Jira progress: loading…

CUEM

CUEM — Commercial Usage & Entitlement Module

1. Purpose

The Commercial Usage & Entitlement Module (CUEM) is the canonical ZAYAZ module for translating platform consumption into governed commercial state.

CUEM provides a common platform capability for:

usage metering;
subscription and contract entitlements;
included allowances and prepaid balances;
quota enforcement;
usage reservation and commitment;
price-plan resolution;
rating;
charge and credit accounting;
provider and infrastructure cost attribution;
invoice aggregation;
white-label partner settlement;
billing reconciliation;
commercial replay;
margin and unit-economics analytics.

CUEM exists so that individual ZAYAZ modules do not implement their own pricing, quota, billing, or commercial-accounting logic.

The fundamental architecture rule is:

Every potentially monetizable ZAYAZ action SHOULD emit a standardized usage event, even when its current price is zero.

This allows packaging and pricing to evolve without retrofitting commercial instrumentation into every module.

2. Architectural Position

CUEM is a top-level platform module.

Under the ZAYAZ ontology:

CUEM is the Module;
metering, entitlement, rating, ledgers, registries, reconciliation, settlement, and invoice aggregation are Components belonging to CUEM;
payment providers, accounting systems, ERP systems, and tax services remain external systems or integrations;
producing modules remain authoritative for the business event that occurred;
CUEM becomes authoritative only for the commercial interpretation of that event.

CUEM SHALL NOT become a duplicate identity, authorization, audit, reporting, payment, or general-ledger architecture.

3. Core Separation of Responsibilities

CUEM SHALL preserve the following commercial pipeline:

WHAT HAPPENED
Usage Event
    ↓
WHAT IS ALLOWED
Entitlement Resolution
    ↓
WHAT ALLOWANCE APPLIES
Allowance / Quota Resolution
    ↓
WHAT IS IT WORTH
Rating
    ↓
WHO OWES WHOM
Charge / Credit
    ↓
HOW IT IS GROUPED
Invoice Aggregation / Settlement
    ↓
HOW MONEY MOVES
Payment Provider / ERP / Accounting System

These layers MUST remain separable.

A usage event is not a charge.

A charge is not an invoice.

An invoice is not a payment.

A provider cost is not a customer price.

A payment provider is not the ZAYAZ commercial source of truth.

4. Module Boundaries

4.1. CUEM Owns

CUEM is authoritative for:

normalized usage events;
billable-unit definitions;
commercial contracts and effective versions;
price plans and price rules;
entitlement decisions;
allowance balances and movements;
usage reservation and commitment;
rating results;
charge, credit, reversal, and adjustment records;
commercial cost records;
invoice-ready aggregation;
partner settlement calculations;
commercial reconciliation;
commercial replay and explainability.

4.2. CUEM Does Not Own

CUEM does not replace:

E-C-O identity;
user_id;
uom_number;
Atlas authorization and partner delegation;
Reports Hub report lifecycle;
AI DIAL execution telemetry;
ZARA/ZAAM/ZADIF orchestration;
ALTD assurance semantics;
Stripe or other payment execution;
ERP statutory accounting;
tax authority determinations;
bank settlement;
product or ESG business logic.

4.3. Artifact Governance Status

CUEM is currently a proposed architecture module, not a constitutional artifact-domain registration.

The candidate domain code ADCOMM is therefore a proposal only. It SHALL NOT be treated as a canonical artifact domain, used in an ARTIF-ADCOMM-* identity, or exposed as an authoritative persistence contract unless and until all required constitutional registrations are completed.

Before any CUEM persistent output becomes a production canonical artifact, the platform SHALL complete the applicable governance work, including:

amendment of the Artifact Constitution to register the commercial artifact domain;
OMR ownership binding for the registered domain;
one ARTIF-* entry per persistent artifact type in config/system/artifact-types.json;
a registered runtime identifier type, using ARTID where specialized semantics are not required;
a singular owning specification and producing component;
replay semantics for the artifact type;
CSI transport contracts where cross-component transport is required.

The names listed in the CUEM OMR outputs collection are therefore architecture-level output families, not canonical artifact-type identifiers. They MUST NOT be interpreted as registered persistent artifacts merely because they appear in the module architecture.

This keeps the CUEM architecture usable now without bypassing Artifact Constitution §4.1 or pre-committing the later persistence design.

5. Component Model

The initial CUEM architecture contains the following Components.

Component	Ontology Type	Responsibility
Usage Metering Gateway	Service	Accepts, validates, normalizes, deduplicates, and persists platform usage events
Usage Ledger	Ledger component	Append-only factual record of measured consumption
Billable Unit Registry	Registry	Defines governed units that may be entitled, metered, rated, or charged
Commercial Contract Registry	Registry	Stores effective commercial agreements and commercial scope
Price Catalog	Registry	Stores versioned plans, price rules, tiers, currencies, and effective dates
Entitlement Engine	Engine	Determines whether a capability may be used under the active contract
Allowance Ledger	Ledger component	Tracks included units, prepaid units, reservations, consumption, expiry, and release
Rating Engine	Engine	Converts qualified usage into economic value under a pinned rule set
Charge Ledger	Ledger component	Stores immutable charges, credits, reversals, and adjustments
Cost Ledger	Ledger component	Stores attributable provider and internal COGS independently of selling price
Billing Account Router	Engine	Resolves beneficiary, payer, partner, shared pool, and settlement responsibility
Invoice Aggregator	Service	Converts rated charge entries into invoice-ready line groups
Partner Settlement Engine	Engine	Calculates white-label wholesale, revenue-share, commissions, and partner balances
Reconciliation Engine	Engine	Reconciles platform usage and cost against provider, payment, and ERP records
Commercial Analytics Service	Service	Provides consumption, COGS, margin, overage, allowance, and partner profitability analytics

