G3N Common Contract

Appearance

Storage Billing ​

Status: Implemented (storage usage ledger + scheduled ingestion sweep + manual reconcile endpoint).

Purpose ​

Define how storage usage is attributed for billing in an org-scoped, cost-centre-aware way.

Billing model (business) ​

  • Bill on logical bytes (data size as stored, not compressed transfer size).
  • Object storage usage is billed using a single blended rate.
  • Record storage usage is tracked as a separate usage line item.
  • Include storage for any data attributable to an org or cost centre, including audit and event logs when attributable.
  • Track usage via event-driven ledgers with periodic reconciliation.

Attribution rules ​

  • Every record that references an org (and optional cost centre) participates in storage usage accounting.
  • When cost-centre attribution is present, usage is attributed at both org and cost-centre levels.

Ingestion sweep ​

  • Accounting runs a scheduled storage usage sweep to record usage per org from all attributable data sources (event logs, object storage, operational records).
  • Usage records are written as windowed measurements with a window (from_utc → to_utc) and measured_at.
  • The sweep is asynchronous and does not add latency to operational API calls.

Reconciliation (manual) ​

  • Use POST /accounting/storage/usage/reconcile to reprocess a specific window (from_utc → to_utc) for an org.
  • Supports bounded runs via limit and optional cursor for continuation; dry_run returns a summary without recording usage.
  • Reconcile runs are idempotent per org + window + resource prefix; repeats will not duplicate usage records.

Current limitations (prototype) ​

  • Record-level usage is derived from changelog snapshots (write-volume approximation).
  • Some storage categories without org-prefixed keys require a dedicated reconciliation pass (future).
  • Billing should treat usage records as windowed measurements and apply retention-aware rollups.

Retention and pointer lifetime (billing relevance) ​

  • Retention windows affect billed storage; policy changes must be auditable.
  • Events that reference external payloads must not outlive those payloads unless a compliant tombstone is retained.
  • See /common/security-compliance.html for retention baselines and pointer lifetime rules.