feat(spaces): add spaces v1 vertical slice

Author: Mr-Dark-debug

docs/05-ui-ux-delta.md

@@ -9,8 +9,11 @@
 ## 2. Component Inventory (New & Updated)
 | Component | Type | Status | Notes |
 | --- | --- | --- | --- |
-| `SpaceHeader` | Server component | New | Displays space branding, rules CTA, join/leave actions, feature-flag aware. |
+| `SpaceHeader` | Client component | New | Displays space branding, rules CTA, join/leave actions, feature-flag aware. |
+| `SpaceShell` | Client component | New | Wraps header, membership panel, and rules editor for `spaces_v1` detail page. |
 | `SpaceRolePill` | Client component | New | Shows member role, tooltip with privileges. |
+| `MembershipPanel` | Client component | New | Organizer approval dashboard for pending requests with keyboard-accessible actions. |
+| `CreateSpaceForm` | Client component | New | Organizer-only creation flow with zod-backed validation and feature flag guard. |
 | `ContentComposer` | Client component | Updated | Modular editor supporting Article/Discussion/Q&A/Event/Workshop templates with plugin architecture. |
 | `TemplatePickerModal` | Client component | New | Allows selecting space-level templates with previews and accessibility hints. |
 | `ModerationQueueTable` | Client component | Updated | Adds filters for queue type, bulk actions, SLA indicators. |
