P125 — AIEP — Subscription and Billing Protocol
Publication Date: 2026-03-01 Status: Open Source Prior Art Disclosure Licence: Apache License 2.0 Author/Organisation: Phatfella Ltd Schema: AIEP_OS_SPEC_TEMPLATE v1.0.1 — https://aiep.dev/schemas/aiep-os-spec-template/v1.0.1
Framework Context
[0001] This disclosure operates within an Architected Instruction and Evidence Protocol (AIEP) environment as defined in United Kingdom patent application number GB2519711.2, filed 20 November 2025, and GB2519798.9, filed 20 November 2025, the entire contents of which are incorporated herein by reference.
[0002] The present disclosure defines a subscription and billing protocol for AIEP-compliant SaaS deployments — a mechanism by which tenant subscription plans govern access to evidence substrate capabilities, and by which subscription state changes are committed as governed lifecycle artefacts in the tenant ledger.
Field of the Disclosure
[0003] This disclosure relates to governed artificial intelligence SaaS substrates that gate access to evidence substrate features and capacity limits based on a tenant’s active subscription tier, and that handle subscription lifecycle events — creation, upgrade, downgrade, cancellation, and renewal — as auditable committed artefacts.
[0004] More particularly, the disclosure concerns a Stripe-integrated subscription protocol with: a Subscription Plan schema defining capability entitlements; a tenant plan store binding each tenant to their current plan and its entitlements; a webhook handler committed subscription lifecycle events to the tenant ledger; and an Artefact KV Cache mechanism that provides evidence performance enhancement as a plan-gated feature.
Background
[0005] SaaS deployments of evidence substrates require capability gating: higher-tier plans should unlock larger evidence windows, higher concurrency limits, advanced provenance classes, and export features. Existing SaaS billing integrations: (a) gate features by database flag without committing the state change as an auditable artefact; (b) provide no record of capability limits in effect at a given point in time; and (c) cannot prove to an auditor what tier was active when a given AI response was generated.
Summary of the Disclosure
[0006] A SubscriptionPlan record defines the capability entitlements for a tier. Plan fields include: plan_id; plan_name; max_evidence_tokens (P117 unburdening parameter upper bound); max_session_memory_turns (P118 KV memory window); bulk_ingestion_max_items (P123 batch size limit); computer_use_enabled boolean (P121 surface); export_enabled boolean (P120 output); delta_feeds_max (P123 subscription count); and artefact_cache_enabled boolean.
[0007] The Artefact KV Cache is a plan-gated performance layer. When enabled, EvidenceRef artefacts retrieved and normalised in a session are stored in Cloudflare KV keyed by content_hash. On subsequent sessions, a cache check is performed before retrieval: if the content_hash for a target URL is already in the cache and the cached artefact is within the tenant’s staleness threshold, the cached artefact is returned without re-fetching. The cache entry comprises: the full EvidenceRef object; a chain_id linking it to the session that first retrieved it; a cached_at timestamp; and a cache_hash.
[0008] The Subscription Lifecycle Handler processes Stripe webhook events. Handled event types: customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, invoice.payment_succeeded, invoice.payment_failed. For each event, a SubscriptionLifecycleArtefact is committed to the tenant ledger comprising: event_type; tenant_id; plan_id; effective_at; stripe_event_id; and a lifecycle_hash — SHA-256 over the artefact in canonical JSON form.
[0009] The webhook handler validates Stripe webhook signatures using the Stripe-Signature header and the tenant’s webhook secret before processing. Events with invalid signatures are rejected with a 400 response and logged as security events. Events are idempotent: duplicate events (same stripe_event_id) are detected and skipped without re-committing the lifecycle artefact.
[0010] On subscription.deleted or payment_failed (after retry exhaustion), the tenant’s plan is downgraded to the free tier. Active sessions are not interrupted; the new capability limits take effect on the next session creation. A plan_change_at field on the session record enables auditors to identify sessions that straddled a plan transition.
[0011] The plan_id active at the time of each AI response is recorded on the response’s message record in the Evidence Ledger. This enables auditors to verify that the capabilities used to generate a response (evidence token budget, export, computer-use) were within the entitlements of the active plan at generation time.