These Components belong to CUEM.

They MUST NOT be represented as independent top-level Modules unless a later constitutional architecture decision explicitly changes ownership.

6. Canonical Identity Model

CUEM SHALL use the governed ZAYAZ identity vocabulary.

The canonical identities remain:

Identity	Meaning
`eco_number`	E-C-O family organizational or business identity
`user_id`	Individual ZAYAZ user identity
`uom_number`	Independently issued UOM-owned object identity

CUEM MUST NOT introduce tenant_id, client_id, or organization_id as replacement canonical business identities where the governed identity is known.

Commercial roles SHOULD be represented by role objects containing the canonical identity.

Example:

{
  "actor": {
    "user_id": "usr-..."
  },
  "beneficiary": {
    "eco_number": "ECO-..."
  },
  "payer": {
    "eco_number": "ECO-..."
  },
  "partner": {
    "eco_number": "WLP-..."
  },
  "subject": {
    "uom_number": null
  }
}

The same E-C-O family identity MAY occupy more than one commercial role.

7. Commercial Role Separation

CUEM SHALL distinguish at least the following roles where applicable:

actor — who initiated or caused the usage;
beneficiary — whose ZAYAZ work received the benefit;
payer — which contractual party is economically responsible;
partner — which white-label, accounting, assurance, or reseller organization participates commercially;
subject — optional UOM-owned object associated with the usage;
producer — the ZAYAZ Module and Component that emitted the usage.

This separation allows:

client-paid usage;
parent-company-paid usage;
partner-paid usage;
reseller billing;
shared group allowances;
subsidiary consumption;
partner revenue share;
delegated workflows without confusing commercial responsibility with authorization.

8. Standard Usage Event

All CUEM-integrated producers SHOULD emit a normalized runtime Usage Event.

The Usage Event is a runtime contract.

Persistent implementation artifacts derived from this contract SHALL be registered through the applicable constitutional artifact and identifier registries before production where required.

A conceptual envelope is:

{
  "usage_event_id": "uuid",
  "source_event_id": "producer-stable-idempotency-key",
  "trace_id": "trace-ref",
  "occurred_at": "2026-09-20T08:30:00Z",
  "received_at": "2026-09-20T08:30:01Z",

  "actor": {
    "user_id": "usr-..."
  },

  "beneficiary": {
    "eco_number": "ECO-..."
  },

  "payer": {
    "eco_number": "ECO-..."
  },

  "partner": {
    "eco_number": null
  },

  "subject": {
    "uom_number": null
  },

  "producer": {
    "module_id": "reports-insights-hub",
    "component_ref": "report-lifecycle"
  },

  "usage": {
    "billable_unit_ref": "registered-unit-ref",
    "quantity": "1",
    "unit_of_measure": "event"
  },

  "context": {
    "report_ref": "report-reference",
    "framework": "ESRS",
    "reporting_period": "2026"
  },

  "commercial": {
    "contract_ref": null,
    "entitlement_ref": null
  },

  "integrity": {
    "event_hash": "sha256:..."
  }
}

The producer SHOULD provide facts.

The producer SHOULD NOT calculate customer price.

9. Idempotency

Commercial side effects MUST be idempotent.

At-least-once delivery of the same producer event MUST NOT result in duplicate economic charges.

The combination of producer identity and source_event_id SHALL provide a stable deduplication boundary.

For lifecycle-triggered billing, the source event SHOULD represent the governed transition rather than an incidental technical operation.

Example:

Correct:
report artifact → APPROVED → ISSUED

Not sufficient:
PDF renderer executed

Rendering the same report twenty times SHALL NOT produce twenty report-issuance charges unless the commercial contract explicitly defines rendering as the metered unit.

10. Billable Unit Registry

CUEM SHALL maintain a governed Billable Unit Registry.

The registry defines what may be:

entitled;
counted;
reserved;
deducted;
rated;
charged;
credited;
reconciled.

A billable unit definition SHOULD contain:

unit identity
name
description
producer scope
measurement basis
quantity precision
aggregation policy
deduplication policy
eligibility rules
default rating behavior
replay requirements
effective dates
status

Initial business categories are expected to include:

active users or seats;
report issuance;
report verification;
API consumption;
AI consumption;
advanced computation;
lifecycle assessment;
verification cases;
Carbon Passport issuance;
storage or data volume where commercially relevant;
managed supplier volumes;
premium module access;
premium workflow execution.

Specific unit codes SHALL be registered before they are treated as canonical governed identifiers.

11. Entitlement Model

Entitlement answers:

May this commercial scope use this capability now?

An entitlement MAY originate from:

subscription plan;
enterprise contract;
partner contract;
add-on;
trial;
promotion;
prepaid package;
regulatory or public-interest access;
manual commercial grant;
migration agreement.

Entitlement is distinct from RBAC authorization.

A user can be technically authorized to execute an action while the organization is not commercially entitled to consume it.

Conversely, an organization may own an entitlement while a specific user remains unauthorized by Atlas or application RBAC.

Both checks are required.

12. Entitlement Outcomes

The initial policy model SHOULD support outcomes equivalent to:

Outcome	Meaning
Allow unmetered	Capability is available and no consumption balance is affected
Allow and meter	Usage is recorded but no allowance is deducted
Allow and deduct	Usage consumes an included or prepaid allowance
Allow overage	Usage consumes allowance first and may generate overage
Block when exhausted	Execution is denied when available allowance reaches zero
Require upgrade	Capability requires another subscription or add-on
Require approval	Commercial approval is required before execution

