Project subscriptions into StarIntel entitlements and quotas #4

New issue

Open

opened 2026-08-25 10:53:57 +00:00 by lost-rob0t · 1 comment

lost-rob0t commented

2026-08-25 10:53:57 +00:00

(Migrated from github.com)

Goal

Turn canonical billing/subscription state from #1 into a narrow, auditable entitlement model that StarIntel services can enforce without understanding Stripe or crypto-provider details.

Model

Define stable entitlement concepts for at least:

plan/product -> entitlement set
feature/capability grant
quantitative quota/limit
effective-from / effective-until
grace period
suspension/revocation
trial/promo/manual grant where explicitly supported
source billing/subscription revision

Requirements

Billing state and authorization remain separate domains: payment providers never directly grant API scopes or mutate StarIntel auth records.
Build an idempotent projection from canonical subscription state into effective entitlements.
Make grants/revocations monotonic with an explicit revision/version so stale webhook or replayed provider events cannot resurrect old access.
Define behavior for active, trialing, past-due, grace-period, canceled-at-period-end, canceled, refunded/reversed, disputed, and manually suspended states.
Quotas are exact and machine-readable: e.g. API/search/agent/run/storage limits where later products define them. Do not invent commercial numbers in this issue.
Support account-level and, if current StarIntel tenancy requires it, organization/tenant-level entitlements without conflating identities.
Provide an authenticated internal query/check API or library contract: entitlements(account), allowed?(account, capability), and quota metadata/current revision.
Cache only with bounded TTL/revision invalidation so revocation propagates predictably.
Every entitlement change produces a structured audit event without exposing payment secrets.
Administrative/manual grants require explicit authority, reason, actor identity, and expiry where applicable.

StarIntel integration

Define the smallest contract starintel-server and other consumers need to enforce paid features. Public /api/v1/capabilities may describe product capabilities generically but must never reveal another customer's plan, billing status, or private entitlement state.

Tests / acceptance

subscription state -> entitlement projection fixtures
stale/out-of-order billing revision cannot restore revoked access
cancellation-at-period-end vs immediate cancellation behavior
failed payment/grace/recovery behavior
refund/dispute/reversal policy fixtures
quota boundary tests and concurrent consumption semantics where usage counters are introduced
manual grant/revoke audit tests
exact-head repo-native verification

Execution mode — AUTO-RAGE

Run the full ADARD/ADADR loop autonomously: inspect #1 and current StarIntel auth/capability/tenant contracts; design and record entitlement semantics; adversarial review + privilege-resurrection/stale-state/quota/account-isolation threat model; autonomous decision gate; TDD-first implementation; exact-head service/integration verification; push a focused branch and open/update a PR targeting main. Stop only for a genuinely unresolved requirement/security blocker, inaccessible dependency, or failed verification gate. Do not ask for approval between phases.

## Goal Turn canonical billing/subscription state from #1 into a narrow, auditable entitlement model that StarIntel services can enforce without understanding Stripe or crypto-provider details. ## Model Define stable entitlement concepts for at least: - plan/product -> entitlement set - feature/capability grant - quantitative quota/limit - effective-from / effective-until - grace period - suspension/revocation - trial/promo/manual grant where explicitly supported - source billing/subscription revision ## Requirements - Billing state and authorization remain separate domains: payment providers never directly grant API scopes or mutate StarIntel auth records. - Build an idempotent projection from canonical subscription state into effective entitlements. - Make grants/revocations monotonic with an explicit revision/version so stale webhook or replayed provider events cannot resurrect old access. - Define behavior for active, trialing, past-due, grace-period, canceled-at-period-end, canceled, refunded/reversed, disputed, and manually suspended states. - Quotas are exact and machine-readable: e.g. API/search/agent/run/storage limits where later products define them. Do not invent commercial numbers in this issue. - Support account-level and, if current StarIntel tenancy requires it, organization/tenant-level entitlements without conflating identities. - Provide an authenticated internal query/check API or library contract: `entitlements(account)`, `allowed?(account, capability)`, and quota metadata/current revision. - Cache only with bounded TTL/revision invalidation so revocation propagates predictably. - Every entitlement change produces a structured audit event without exposing payment secrets. - Administrative/manual grants require explicit authority, reason, actor identity, and expiry where applicable. ## StarIntel integration Define the smallest contract `starintel-server` and other consumers need to enforce paid features. Public `/api/v1/capabilities` may describe product capabilities generically but must never reveal another customer's plan, billing status, or private entitlement state. ## Tests / acceptance - subscription state -> entitlement projection fixtures - stale/out-of-order billing revision cannot restore revoked access - cancellation-at-period-end vs immediate cancellation behavior - failed payment/grace/recovery behavior - refund/dispute/reversal policy fixtures - quota boundary tests and concurrent consumption semantics where usage counters are introduced - manual grant/revoke audit tests - exact-head repo-native verification ## Execution mode — AUTO-RAGE Run the full ADARD/ADADR loop autonomously: inspect #1 and current StarIntel auth/capability/tenant contracts; design and record entitlement semantics; adversarial review + privilege-resurrection/stale-state/quota/account-isolation threat model; autonomous decision gate; TDD-first implementation; exact-head service/integration verification; push a focused branch and open/update a PR targeting `main`. Stop only for a genuinely unresolved requirement/security blocker, inaccessible dependency, or failed verification gate. Do not ask for approval between phases.

lost-rob0t commented

2026-08-25 10:58:58 +00:00

(Migrated from github.com)

Entitlement projection, grace/suspension/cancellation semantics, quotas, revision/cache behavior, and StarIntel enforcement integration docs are tracked in #5. Keep those contracts synchronized with this implementation.