ADR-0061: Product-scoped platform AI for B2C rental

Status

Accepted (2026-08-29)

Tags

rental, ai, access-gate, usage-accounting, multi-tenancy, schema, b2c, adr-0055, adr-0006

Decision

The AI Access Gate gains a second authorization scope, product, alongside the existing organization scope. Rental’s payment-proof extraction authorizes with product_key = 'rental' instead of an organization ID.
  • One ai_product_configs row per product holds enabled, the platform provider/model, and the monthly call/token caps and counters. The rental row ships disabled and cannot be enabled without a platform-eligible, vision-capable model.
  • Product calls keep mode = platform — Gremlin pays the provider. product_key is what distinguishes sponsored B2C use from an organization’s platform subscription, so no new mode is introduced.
  • ai_access_events and ai_usage carry both organization_id (now nullable) and product_key, with a CHECK on each table requiring exactly one to be present.
  • Product authorization reuses the global kill-switch, model catalog, platform key resolver, provider runner, prompt service, and usage rollups. It does not lazy-provision an organization, evaluate a subscription, or decrypt BYOK credentials.

Why

Rental is B2C. A Landlord and a Tenant are global users with no organization (ADR-0055, CONTEXT.md → Landlord/Tenant), but AccessGate.Authorize requires an organization ID. Something had to give, and the alternatives all corrupted a boundary that the rest of the platform depends on.

Considered options

  • A synthetic Rental organization (one fixed UUID) — rejected. Tiny in code, wrong in meaning: every landlord’s configuration, subscription, and usage would merge into one fake business tenant, and every organization report would silently include B2C traffic. It also teaches the next feature that inventing an organization is the way out.
  • Landlord BYOK — rejected. BYOK credentials hang off ai_configs.organization_id. Attaching a landlord’s key there means inventing an organization for a person.
  • A separate AI path for Rental (reusing the legacy OCRExtract route) — rejected. It can reach vision providers, but it bypasses the Access Gate contract and current usage accounting, giving feature modules a second, ungoverned way to reach a provider.
  • A sentinel product_key = '' on organization rows, to keep the column NOT NULL — rejected. That is the synthetic-organization trick again, one column across.

Consequences

  • Uniqueness must become per-scope. ai_usage’s UNIQUE (organization_id, usage_date, provider, model, feature) cannot survive a nullable organization_id: Postgres treats NULLs as distinct, so product rows would never conflict and the accumulating upsert would silently insert a new row per call instead of adding to one. The constraint is replaced by two partial unique indexes — one WHERE organization_id IS NOT NULL, one WHERE product_key IS NOT NULL — and the repository carries one upsert per scope, each naming its own predicate in ON CONFLICT. The organization path keeps exactly the key it has today.
  • ai_access_events.decision gains two values, denied_product_disabled and denied_product_cap_exceeded. denied_platform_cap_exceeded stays organization-specific, so existing reports filtering on it do not start counting B2C denials.
  • Reports need their own index. ai_usage_feature_idx is (organization_id, feature, usage_date DESC); product reporting gets the matching (product_key, feature, usage_date DESC) index rather than scanning a growing table.
  • The product scope is reusable by later B2C Rental features without forcing Landlords or Tenants into an organization. It is deliberately not a general quota subsystem: per-user limits stay in the owning feature module (slice 4 caps AI attempts per tenancy per day).
  • Every future writer of ai_usage or ai_access_events must set exactly one scope. The CHECK constraints make that a database error rather than a reporting mystery.
Design detail: docs/superpowers/specs/2026-08-28-rental-platform-slice4-tenancy-payments-ai-design.md §4.7, §5.1, §6.8.