The exact runtime enumeration SHALL be versioned by the implementation contract.

Commercial policy SHALL NOT weaken authorization, governance, assurance, security, or residency policy.

13. Allowance Ledger

CUEM SHALL support allowance accounts for:

included monthly usage;
included annual usage;
prepaid credits;
promotional credits;
partner pools;
group pools;
feature-specific allowances;
monetary-equivalent allowances where contractually defined.

Allowance balances MUST be derived from immutable movements rather than overwritten totals.

Example movement types include:

grant
reserve
commit
release
expire
adjust
reverse
transfer

A displayed balance is a projection.

The movements are the authoritative history.

14. Reservation Semantics

Expensive or concurrent operations SHOULD support reservation.

Available allowance = 100 units

Request A reserves 40
Request B reserves 50

Visible free balance = 10

Request A completes with actual usage 31
    → commit 31
    → release 9

Request B fails before billable execution
    → release 50

Reservation prevents multiple concurrent operations from spending the same remaining allowance.

Reservations MUST have expiry and recovery behavior.

15. Commercial Contracts

The Commercial Contract Registry SHALL represent the versioned agreement governing economic behavior.

A contract SHOULD resolve:

beneficiary scope;
payer;
partner relationship;
effective period;
product/subscription plan;
add-ons;
included allowances;
price-plan reference;
commitment;
minimum fee;
maximum spend where applicable;
overage behavior;
settlement terms;
invoicing cadence;
currency;
tax treatment metadata;
renewal behavior;
termination behavior.

Commercial contracts MUST be effective-dated.

Historical events MUST retain the contract version that governed them.

16. Price Catalog

The Price Catalog SHALL store versioned price rules independently of product implementation.

Supported pricing patterns MAY include:

fixed subscription;
seat pricing;
flat per-event pricing;
per-unit pricing;
graduated tiers;
volume tiers;
packaged allowances;
prepaid units;
minimum commitment;
overage;
cost-plus;
markup;
negotiated enterprise pricing;
partner wholesale pricing;
revenue share;
zero-price promotional or public-interest access.

Price changes MUST NOT rewrite historical rated usage.

17. Rating Engine

Rating answers:

What is this qualified usage worth under the governing commercial agreement?

The Rating Engine SHALL use version-pinned inputs.

A rating result SHOULD retain:

usage_event_ref
contract_version
price_plan_version
price_rule_version
quantity
allowance_applied
billable_quantity
list_amount
discount_amount
credit_amount
net_amount
currency
tax_basis_metadata
rounding_policy
rating_timestamp
explanation

The same historical usage event, contract version, and price-rule version SHOULD reproduce the same rating result.

18. Usage Ledger and Charge Ledger Are Separate

CUEM SHALL maintain a strict distinction between factual consumption and economic interpretation.

18.1. Usage Ledger

The Usage Ledger records:

Something happened.

Example:

At 10:42:17
user U
for organization E
caused one governed report issuance
through Reports Hub.

The Usage Ledger does not state what the customer owes.

18.2. Charge Ledger

The Charge Ledger records:

Under the governing commercial agreement, this usage produced this economic effect.

Example:

Usage event: U123
Included allowance consumed: 1
Billable overage quantity: 0
Net customer charge: EUR 0.00

or:

Usage event: U987
Allowance exhausted
Billable overage quantity: 1
Net customer charge: EUR 49.00

This separation is mandatory.

19. Corrections, Reversals, and Adjustments

Economic history SHOULD be append-only.

A material billing correction SHOULD use reversal and replacement rather than silent mutation.

Example:

Original charge      +79.00
Reversal             -79.00
Corrected charge     +49.00

The relationship between original, reversal, and corrected record MUST remain traceable.

Usage facts SHOULD be corrected only through explicit correction events when the original factual event itself was wrong.

20. Report-Based Commercial Events

Reports are a primary candidate for outcome-based pricing.

CUEM SHALL distinguish report lifecycle from report rendering.

A contract MAY price:

report issuance;
verified report;
assurance package;
report re-issuance;
premium export package.

A billable report event SHOULD bind to a governed Reports Hub lifecycle transition.

Example:

DRAFT
  ↓
REVIEW
  ↓
APPROVED
  ↓
ISSUED       ← candidate commercial event
  ↓
VERIFIED     ← separate candidate commercial event

The contract determines whether either event is chargeable.

CUEM determines the economic result.

Reports Hub remains authoritative for the report lifecycle state.

21. AI Usage Integration

AI usage is one producer domain inside the broader CUEM architecture.

AI DIAL, provider adapters, ZARA, ZAAM, ZADIF, and other AI execution components MAY produce measurements such as:

input tokens;
output tokens;
cached input;
model deployment;
provider;
latency;
model profile;
execution region;
provider-estimated cost.

Those measurements SHALL feed an AI metering adapter and then CUEM.

AI infrastructure MUST NOT become a parallel billing authority.

The canonical flow is:

AI execution
    ↓
AI execution telemetry
    ↓
AI Metering Adapter
    ↓
CUEM Usage Metering Gateway
    ↓
Usage Ledger
    ↓
Entitlement / Allowance / Rating
    ↓
Charge Ledger

A commercial contract MAY choose to bill AI by:

included AI allowance;
raw token quantity;
normalized AI unit;
premium AI feature;
AI-assisted report;
fixed subscription;
no incremental AI charge.

The underlying AI execution measurement and the commercial billing model therefore remain decoupled.

22. Cost Ledger

CUEM SHALL distinguish customer price from ZAYAZ cost.

The Cost Ledger MAY record:

LLM provider cost;
embedding cost;
reranking cost;
GPU cost;
cloud compute;
storage;
network;
premium data-provider cost;
verifier or assurance partner cost;
payment-processing cost;
other attributable variable infrastructure cost.

A cost record SHOULD identify:

provider;
cost basis;
quantity;
currency;
source record;
affected usage;
estimate or actual status;
reconciliation status.

23. Estimated Cost and Actual Cost

Operational systems MAY provide immediate estimated cost.

Provider invoices or later settlement data MAY provide actual cost.

CUEM SHOULD retain both.

Example:

execution estimate     EUR 0.082
provider actual        EUR 0.079
variance              -EUR 0.003

Reconciliation MUST NOT rewrite the original execution telemetry.

It updates the commercial cost interpretation through governed reconciliation records.

24. Unit Economics

CUEM SHOULD support:

Revenue
-
Provider cost
-
Compute cost
-
Data-provider cost
-
Verification-partner cost
-
Payment-processing cost
-
Other attributable variable cost
=
Contribution margin

Commercial Analytics SHOULD be able to calculate margin by:

E-C-O organization;
white-label partner;
module;
component;
report;
API product;
AI capability;
model provider;
report framework;
subscription;
commercial contract;
country or region where permitted;
product line.

25. White-Label Commercial Model

CUEM is required for scalable white-label economics.

The architecture SHALL allow:

White-label partner
        │
        ├── Customer A
        ├── Customer B
        └── Customer C

Customer usage MAY be attributed to the customer as beneficiary while the partner is the payer.

The commercial contract MAY then apply:

wholesale platform price;
partner allowance;
minimum annual commitment;
revenue share;
partner markup;
service fee;
settlement credit;
verifier transaction revenue.

ZAYAZ SHOULD retain the ability to calculate partner profitability independently of the partner's retail price.

26. Group and Parent Billing

CUEM SHOULD support hierarchical commercial arrangements.

Example:

Group E-C-O
  │
  ├── Subsidiary A
  ├── Subsidiary B
  └── Subsidiary C

A subsidiary can be the beneficiary while the group is the payer.

The contract MAY provide:

pooled report allowance;
pooled AI allowance;
pooled user licenses;
subsidiary-specific sub-limits;
central invoicing;
internal cost allocation.

Commercial hierarchy SHALL NOT redefine the UOM graph or E-C-O identity model.

27. Billing Account Routing

The Billing Account Router SHALL resolve who is economically responsible.

Inputs MAY include:

beneficiary E-C-O scope;
parent/group commercial contract;
active white-label partner relationship;
reseller agreement;
product;
jurisdiction;
currency;
billing cadence;
contractual exception.

Routing MUST be deterministic and explainable.

A usage event MUST NOT be billed to a different party merely because that party initiated the technical request.

28. Invoice Aggregation

The Invoice Aggregator converts charge-ledger entries into invoice-ready groups.

Aggregation MAY occur by:

payer;
contract;
billing period;
purchase order;
currency;
tax category;
product;
billable unit;
partner;
project or cost center where contractually supported.

An invoice line SHOULD be traceable back to the charge entries from which it was aggregated.

29. Stripe and Payment Providers

Stripe or another payment provider is an execution integration.

It SHALL NOT be the canonical ZAYAZ source for:

billable-unit semantics;
entitlement logic;
allowance balances;
price-plan governance;
partner attribution;
commercial identity;
rating;
charge history.

The preferred boundary is:

CUEM Charge Ledger
      ↓
Invoice Aggregator
      ↓
Invoice-ready commercial instruction
      ↓
Stripe / ERP / accounting integration
      ↓
Payment / receivable state
      ↓
Reconciliation back to CUEM

This allows ZAYAZ to support:

Stripe;
direct enterprise invoicing;
ERP invoicing;
Tripletex;
SAP;
reseller invoicing;
purchase-order billing;
manual settlement;
future providers.

30. General Ledger Boundary

CUEM is a commercial usage and charging subledger.

It is not the statutory general ledger.

Accounting recognition, statutory journal entries, tax filing, and financial-statement accounting remain the responsibility of the organization's accounting or ERP system.

CUEM MAY export commercial accounting evidence and invoice-ready data to those systems.

31. Currency

Every monetary record MUST carry an explicit currency.

CUEM MUST NOT silently compare or aggregate unlike currencies.

Where foreign-exchange conversion is required, the rated or reconciled record SHOULD preserve:

source currency;
target currency;
exchange rate;
rate source;
rate timestamp or effective date;
conversion policy.

Historical charges MUST retain the FX basis used at the time of rating or invoicing.

32. Tax and VAT Boundary

CUEM MAY carry:

tax category;
customer tax status;
jurisdiction metadata;
reverse-charge metadata;
VAT identifiers;
tax-calculation result references.

Tax calculation MAY be performed by a specialized tax service, ERP, or payment provider.

CUEM SHALL retain the commercial basis and returned tax result required for invoice traceability.

CUEM MUST NOT hardcode jurisdictional tax rates into unrelated application logic.

33. Discounts, Credits, Trials, and Promotions

CUEM SHOULD support governed commercial adjustments including:

negotiated discount;
temporary promotion;
free trial;
launch credit;
service credit;
prepaid credit;
partner credit;
goodwill credit;
SLA credit.

Every adjustment SHOULD carry:

reason;
authority;
effective period;
scope;
amount or rule;
approver where required;
audit reference.

34. Quota Enforcement

CUEM SHOULD support:

hard limits;
soft limits;
alert thresholds;
overage;
approval-required limits;
spend caps;
per-user limits;
per-E-C-O limits;
group limits;
partner limits.

The Entitlement Engine remains authoritative for commercial permission.