@@ -47,10 +50,12 @@ Tokens are declared in `tailwind.config.js` and consumed within `src/components/
 - For events, include accessibility notes (wheelchair access, ASL availability) and ensure color-coded statuses have text equivalents.
 - Implement reduced motion mode for animations in reputation celebrations and feed transitions.
 - RBAC Role Manager exposes live search and roster list with `aria-live="polite"` status updates and keyboard-visible focus rings tied to `brand.focus`.
+- Space Shell components expose join actions with `aria-disabled`, focus-visible outlines, and announce success/error via inline status banners that meet contrast ratios.
 
 ### 4.1 Accessibility Validation Checklist — 2025-11-07
 - ✅ `tests/e2e/admin-role-manager.spec.ts`: Axe scan (`@axe-core/playwright`) focused on the role manager section verifies no WCAG 2.1 AA violations when `rbac_hardening_v1` is enabled for staff.
 - ✅ `tests/e2e/nav-ia.spec.ts`: Confirms skip-link/focus states on the new navigation hubs (`nav_ia_v1`) and asserts hub visibility per role gate.
+- ⚠️ `tests/e2e/space-shell.spec.ts` (planned): Axe scan will cover `SpaceShell` header + membership panel to confirm join buttons announce state changes and tab order matches visual layout once Playwright fixtures land.
 - ⚠️ Publish flow axe validation deferred to Phase-2 composer overhaul; current admin table relies on legacy markup and is tracked in MOD-001 follow-up.
 - Keyboard walkthroughs recorded in `/docs/operations/runbooks/rls-denial-spike.md` appendix to ensure moderators can assign roles without pointer devices.
 

docs/06-data-model-delta.md

@@ -4,9 +4,9 @@
 | Table | Purpose | Key Columns | Notes |
 | --- | --- | --- | --- |
 | `spaces` | Defines communities with branding and governance metadata | `id`, `slug`, `name`, `description`, `visibility`, `rules`, `created_by`, `feature_flags`, `created_at`, `updated_at` | `slug` unique; `feature_flags` JSONB for space-level toggles |
-| `space_members` | Maps users to spaces with roles and status | `space_id`, `profile_id`, `role`, `status`, `invited_by`, `joined_at`, `last_active_at` | Composite PK (`space_id`, `profile_id`); status enum (pending, active, banned) |
-| `space_rules` | Structured rules/flairs/templates | `id`, `space_id`, `type`, `value`, `position` | `type` enum (rule, flair, template, automod) |
-| `post_templates` | Stores reusable template metadata | `id`, `space_id`, `content_type`, `title`, `body`, `config` | `config` JSONB for form fields, required sections |
+| `space_members` | Maps users to spaces with roles and status | `space_id`, `profile_id`, `role_id`, `role_slug`, `status`, `requested_at`, `decision_at`, `joined_at`, `last_active_at` | Composite PK (`space_id`, `profile_id`); `status` enum (`pending`, `active`, `banned`); `role_slug` maintained via trigger |
+| `space_rules` | Structured rules/flairs/templates | `id`, `space_id`, `title`, `body`, `kind`, `value`, `position` | `kind` enum (`rule`, `flair`, `template`, `automod`); JSONB `value` stores config |
+| `post_templates` | Stores reusable template metadata | `id`, `space_id`, `content_type`, `title`, `body`, `config` | `content_type` enum (`article`, `discussion`, `qa`, `event`, `workshop`); `config` JSONB for form fields |
 | `post_versions` | Version history for posts | `id`, `post_id`, `version_number`, `content`, `metadata`, `created_by`, `created_at` | Add `content` as JSONB to support editor structure |
 | `questions` | Extends posts for Q&A | `post_id`, `accepted_answer_id`, `bounty_amount`, `bounty_currency`, `bounty_expires_at` | `post_id` FK to `posts`; `accepted_answer_id` references `answers` table |
 | `answers` | Stores answers for Q&A posts | `id`, `question_id`, `body`, `author_id`, `is_accepted`, `created_at`, `updated_at` | Add index on (`question_id`, `is_accepted`) |
@@ -23,6 +23,7 @@
 
 > 2025-10-24: Created baseline `audit_logs` table with service-role write policy and admin read access to support SEC-001 guard telemetry.
 > 2025-10-31: Hardened SEC-001 scope with community scaffolding. Added `spaces` (slug, name, visibility, created_by, timestamps), `space_members` (space_id, profile_id, role_id, status, joined_at, last_seen_at), `space_rules` (space_id, title, body, created_by, timestamps), `post_versions` (post_id, version_number, content JSONB, metadata JSONB, created_by, created_at), and `reports` (reporter_profile_id, subject_type/id, reason, status, space_id, timestamps). Added helper functions `normalize_role_slug`, `highest_role_slug`, `user_space_role_at_least` to back policies.
+> 2025-11-07: MOD-001 expansion introduced `feature_flags` JSONB + optional banner imagery on `spaces`, normalized `space_membership_status` to `pending|active|banned`, added `role_slug`/`requested_at`/`decision_at` columns with sync trigger on `space_members`, extended `space_rules` with `kind` enum + JSONB `value`, created `content_template_type` enum + `post_templates` table, and added `space_members_pending_idx` / `audit_logs_space_*` indexes. Policy `Members request access` now allows self-service join requests gated to `status='pending'`.
 
 ### Index & Policy Update — 2025-10-31
 

docs/07-security-privacy.md

@@ -31,6 +31,8 @@ Full matrix with endpoint mapping maintained alongside Supabase policy definitio
 
 **Admin Guard Hardening:** Unified admin API routes now delegate to `requireAdmin` in `src/lib/auth/require-admin.ts`, which resolves canonical roles, audits denials via `audit_logs`, and emits `authz_denied_count{resource,role,space,reason}`. Guard usage now extends to user management and gamification APIs, ensuring telemetry tags include `resource`, `role`, `space`, `reason` for Operations dashboards. RLS helper functions (`normalize_role_slug`, `user_space_role_at_least`, `highest_role_slug`) back deny-by-default policies across `spaces`, `space_members`, `space_rules`, `posts`, `post_versions`, `comments`, `reports`, `feature_flags`, and `audit_logs`. The role manager UI behind `rbac_hardening_v1` surfaces canonical badges, enforces audit logging on each mutation, and is covered by synthetic navigation tests plus axe scans.
 
+**Space Guard Enhancements (2025-11-07):** Introduced `requireRole` and `requireSpaceRole` helpers under `src/lib/auth/` to unify canonical-role enforcement across Phase-2 APIs. `requireRole` gates global actions (e.g., space creation) while `requireSpaceRole` validates per-space membership, emits `authz_denied_count{resource,role,space,reason}`, and logs denials with structured metadata. Supabase policies now include `Members request access` to allow self-service join requests gated to `status='pending'`; organizers/moderators approve via audited endpoints that record `space_join_approval_latency_ms` telemetry. API routes under `/api/spaces` use these guards and server spans to preserve RLS invariants before mutating Supabase tables.
+
 **Runbook – RLS Denial Spike (2025-10-31):** If `authz_denied_count` surges, check Operations dashboard panel `op_rbac_denials` for `resource` + `space` tags. Use `/admin/audit` to confirm actor role assignments and `feature_flag_audit` for recent flag toggles. Validate helper functions are returning canonical slugs via Supabase SQL (`select public.highest_role_slug('<profile-id>'::uuid)`). Rollback: toggle `rbac_hardening_v1` off, apply migration `0020_sec_001_rls_policies.down.sql`, restore from PITR if required. Document investigation outcomes in `/docs/operations/runbooks/rls-denial-spike.md`.
 
 ## 3. Input Validation & Sanitization

docs/08-observability.md

@@ -20,11 +20,13 @@
 | `authz_denied_count` | Authorization failures | Counter | `resource`, `role`, `space` |
 | `flag_evaluation_latency_ms` | Feature flag evaluation | Histogram | `flag_key` |
 | `nav_interaction_total` | Nav hub clicks (flag cohorts) | Counter | `target`, `from`, `variant`, `role` |
+| `space_creation_success_rate` | Organizer space creation success ratio | Gauge | `visibility`, `flag` |
+| `space_join_approval_latency_ms` | Time from request to approval/ban | Histogram | `space_id`, `actor_role` |
 | `webhook_delivery_success_rate` | Webhook successes vs. attempts | Gauge | `event_type` |
 | `automod_trigger_count` | Automod actions per rule | Counter | `rule_type`, `space` |
 
 > 2025-10-31: Added `admin_publish_duration_ms` internal histogram for staff tooling responsiveness and began emitting `content_publish_latency_ms` from `/api/admin/posts`. Structured logs now include `user_id_hash`, `space_id`, and feature flag context for audit correlation. `nav_interaction_total` now captures navigation hub engagement per flag cohort.
-> 2025-11-07: Verified `authz_denied_count{resource,role,space,reason}` increments through synthetic denial (`tests/synthetic/observability.spec.ts`) and confirmed dashboard ingestion within `dash_ops_rbac_v1`.
+> 2025-11-07: Verified `authz_denied_count{resource,role,space,reason}` increments through synthetic denial (`tests/synthetic/observability.spec.ts`) and confirmed dashboard ingestion within `dash_ops_rbac_v1`. Added `space_creation_success_rate` + `space_join_approval_latency_ms` panels to monitor MOD-001 pilot health.
 
 ## 3. Tracing Strategy
 - Instrument Next.js route handlers and server components with OpenTelemetry.
@@ -54,6 +56,7 @@
 | Donation failures spike | `donation_success_rate` < 90% for 15m | Critical | PagerDuty + Finance Slack |
 | Payout errors rising | `payout_error_rate` > 2% for 30m | Critical | PagerDuty + Payments distro |
 | Moderation backlog | `moderation_queue_oldest_min` > 60 | Warning | Slack #safety |
+| Space creation drop | `space_creation_success_rate` < 95% for 15m | Warning | PagerDuty `pd-sec-ops` |
 | Crash-free drop | `crash_free_sessions` < 97% daily | Warning | Slack #frontend |
 | Webhook delivery failures | `webhook_delivery_success_rate` < 95% for 30m | Warning | Slack #integrations |
 
@@ -80,6 +83,7 @@
 - Create `/docs/operations/runbooks/` with scenario-specific guides (publish latency, payment failures, search outage).
 - Each runbook includes detection signals, immediate actions, rollback instructions, communication templates.
 - Link runbooks from dashboards for quick access.
+- New: `/docs/operations/runbooks/space-onboarding-failures.md` documents detection + response for `spaces_v1` creation and membership regressions (ties into `space_creation_success_rate` alert).
 
 ## 10. Data Quality & Telemetry Governance
 - Establish metric naming conventions (`domain_metric_unit`), tag cardinality guidelines, and sampling rules.

docs/09-test-strategy.md

@@ -35,6 +35,7 @@
 - Provide helper to set flag context in tests (`withFeatureFlag('spaces_v1', true)`).
 - CI includes matrix builds for critical flags (Spaces, Commerce, Events).
 - Phase-1 gate suites: `tests/security/rbac-policies.test.ts`, `tests/e2e/admin-role-manager.spec.ts`, `tests/e2e/nav-ia.spec.ts`, `tests/e2e/publish-flow.spec.ts`, and `tests/synthetic/observability.spec.ts` must remain green before enabling Phase-2 flags.
+- Guard coverage expanded with `tests/unit/require-role.test.ts` and `tests/unit/require-space-role.test.ts` to exercise canonical role enforcement for `spaces_v1` APIs prior to e2e rollout.
 
 ## 7. Performance & Load
 - Baseline load test for publish, search, donations, and event checkout before GA.

docs/assumptions.md

@@ -11,6 +11,6 @@
 | A-007 | 2025-02-14 | Observability vendor (Grafana Cloud/Honeycomb) budget approved for Phase 1. | Required to meet telemetry commitments. | Open |
 | A-008 | 2025-02-14 | Legal/compliance resources available before Phase 3 commerce rollout. | Necessary for payments, KYC, events. | Open |
 | A-009 | 2025-10-24 | Design Lead owns `nav_ia_v1` rollout and SRE Lead owns `observability_v1` feature flag. | Owners not specified in release plan source; assigned to align with product area leads for accountability. | Open |
-| A-010 | 2025-10-31 | `space_membership_status` enum values (`active`, `invited`, `suspended`) are sufficient for Phase-1 moderation workflows. | SEC-001 scope only requires basic lifecycle states; additional states can be added with reversible migrations later. | Open |
+| A-010 | 2025-10-31 | `space_membership_status` enum will cover base lifecycle states only. | SEC-001 scope required minimal workflow coverage; Phase-2 migration (`0022_spaces_core.sql`) renamed values to `pending|active|banned` and added join metadata. | Closed |
 | A-011 | 2025-10-31 | Dashboard identifiers `dash_exec_kpi_v1` and `dash_ops_rbac_v1` will be provisioned by analytics; used as placeholders for documentation until Grafana workspace ready. | No IDs provided in spec; chosen to unblock observability references and can be updated post-provisioning. | Open |
 | A-012 | 2025-11-07 | Dedicated Supabase project + JWT fixtures available for automated RLS matrix tests (`RBAC_TEST_*` env vars). | Integration coverage depends on server-issued tokens; assumed staging security team refreshes monthly and shares via secure channel. | Open |

docs/operations/runbooks/space-onboarding-failures.md

@@ -0,0 +1,68 @@
+# Runbook: Space Onboarding Failures
+
+_Last updated: 2025-11-07_
+
+## Purpose
+Spaces v1 introduces space creation, membership approval, and rule governance behind the `spaces_v1` feature flag. This runbook covers how to triage and resolve failures when organizers cannot create spaces or when membership requests stall.
+
+## Preconditions
+- `spaces_v1` enabled for the current environment.
+- Supabase migrations `0022_spaces_core.sql` and `0023_space_audit.sql` applied successfully.
+- Operations dashboard panels `dash_ops_rbac_v1` (authz denials) and `dash_ops_nav_v1` (nav interactions) reachable.
+
+## Detection
+1. **Alert:** `pd-sec-ops::space_creation_drop` fires when `space_creation_success_rate` falls below 95% over 15 minutes.
+2. **Support Ticket:** Organizers report 4xx errors from `/api/spaces` or members see stale "Request pending" messages.
+3. **Dashboard Signal:** `space_join_approval_latency_ms` histogram shows sustained latency > 5 minutes.
+
+## Immediate Actions
+1. **Confirm Feature Flag**
+   ```sql
+   select flag_key, enabled from public.feature_flags where flag_key = 'spaces_v1';
+   ```
+   - If `enabled=false`, toggle for staff cohort only via admin console; document reason in `feature_flag_audit`.
+2. **Check Audit Logs**
+   ```sql
+   select created_at, actor_role, action, metadata
+   from public.audit_logs
+   where resource in ('space', 'space_membership')
+   order by created_at desc limit 20;
+   ```
+   - Missing entries suggest API guard failures; inspect application logs for `requireRole`/`requireSpaceRole` errors.
+3. **Validate Policies**
+   ```sql
+   select *
+   from pg_policies
+   where tablename in ('spaces', 'space_members')
+   order by tablename, policyname;
+   ```
+   - Ensure `Members request access` exists; if missing, re-run migration `0022_spaces_core.sql`.
+4. **Review Telemetry**
+   - `authz_denied_count{resource="space"}` spikes indicate guard denials; inspect tags for `reason` (`no_session`, `inactive_membership`, etc.).
+   - `space_join_approval_latency_ms` > target implies organizer backlog; confirm moderators are online.
+
+## Remediation Steps
+- **Creation Failing with 5xx:**
+  - Check Supabase RPC quota; ensure `feature_flags` default metadata is valid JSON.
+  - Confirm `requireRole` returns `organizer` or higher. Grant temporary organizer role via Role Manager UI if necessary.
+- **Join Requests Stuck Pending:**
+  - Ensure `space_members.role_slug` trigger active. Recreate trigger with:
+    ```sql
+    call public.space_members_set_role_slug();
+    ```
+  - Verify organizers receive notifications; check nav interaction logs for `/spaces` traffic.
+- **Audit Entries Missing:**
+  - Re-deploy `/api/spaces` routes; confirm `writeAuditLog` calls succeed (service key valid).
+
+## Escalation
+- If Supabase schema drift detected, page Database On-Call and prepare PITR window.
+- For repeated authz denials > 10/min, escalate to Security Lead; consider temporarily disabling `spaces_v1`.
+
+## Verification
+- Create test space (`spaces_v1` staging cohort) and complete join→approve flow using staff accounts.
+- Confirm `space_creation_success_rate` returns above 99% and new audit rows appear with `resource='space_membership'`.
+- Run Playwright smoke for Space Shell (when available) to validate accessibility checks.
+
+## Postmortem Notes
+- Document root cause, mitigation, and follow-up tasks in `/docs/progress/weekly-YYYY-MM-DD.md` and backlog.
+- Evaluate whether additional alerts or dashboards are required (e.g., backlog of pending members per space).

docs/progress/weekly-2025-10-24.md

@@ -5,16 +5,19 @@
 - UX-010: Navigation IA & design tokens applied to top nav and admin role tooling behind `nav_ia_v1`.
 - OBS-100: Observability baseline instrumentation (nav interaction metrics, synthetic journeys, structured logging enrichments) behind `observability_v1` UI surfaces.
 - Phase-1 Gate Validation: Added integration (`tests/security/rbac-policies.test.ts`) and Playwright suites (`tests/e2e/*.spec.ts`, synthetic denial checks) plus rollback rehearsal notes to unblock Phase-2 kickoff.
+- MOD-001 (Spaces v1) vertical slice kickoff: migrations `0022_spaces_core.sql`/`0023_space_audit.sql`, `/api/spaces` CRUD/membership endpoints, and `SpaceShell` UI shipped behind `spaces_v1`.
 
 ## Flags Enabled
 - `rbac_hardening_v1`: Staff-only in staging for Role Manager validation.
 - `nav_ia_v1`: Staff-only cohort to evaluate hub engagement.
 - `observability_v1`: SRE sandbox only; dashboards linked but UI gates remain off for general users.
+- `spaces_v1`: OFF for public; staff-only cohorts will pilot once e2e smoke stabilizes.
 
 ## KPI Deltas
 - `authz_denied_count` trending flat (≤2/min) after Role Manager smoke tests.
 - `nav_interaction_total` baseline captured for staff navigation (~35 clicks/hour) to tune IA.
 - `content_publish_latency_ms` P95 steady at 4.2s post-instrumentation.
+- `space_creation_success_rate` baseline recorded at 100% (single organizer flow via staging cohort); `space_join_approval_latency_ms` initial approval latency 42s (target <60s).
 - Publish flow trace headers validated via `tests/e2e/publish-flow.spec.ts` (median 3.6s end-to-end, traceparent header asserted).
 
 ## New Risks / Assumptions
@@ -24,6 +27,6 @@
 
 ## Next Targets
 - Harden Storybook coverage for tokenized components (SpaceHeader, TemplatePickerModal, DonationWidget, EventCard).
-- Expand RLS integration tests to cover reports/audit log mutations with moderator/admin roles.
+- Expand RLS integration tests to cover reports/audit log mutations with moderator/admin roles plus new `space_members` pending policy.
 - Connect dashboards to production Grafana workspace and validate alert routing (`pd-sec-ops`, `ops-telemetry`).
-- Begin MOD-001 vertical slice (schema + API planning) once Phase-1 gate marked green.
+- Finalize spaces Playwright coverage (`tests/e2e/space-shell.spec.ts`) and polish Storybook tokens before enabling staff pilot.