Ontology · domain 5

Commerce — two systems, one law

The binding law (.agents/rules/licensing-separation.md, CTO decision 2026-07-15): there are two licensing systems. KOS signed grants carry entitlement…

16 objects · 0 links · 0 actions

Objects · every one cites its backing source

Subscription

license schema models

status → license status mapping (beta/trialing/wallet_pending → trialing; trial_expired → expired; active → active)

Seat / Machine

machines

install/deployment binding; seat limit; 48h cooldown; max 5 deactivations/month

Grant

activation_grants, offline_grants

Ed25519 wire format b64url(sorted JSON claims).b64url(64-byte sig), v=2; claims incl. features[], valid_until/grace_until/kid/server_time; signer = OpenBao Transit (non-exportable key, legacy id engen-os-license-signing; private key never leaves OpenBao); test-only LocalEd25519Signer

LicenseSession

license token service

narrow JWT (legacy type engen_os_license_session), scopes license:activate|heartbeat|read|manage, non-refreshable, org baked in; never a console JWT

Revocation

revocations table (legacy engen_os_revocations)

operator-side only via admin-portal /internal/admin/license/revoke; seats marked MACHINE_REVOKED; heartbeat surfaces revoked:true

Release/Channel

releases table (legacy engen_os_releases)

GET /api/v1/license/releases/{channel} — public, no credential; R2 artifact_url + sha256 + optional signature

SignedKey ledger

signed-key table (legacy engen_os_license_keys)

revoke-and-reissue of versioned signed keys

Edition

app/edition.py

dev | open-source | commercial, baked at build; structural provider gate, never licensable

Entitlement

app/license.py entitlements()

six axes: projects, teams, AI workers, users, deterministic agents, advanced atoms (manifold_access, byok, harness atoms); effective = max(commercial_floor, grant)

Trial

app/deployment_identity.py + license module

one immutable 9-day evaluation; starts only after full install health gate

DeploymentID

app/deployment_identity.py

durable across reinstall/upgrade

VerifyKeyRing

release-baked Ed25519 public keys

KAIDERA_OS_PRODUCTION_LICENSE_KID=kaidera-os-lic-prod-v1

Wallet

credit_wallets/credit_transactions + credit_service.py

one per org; ledger sums to balance; consume_credits idempotent on (wallet,'consumed',reference); auto-topup; expiry buckets; offboard close

AddOn

subscription_addons, seed_plans.py

units_per_license pricing (e.g. +1 project $199/mo)

EntitlementService

entitlement_service.py

precedence: overrides > add-ons > plan > free-tier

StripeRails

stripe_service.py, webhooks.py

16 webhook event types; checkout; subscriptions incl. send_invoice no-card fallback (14-day due); refunds; credit notes; coupons; Billing Meter llm_token_usage

Notes, laws and mechanics

1. the manifold_access key gate 2. the shared Stripe rails

System A — Kaidera Platform License Authority ("Surface B")

Lives in 02-cust-portal, in the dedicated Kaidera OS license schema (Postgres schema engen_os + role engen_os_app_dml — legacy compatibility namespace until the verified identifier migration; FORCE RLS; migration 104; commercial tables from 115).

Authority endpoints

POST /api/v1/license/login            console email/password ± MFA → license session (rate-limited 5/min)
POST /api/v1/license/activate         bind install/deployment → Ed25519 grant (402 no paid sub · 403 revoked · 409 seat limit)
POST /api/v1/license/heartbeat        ~24h; refreshed grant + revoked + server_time high-water mark (clock-rollback defence)
POST /api/v1/license/deactivate
GET  /api/v1/license/customer/summary
POST /api/v1/license/customer/licenses/{id}/restore | seats/{install_id}/enable | expire
GET  /api/v1/license/releases/{channel}

System B — KOS app-side enforcement (verify only)

Six enforcement gates: 1 provider list (edition) · 2 harness picker (license) · 3 runtime backstop _chat_routing_for — the teeth · 4 project-create cap · 5 worker/team cap · 6 startup posture (soft; hard-gate flag default off).