Execution systems MAY enforce derived runtime limits locally for performance.

Local enforcement MUST NOT invent commercial policy.

35. Usage Preflight

For operations with predictable commercial impact, CUEM SHOULD support preflight.

Example:

Request
   ↓
Authorization
   ↓
Commercial preflight
   ├── entitled?
   ├── allowance available?
   ├── spend cap available?
   └── approval required?
   ↓
reserve if necessary
   ↓
execute
   ↓
commit actual usage

Preflight improves user experience and prevents avoidable denied or unpaid work.

36. Uncertain Final Quantity

Some operations cannot know final quantity before execution.

Examples include:

LLM token use;
large data processing;
Monte Carlo workloads;
ingestion volume.

CUEM SHOULD support:

conservative reservation;
execution;
actual measurement;
commitment of actual quantity;
release of unused reservation.

If actual usage exceeds reservation, overrun behavior SHALL follow the active commercial policy.

37. Late and Out-of-Order Usage

Usage events MAY arrive late or out of order.

CUEM SHALL preserve:

actual occurrence time;
ingestion time;
governing contract time;
rating time.

A late event SHALL be rated according to the governed policy for the period in which the usage occurred, unless an explicit correction or migration policy states otherwise.

Backdating a new price plan MUST NOT silently reprice already finalized historical charges.

38. Contract Changes

Commercial changes MUST be versioned.

Examples include:

subscription upgrade;
subscription downgrade;
added report allowance;
new partner discount;
currency change;
price change;
new add-on;
changed spend cap.

The effective timestamp and proration policy MUST be explicit.

A contract update SHALL NOT mutate the commercial meaning of already finalized historical records.

39. Proration

Proration SHOULD be a governed rating policy.

Examples:

per-day proration;
full-period billing;
next-period activation;
immediate upgrade / next-cycle downgrade;
no proration for usage-based charges.

The applicable rule MUST be captured in the rating explanation.

40. Usage Event Durability

Producing modules SHOULD use an outbox or equivalent durable-delivery pattern for financially relevant usage.

The architecture MUST avoid:

business action succeeds
usage event silently disappears

A metering outage SHOULD not necessarily block a low-risk operation if durable recovery is guaranteed.

However, operations requiring a hard commercial preflight MAY fail closed when entitlement or allowance state cannot be reliably resolved.

41. Three Levels of Commercial Telemetry

CUEM SHOULD separate:

Level 1 — Operational Telemetry

Examples:

request latency;
provider response;
token counter;
API response code;
compute runtime.

Level 2 — CUEM Commercial Records

Examples:

usage event;
allowance movement;
rating;
charge;
cost;
settlement;
invoice aggregation.

Level 3 — ALTD / Assurance Records

Examples:

material commercial-policy change;
approved pricing override;
disputed high-value adjustment;
assurance-significant consumption event;
human commercial override where governance requires evidence.

Not every token or API call belongs in ALTD.

42. Audit and Explainability

For every material charge, CUEM SHOULD be able to answer:

what happened;
when it happened;
who initiated it;
which organization benefited;
who was billed;
which partner was involved;
which unit was measured;
what quantity was measured;
which entitlement applied;
which allowance was consumed;
which contract version applied;
which price rule applied;
which discount or credit applied;
which currency applied;
how the final amount was calculated;
which cost was attributed;
whether the record was reversed or corrected;
which invoice included it.

43. Replay

CUEM replay SHALL follow the Replay Constitution and the governed TrustGate replay profiles. Replay semantics are declared per governed output, not inferred from the fact that the CUEM module supports replay.

For deterministic commercial interpretation, the required profile is EXACT. Given the immutable replay manifest and pinned commercial inputs, the replayed governed output SHALL be bit-identical to the original governed output.

For externally observed or ledger-recorded facts that are not meaningfully recreated by rerunning current software, the required profile is RECORDED. Replay verifies the integrity, provenance, lineage, and creation-time anchoring of the recorded output rather than pretending that a later provider invoice or external settlement fact can be regenerated historically.

CUEM does not define a BANDED commercial output in this architecture version. A future probabilistic CUEM output MAY use BANDED only where its owning governed specification supplies the tolerance-policy reference required by the Replay Constitution.

43.1. Component Replay Profiles

CUEM component / output family	Replay profile	Required replay meaning
Usage Metering Gateway — accepted normalized usage event	`RECORDED`	Verify the immutable accepted event, source reference, deduplication identity, producer identity, timestamp basis, and creation-time anchor. Do not re-measure the historical external action.
Usage Ledger — usage record	`RECORDED`	Verify the original append-only usage fact and lineage.
Billable Unit Registry — resolved billable-unit definition	`EXACT`	Re-resolve the pinned registry version and reproduce the same governed definition.
Commercial Contract Registry — resolved effective contract	`EXACT`	Resolve the pinned contract version and effective-time context identically.
Price Catalog — resolved plan/rule set	`EXACT`	Resolve the pinned catalog and price-rule versions identically.
Entitlement Engine — entitlement decision	`EXACT`	Reproduce the same allow/deny/conditional decision from pinned identity, contract, capability, and policy inputs.
Allowance Ledger — reservation/commit/release movement	`EXACT`	Reproduce the same governed state transition from the pinned prior state and event sequence.
Rating Engine — rating result	`EXACT`	Reproduce the same quantity, price rule, currency/FX basis, rounding basis, and rated amount.
Billing Account Router — payer/beneficiary/partner resolution	`EXACT`	Reproduce the same commercial-role resolution from pinned identities, delegation context, and contract state.
Charge Ledger — charge, credit, reversal, adjustment record	`RECORDED`	Verify the immutable posted commercial record, lineage, correction chain, and anchor.
Cost Ledger — provider/internal cost record	`RECORDED`	Verify the recorded estimate or actual cost and its source evidence. Later reconciliation SHALL create successor evidence rather than rewrite the historical record.
Invoice Aggregator — invoice-ready line grouping	`EXACT`	Reproduce identical grouping and amounts from the pinned charge set and aggregation policy.
Partner Settlement Engine — settlement calculation	`EXACT`	Reproduce identical settlement economics from pinned contract, charge, and revenue-share inputs.
Reconciliation Engine — reconciliation record	`RECORDED`	Verify the reconciliation outcome that was recorded for the evidence available at that time. Later provider/ERP evidence creates a new reconciliation record rather than changing replay truth.
Commercial Analytics Service — governed materialized metric snapshot	`EXACT`	Reproduce the same governed metric from the pinned dataset snapshot and calculation/configuration versions. Non-governed exploratory analytics are outside constitutional replay.

