{
  "agent": "04/20",
  "title": "Unified contract: plan features + staff roles + legacy",
  "status": "design_only",
  "version": "1.0.0",
  "coordinates_with": [
    "docs/admin-roles-support/01-ux-research.md",
    "docs/admin-roles-support/02-current-inventory.md",
    "docs/admin-roles-support/03-roles-matrix.md",
    "docs/admin-roles-support/03-roles-matrix.json",
    "docs/plan-permissions/03-permission-contract.md",
    "docs/plan-permissions/03-permission-contract.json",
    "docs/plan-permissions/01-feature-keys.json",
    "docs/plan-permissions/06-defaults-matrix.json"
  ],
  "assumptions": [
    "Product cohort (legacy/standard/custom) is a plan feature_profile, not a stored end-user RBAC role; legacy_user/standard_user are derived labels",
    "support_staff is least privilege: ticket queue assign/reply only — narrower than optional read-assist in 03",
    "packages ≡ plans rows; no parallel permission service outside billing + auth staff flags",
    "is_platform_admin retained; staff_role additive with null+admin-flag ⇒ staff_role admin back-compat",
    "A1/Local Demo Co Enterprise → Legacy assign is explicit ops step, not silent migration"
  ],
  "axes": {
    "plan_features": {
      "subject": "company.active_plan",
      "storage": ["plans.features", "plans.feature_profile", "platform_feature_gates"],
      "resolver": "ResolveEffectiveFeatures / CapabilitiesForCompany",
      "failure": { "http": 402, "code": "plan_gate" }
    },
    "company_membership": {
      "subject": "user in company",
      "storage": "memberships.role",
      "values": ["admin", "member"],
      "notes": "Orthogonal; do not overload with platform admin"
    },
    "platform_staff": {
      "subject": "user",
      "storage": ["users.is_platform_admin", "users.staff_role"],
      "resolver": "resolve_staff_role + staff_allows(capability)",
      "failure": { "http": 403, "error": "staff capability required" }
    }
  },
  "runtime_formulas": {
    "effective_feature": "plan_allows(key) AND global_section_enabled(section(key)) AND global_feature_enabled(key)",
    "plan_allows": [
      "if key in plans.features -> plans.features[key]",
      "else if resolve_plan_profile == legacy -> LegacyMatrix[key] (missing -> false)",
      "else if resolve_plan_profile == custom -> true",
      "else -> DefaultPlanFeatures(name, false)[key]"
    ],
    "resolve_plan_profile_priority": [
      "plans.feature_profile if set (legacy|ladder|custom)",
      "legacy name patterns from 03-roles-matrix",
      "IsCustomPackage -> custom",
      "else ladder"
    ],
    "staff_allows": "user.is_active AND resolve_staff_role(user) in allowed_roles(capability)",
    "resolve_staff_role": [
      "inactive -> none",
      "staff_role if not null",
      "else if is_platform_admin -> admin",
      "else none"
    ]
  },
  "legacy": {
    "profile": "legacy",
    "shipping_modes": [
      {
        "id": "named_profile",
        "preferred": true,
        "mechanism": "plans.feature_profile='legacy' or name-pattern derive; DefaultPlanFeatures/LegacyMatrix"
      },
      {
        "id": "sparse_or_dense_features",
        "preferred": false,
        "mechanism": "plans.features explicit map; requires profile precedence so missing keys are not custom-all-on"
      }
    ],
    "must_not": "Fall through IsCustomPackage all-ON for A1/legacy names",
    "allowlist_authority": "docs/admin-roles-support/03-roles-matrix.md",
    "excluded_sections": [
      "processing.monitor",
      "stores.*",
      "marketing.*",
      "integrations.*",
      "support.*"
    ],
    "name_patterns_ref": "docs/admin-roles-support/03-roles-matrix.json#plan_name_patterns",
    "a1_example": {
      "legacy_company_id": "97e1a309-3d23-4aa2-b518-8e8d7afdfec7",
      "demo_note": "Local Demo Co may still be on Enterprise until explicit Legacy assign"
    }
  },
  "staff_roles": {
    "values": ["admin", "developer", "support_staff"],
    "storage": {
      "keep": "users.is_platform_admin",
      "add": {
        "column": "users.staff_role",
        "type": "TEXT NULL CHECK IN (admin, developer, support_staff)",
        "invariant": "staff_role set implies is_platform_admin=true"
      }
    },
    "backfill": "UPDATE users SET staff_role='admin' WHERE is_platform_admin AND staff_role IS NULL",
    "capabilities": {
      "staff.admin_shell": ["admin", "developer", "support_staff"],
      "staff.support.queue": ["admin", "developer", "support_staff"],
      "staff.support.reply": ["admin", "developer", "support_staff"],
      "staff.support.assign": ["admin", "developer", "support_staff"],
      "staff.users.read": ["admin", "developer"],
      "staff.users.write": ["admin", "developer"],
      "staff.analytics": ["admin", "developer"],
      "staff.billing": ["admin", "developer"],
      "staff.plans_features": ["admin", "developer"],
      "staff.feature_gates": ["admin", "developer"],
      "staff.settings": ["admin", "developer"],
      "staff.jobs_stuck": ["admin", "developer"],
      "staff.impersonate": ["admin", "developer"],
      "staff.dev_password": ["admin", "developer"]
    },
    "support_staff_least_privilege": {
      "allowed_web": ["/admin/support", "/admin/support/[id]"],
      "allowed_api": [
        "GET /api/admin/support/tickets",
        "GET /api/admin/support/tickets/{id}",
        "POST /api/admin/support/tickets/{id}/messages",
        "PATCH /api/admin/support/tickets/{id}"
      ],
      "denied": [
        "billing",
        "plans",
        "feature_gates",
        "credits",
        "settings",
        "users_write",
        "impersonate",
        "stuck_cleanup",
        "self_escalate_staff_role"
      ],
      "deferred": "ticket-side read-only company context without tenant write APIs"
    },
    "middleware": {
      "prefer": ["RequireStaff", "RequireStaffCapability"],
      "extend": [
        "apps/api/internal/httpapi/middleware.go#RequirePlatformAdmin",
        "apps/api/internal/httpapi/middleware.go#checkPlatformAdmin",
        "apps/api/internal/auth/invites.go#IsPlatformAdmin"
      ],
      "router_today": "apps/api/internal/httpapi/server.go /api/admin RequireSession+RequirePlatformAdmin",
      "ui": [
        "apps/web/src/lib/admin-gate.ts",
        "apps/web/src/lib/components/AdminNav.svelte"
      ]
    }
  },
  "security": {
    "session": "scs cookie + RequireSession; staff flags from DB not client claims",
    "csrf": "double-submit X-CSRF-Token on dashboard /api including /api/admin; v1/public/webhooks exempt",
    "company_isolation": [
      "tenant APIs RequireCompany scoped",
      "admin support cross-company ticket view does not open tenant write APIs",
      "impersonate admin|developer non-prod only; never support_staff",
      "allowCompanyAdminOrPlatform: only admin|developer count as platform bypass — not support_staff"
    ],
    "no_privilege_escalation": [
      "capability middleware on admin routes",
      "no self-service staff_role",
      "plan features never grant /admin",
      "staff never granted by plan JSON",
      "fail closed on missing role/capability"
    ]
  },
  "performance": {
    "existing": {
      "symbol": "featureETag",
      "path": "apps/api/internal/billing/plan_features.go",
      "semantics": "sha256 of sorted enabled feature keys"
    },
    "rules": [
      "Do not fold staff_role into feature_etag",
      "Keep company capabilities cache keyed by company_id + feature_etag",
      "Invalidate on plan assign, plans.features write, global gates write",
      "etag remains pure function of effective enabled-key set (profile already reflected in map)",
      "Resolve staff role once per request in middleware"
    ],
    "me_payload_additive": {
      "user.staff_role": "string|null",
      "staff_capabilities": "string[]",
      "credits.feature_profile": "legacy|ladder|custom|null",
      "credits.feature_etag": "unchanged semantics"
    }
  },
  "migration": {
    "file_suggestion": "apps/api/sql/schema/027_staff_roles_legacy_profile.sql",
    "idempotent": true,
    "destructive": false,
    "steps": [
      "ALTER users ADD staff_role NULL CHECK",
      "ALTER plans ADD feature_profile NULL CHECK",
      "Backfill staff_role=admin for existing platform admins",
      "Ensure Legacy plan row with feature_profile=legacy",
      "Optional sparse plans.features from LegacyMatrix",
      "Explicit A1/demo assign — no silent Enterprise downgrade",
      "EnsureDefaultPlans must not clobber features or feature_profile"
    ],
    "optional_flag": "STAFF_RBAC=1 to enforce capability middleware",
    "breaking_changes": [],
    "preserve": [
      "is_platform_admin",
      "public ladder names",
      "Stripe public-ladder checkout",
      "402 plan_gate shapes",
      "support assignee_admin_user_id schema",
      "CSRF session behavior"
    ]
  },
  "reuse_symbols": {
    "billing": [
      "DefaultPlanFeatures",
      "SparseDefaultOverrides",
      "IsCustomPackage",
      "PlanAllowsFeature",
      "ResolveEffectiveFeatures",
      "CapabilitiesForCompany",
      "featureETag",
      "EntitlementsForCompany"
    ],
    "auth_http": [
      "IsPlatformAdmin",
      "RequirePlatformAdmin",
      "checkPlatformAdmin",
      "CSRF",
      "RequireSession",
      "allowCompanyAdminOrPlatform"
    ],
    "support": [
      "ListAdmin",
      "GetAdmin",
      "ReplyAsAgent",
      "UpdateAdmin",
      "handleAdminListSupportTickets"
    ],
    "web": [
      "requirePlatformAdmin",
      "AdminNav",
      "PlanPermissionsPanel",
      "planCapabilities",
      "Nav.svelte"
    ]
  },
  "do_not_add": [
    "parallel permissions package outside billing/auth",
    "packages table",
    "tenant feature_keys for /admin/*",
    "mixing LLM admin-ai-roles into staff RBAC",
    "staff fields inside feature_etag"
  ],
  "verification": [
    "legacy excludes processing/stores/marketing/integrations/support",
    "A1/legacy profile not custom-all-on",
    "custom non-legacy still all-on",
    "ladder Free/Starter denials unchanged",
    "null staff_role + is_platform_admin => admin",
    "support_staff 403 on billing/plans/settings",
    "support_staff AdminNav Support-only",
    "CSRF still on admin mutations",
    "feature_etag stable across staff_role-only changes",
    "tenant APIs remain company-scoped for support_staff"
  ],
  "open_questions_defaults": {
    "a1_demo_cutover": "explicit_ops_assign",
    "support_staff_sets_is_platform_admin": true,
    "company_admin_platform_bypass": "admin_and_developer_only",
    "legacy_seed_density": "profile_first_sparse_optional"
  }
}