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-0006Decision
The AI Access Gate gains a second authorization scope, product, alongside the existing organization scope. Rental’s payment-proof extraction authorizes withproduct_key = 'rental' instead of an organization ID.
- One
ai_product_configsrow per product holdsenabled, the platform provider/model, and the monthly call/token caps and counters. Therentalrow ships disabled and cannot be enabled without a platform-eligible, vision-capable model. - Product calls keep
mode = platform— Gremlin pays the provider.product_keyis what distinguishes sponsored B2C use from an organization’s platform subscription, so no new mode is introduced. ai_access_eventsandai_usagecarry bothorganization_id(now nullable) andproduct_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
OCRExtractroute) — 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’sUNIQUE (organization_id, usage_date, provider, model, feature)cannot survive a nullableorganization_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 — oneWHERE organization_id IS NOT NULL, oneWHERE product_key IS NOT NULL— and the repository carries one upsert per scope, each naming its own predicate inON CONFLICT. The organization path keeps exactly the key it has today. ai_access_events.decisiongains two values,denied_product_disabledanddenied_product_cap_exceeded.denied_platform_cap_exceededstays organization-specific, so existing reports filtering on it do not start counting B2C denials.- Reports need their own index.
ai_usage_feature_idxis(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_usageorai_access_eventsmust set exactly one scope. The CHECK constraints make that a database error rather than a reporting mystery.
docs/superpowers/specs/2026-08-28-rental-platform-slice4-tenancy-payments-ai-design.md §4.7, §5.1, §6.8.