43.2. Immutable Replay Manifest

Every replayable CUEM execution SHALL possess an immutable Replay Manifest before it may be presented as replayable.

At minimum, the manifest SHALL preserve or reference:

the declared replay_mode;
the executing component identity and pinned version/CMI where applicable;
the configuration snapshot reference;
the original output or artifact hash for RECORDED outputs;
usage-event identity and immutable source reference;
beneficiary, payer, partner, actor, and subject identities used by the execution;
contract version and effective-time basis;
entitlement-policy version;
allowance state or prior-ledger reference where relevant;
billable-unit definition version;
price-plan and price-rule versions;
quantity, unit, rounding, currency, and FX source/version where relevant;
charge/cost/reversal/correction lineage;
provider, ERP, payment, or other external evidence references used by reconciliation;
the resulting governed output hash;
the ALTD/DAL anchor or equivalent governed evidence reference required by the applicable replay profile.

Commercial replay SHALL NOT depend on whatever price, contract, allowance, FX rate, provider cost, or policy is current at replay time.

For EXACT outputs, any divergence is a replay failure. For RECORDED outputs, replay passes only when the recorded evidence, lineage, hashes, and required creation-time anchoring verify successfully.

44. Security and Privacy

CUEM contains commercially sensitive data.

Access SHOULD follow least privilege.

CUEM SHOULD avoid storing unnecessary business payloads.

For example, AI metering SHOULD normally store:

model profile;
token quantities;
cost;
execution reference;

not the full prompt or model response.

Report charging SHOULD store report references and lifecycle evidence rather than duplicate report contents.

Payment credentials SHOULD remain with approved payment infrastructure.

45. Atlas and Delegation

Atlas remains authoritative for authorization.

Existing commercial capabilities such as:

subscription changes;
billing-detail administration;

remain governed by Atlas delegation policy.

CUEM SHALL consume authorized commercial decisions.

CUEM SHALL NOT allow a partner to modify billing identity, contract, price, allowance, or payment authority merely because that partner may perform operational work for a client.

46. White-Label Isolation

A white-label partner MUST NOT receive another partner's:

client usage;
prices;
costs;
allowances;
margins;
settlements;
invoice details.

Partner-facing commercial views SHALL be scoped through governed E-C-O relationships and authorization.

47. Price Governance

Price creation and publication SHOULD be separated from ordinary runtime consumption.

Price plans SHOULD support states equivalent to:

DRAFT
  ↓
REVIEW
  ↓
APPROVED
  ↓
ACTIVE
  ↓
RETIRED

Material price changes SHOULD require authorized review.

Runtime systems consume approved price policy.

They do not create it.

48. Commercial Analytics

CUEM SHOULD support analytics including:

active commercial accounts;
consumption by unit;
included usage consumed;
remaining allowance;
overage;
prepaid balance;
forecasted exhaustion;
AI COGS;
report COGS;
contribution margin;
gross margin proxy;
partner margin;
provider variance;
price realization;
revenue by module;
usage by E-C-O;
usage by white-label partner;
usage by product;
usage by framework;
unusual cost growth.

Analytics SHALL read governed commercial records rather than recompute billing logic independently.

49. Anomaly Detection

CUEM SHOULD detect anomalies such as:

duplicate usage;
sudden consumption spikes;
runaway AI usage;
excessive retries;
abnormal API activity;
negative allowance drift;
missing meter events;
provider cost mismatch;
unexpected zero-rated high-cost workloads;
unusual partner settlement variance.

Anomaly detection MAY alert, pause, require approval, or invoke a hard limit according to policy.

50. Conceptual Persistence Model

The following logical data sets are expected.

Physical schemas are implementation decisions and do not constitute existing database claims.

cuem_usage_event
cuem_billable_unit
cuem_commercial_contract
cuem_contract_version
cuem_price_plan
cuem_price_rule
cuem_entitlement
cuem_allowance_account
cuem_allowance_movement
cuem_rating_result
cuem_charge_entry
cuem_cost_entry
cuem_invoice_batch
cuem_invoice_line
cuem_partner_settlement
cuem_reconciliation_record

Before persistent governed artifacts or new identifier types are introduced, they SHALL be registered through the applicable ZAYAZ constitutional registries.

51. Recommended Event Flow

52. Example — Report Allowance

Commercial contract:

Annual subscription: EUR 12,000
Included issued reports: 50
Additional issued report: EUR 35

Runtime:

Report 49 reaches ISSUED
    ↓
Usage event = 1
    ↓
Allowance 2 → 1
    ↓
Charge = EUR 0

Report 50 reaches ISSUED
    ↓
Usage event = 1
    ↓
Allowance 1 → 0
    ↓
Charge = EUR 0

Report 51 reaches ISSUED
    ↓
Usage event = 1
    ↓
Allowance exhausted
    ↓
Charge = EUR 35

The Reports Hub emits the lifecycle fact.

CUEM owns the allowance and price interpretation.

53. Example — AI Included Allowance

Commercial contract:

Monthly AI allowance: 10,000 normalized units
Overage: permitted

AI DIAL reports raw execution measurements.

The AI Metering Adapter normalizes the approved measurement into the registered commercial unit.

CUEM then:

meters
→ deducts allowance
→ rates overage where applicable
→ records provider cost separately

The model provider never determines the customer price.

54. Example — White-Label Partner

Customer beneficiary:
E-C-O Customer A

Partner / payer:
E-C-O Partner P

Usage:
1 verified report

ZAYAZ wholesale rating:
EUR 45

Partner retail price:
outside ZAYAZ unless partner contract requires reporting

Provider/verifier cost:
EUR 18

ZAYAZ contribution before shared overhead:
EUR 27

This model allows ZAYAZ to scale partner economics without exposing internal COGS.

55. Failure Semantics

CUEM SHALL classify commercial failure separately from business-operation failure.

Examples include:

entitlement_denied
allowance_exhausted
spend_cap_exceeded
commercial_approval_required
contract_not_resolved
price_rule_not_resolved
metering_validation_failed
duplicate_usage_event
rating_failed
currency_resolution_failed
invoice_aggregation_failed
settlement_failed
reconciliation_variance

Unknown price or entitlement state SHOULD fail closed for actions where execution would create uncontrolled financial exposure.

56. Non-Goals

CUEM SHALL NOT:

become a payment-card vault;
replace Stripe;
replace an ERP;
replace statutory accounting;
replace tax engines;
own E-C-O identity;
own user identity;
replace Atlas authorization;
own report lifecycle;
own AI orchestration;
own AI provider routing;
duplicate ALTD;
duplicate product business logic.

57. Initial Implementation Phases

Phase 1 — Metering Foundation

Implement:

Usage Event contract;
Usage Metering Gateway;
idempotency;
Usage Ledger;
producer SDK;
trace correlation.

Initial producers SHOULD include:

Reports Hub;
AI execution;
API gateway;
selected premium computations.

Phase 2 — Entitlements and Allowances

Implement:

Commercial Contract Registry;
Entitlement Engine;
Billable Unit Registry;
Allowance Ledger;
reservation / commit / release;
hard and soft quota policies.

Phase 3 — Rating and Charge Accounting

Implement:

Price Catalog;
Rating Engine;
Charge Ledger;
reversals and corrections;
multi-currency support;
rating replay.

Phase 4 — Cost Accounting

Implement:

Cost Ledger;
provider-cost imports;
AI/provider reconciliation;
compute-cost attribution;
unit-economics dashboards.

Phase 5 — Invoice Integration

Implement:

Billing Account Router;
Invoice Aggregator;
Stripe integration;
ERP export contracts;
payment-state reconciliation.

Phase 6 — White-Label Settlement

Implement:

partner contracts;
wholesale price plans;
revenue share;
settlement ledger;
partner commercial dashboards;
group and pooled allowances.

58. Acceptance Criteria

The first production-capable release SHOULD demonstrate:

Test	Expected Result
Same source event delivered twice	One economic effect
Zero-priced feature is used	Usage retained with zero charge
Included report is issued	Allowance deducted, no overage charge
Allowance is exhausted	Contract policy determines block or overage
Concurrent expensive requests	Reservation prevents overspend
Price changes next month	Historical rating remains unchanged
Contract upgrades mid-period	Effective-date/proration rule is explicit
White-label customer uses feature	Beneficiary and payer remain distinct
Parent pays for subsidiary	Usage attributed to subsidiary, invoice to parent
AI execution completes	Raw AI measurement becomes CUEM usage
Provider invoice arrives	Estimated and actual cost reconcile without rewriting usage
Charge is wrong	Reversal and corrected charge preserve history
Invoice generated	Every invoice line traces to charge entries
Stripe unavailable	Charge history remains intact
Currency conversion used	FX basis is preserved
Commercial replay requested	EXACT outputs reproduce from the immutable replay manifest; RECORDED ledger/external facts verify integrity, lineage, and anchoring
Unauthorized billing change	Atlas/RBAC blocks the change
Partner queries another partner	Access denied
Metering transport retries	No duplicate charge

59. Architectural Decisions

The following decisions are canonical for CUEM v0.1.0:

CUEM is a top-level ZAYAZ Module.
Commercial engines, registries, ledgers, services, and workflows are Components of CUEM.
Every potentially monetizable action SHOULD emit usage even when priced at zero.
Producing Modules emit facts; CUEM determines commercial meaning.
Usage, entitlement, allowance, rating, charge, invoice, payment, and settlement are separate concerns.
E-C-O family identity remains the organizational commercial identity.
user_id remains the individual actor identity.
uom_number remains the governed object identity where applicable.
CUEM does not introduce a canonical tenant_id.
Usage history is append-only and idempotent.
Charge corrections use governed reversals or adjustments rather than silent mutation.
Price plans and contracts are versioned and effective-dated.
Historical rating is reproducible from pinned commercial inputs.
Allowance balances derive from immutable movements.
High-cost concurrent execution SHOULD use reservation semantics.
Customer price and provider/internal cost remain separate.
AI is one usage producer domain; AI billing does not own a separate commercial ledger.
Stripe and other payment providers execute payment/invoicing functions but do not own ZAYAZ commercial truth.
CUEM is a commercial subledger, not the statutory general ledger.
White-label and group billing preserve beneficiary, payer, partner, and actor as separate roles.
Not every commercial event is an ALTD event; assurance-significant commercial decisions remain auditable through the appropriate governance layer.
New persistent artifact and identifier types require constitutional registry registration before production.

60. Final Principle

CUEM provides the commercial nervous system of ZAYAZ.

It connects:

Identity
   ↓
Entitlement
   ↓
Consumption
   ↓
Allowance
   ↓
Cost
   ↓
Price
   ↓
Charge
   ↓
Invoice
   ↓
Payment / Settlement
   ↓
Margin

without forcing individual ESG, reporting, AI, assurance, computation, or white-label Components to understand billing infrastructure.

ZAYAZ modules create value. CUEM measures, entitles, prices, attributes, and accounts for its commercial consumption.

GitHub Repo Request for Change (RFC)

1. Purpose​

2. Architectural Position​

3. Core Separation of Responsibilities​

4. Module Boundaries​

4.1. CUEM Owns​

4.2. CUEM Does Not Own​

4.3. Artifact Governance Status​

5. Component Model​

6. Canonical Identity Model​

7. Commercial Role Separation​

8. Standard Usage Event​

9. Idempotency​

10. Billable Unit Registry​

11. Entitlement Model​

12. Entitlement Outcomes​

13. Allowance Ledger​

14. Reservation Semantics​

15. Commercial Contracts​

16. Price Catalog​

17. Rating Engine​

18. Usage Ledger and Charge Ledger Are Separate​

18.1. Usage Ledger​

18.2. Charge Ledger​

19. Corrections, Reversals, and Adjustments​

20. Report-Based Commercial Events​

21. AI Usage Integration​

22. Cost Ledger​

23. Estimated Cost and Actual Cost​

24. Unit Economics​

25. White-Label Commercial Model​

26. Group and Parent Billing​

27. Billing Account Routing​

28. Invoice Aggregation​

29. Stripe and Payment Providers​

30. General Ledger Boundary​

31. Currency​

32. Tax and VAT Boundary​

33. Discounts, Credits, Trials, and Promotions​

34. Quota Enforcement​

35. Usage Preflight​

36. Uncertain Final Quantity​

37. Late and Out-of-Order Usage​

38. Contract Changes​

39. Proration​

40. Usage Event Durability​

41. Three Levels of Commercial Telemetry​

Level 1 — Operational Telemetry​

Level 2 — CUEM Commercial Records​

Level 3 — ALTD / Assurance Records​

42. Audit and Explainability​

43. Replay​

43.1. Component Replay Profiles​

43.2. Immutable Replay Manifest​

44. Security and Privacy​

45. Atlas and Delegation​

46. White-Label Isolation​

47. Price Governance​

48. Commercial Analytics​

49. Anomaly Detection​

50. Conceptual Persistence Model​

51. Recommended Event Flow​

52. Example — Report Allowance​

53. Example — AI Included Allowance​

54. Example — White-Label Partner​

55. Failure Semantics​

56. Non-Goals​

57. Initial Implementation Phases​

Phase 1 — Metering Foundation​

Phase 2 — Entitlements and Allowances​

Phase 3 — Rating and Charge Accounting​

Phase 4 — Cost Accounting​

Phase 5 — Invoice Integration​

Phase 6 — White-Label Settlement​

58. Acceptance Criteria​

59. Architectural Decisions​

60. Final Principle​

1. Purpose

2. Architectural Position

3. Core Separation of Responsibilities

4. Module Boundaries

4.1. CUEM Owns

4.2. CUEM Does Not Own

4.3. Artifact Governance Status

5. Component Model

6. Canonical Identity Model

7. Commercial Role Separation

8. Standard Usage Event

9. Idempotency

10. Billable Unit Registry

11. Entitlement Model

12. Entitlement Outcomes

13. Allowance Ledger

14. Reservation Semantics

15. Commercial Contracts

16. Price Catalog

17. Rating Engine

18. Usage Ledger and Charge Ledger Are Separate

18.1. Usage Ledger

18.2. Charge Ledger

19. Corrections, Reversals, and Adjustments

20. Report-Based Commercial Events

21. AI Usage Integration

22. Cost Ledger

23. Estimated Cost and Actual Cost

24. Unit Economics

25. White-Label Commercial Model

26. Group and Parent Billing

27. Billing Account Routing

28. Invoice Aggregation

29. Stripe and Payment Providers

30. General Ledger Boundary

31. Currency

32. Tax and VAT Boundary

33. Discounts, Credits, Trials, and Promotions

34. Quota Enforcement

35. Usage Preflight

36. Uncertain Final Quantity

37. Late and Out-of-Order Usage

38. Contract Changes

39. Proration

40. Usage Event Durability

41. Three Levels of Commercial Telemetry

Level 1 — Operational Telemetry

Level 2 — CUEM Commercial Records

Level 3 — ALTD / Assurance Records

42. Audit and Explainability

43. Replay

43.1. Component Replay Profiles

43.2. Immutable Replay Manifest

44. Security and Privacy

45. Atlas and Delegation

46. White-Label Isolation

47. Price Governance

48. Commercial Analytics

49. Anomaly Detection

50. Conceptual Persistence Model

51. Recommended Event Flow

52. Example — Report Allowance

53. Example — AI Included Allowance

54. Example — White-Label Partner

55. Failure Semantics

56. Non-Goals

57. Initial Implementation Phases

Phase 1 — Metering Foundation

Phase 2 — Entitlements and Allowances

Phase 3 — Rating and Charge Accounting

Phase 4 — Cost Accounting

Phase 5 — Invoice Integration

Phase 6 — White-Label Settlement

58. Acceptance Criteria

59. Architectural Decisions

60. Final Principle