Skip to main content

Policy model

This page defines the gate policy data model and the constraints you should design against.

Policy scope​

A policy is evaluated in the context of:

  • one realm
  • one bundle
  • one feature code
  • one policy kind (rate, quota, seats)

Bundles are assignment-level packaging units; policies are rule units inside a bundle.

Supported kinds​

Rate​

  • Controls request admission frequency.
  • Uses limit_count.
  • Uses window_sec with window_sec >= 0.

Quota​

  • Controls consumable quantity over time.
  • Uses limit_minor.
  • Requires window_sec > 0.
  • limit_minor = -1 means unlimited quota.

Seats​

  • Controls active seat cardinality for a feature scope.
  • Uses limit_count.
  • Requires unit = seat.
  • Supports limit_count = -1 as unlimited seats.

Shape constraints​

Per-kind field combinations are strict:

  • quota: must have limit_minor, must not have limit_count
  • rate: must have limit_count, must not have limit_minor
  • seats: must have limit_count, must not have limit_minor

Metadata keys consumed by runtime​

gate_policies.metadata supports extension data, and some keys are consumed by runtime.

Quota and rate windows​

Supported keys:

  • feature_code or params.feature_code: feature target override.
  • counter_key or params.counter_key: counter identity override.

Seats billing​

Supported keys:

  • billing_feature_code: billed feature target for seat billing records.
  • billing_meter_code: billed meter target for seat billing records.
  • billing_mode: assigned or active_window.

Status model​

Policy status values:

  • default
  • assignable
  • ceiling
  • disabled

Meaning:

  • default: baseline policy for the same policy shape; used as a standard fallback choice in bundle design.
  • assignable: regular active policy intended for normal bundle composition.
  • ceiling: special-labeled active policy for the same policy shape. In the current runtime it is primarily a modeling/governance marker, not a separate evaluation branch from assignable.
  • disabled: policy is kept for record/audit but excluded from runtime evaluation.

Only non-disabled policies participate in runtime evaluation.

Per realm, default and ceiling are each unique for the same policy shape tuple:

  • feature_code
  • kind
  • unit
  • window_sec

Bundle and wildcard behavior​

  • Runtime policy lookup starts from the account's current bundle.
  • If needed, wildcard feature policies from the realm default bundle can be used as fallback.
  • Seats are enforced separately from rate/quota windows.

Ceiling design goal​

ceiling is designed as an explicit upper-bound track for a policy shape, so policy composition can have a deterministic cap.

Typical targets:

  • platform-level hard upper bound for safety/compliance
  • sales/contract customization boundary (custom plans can increase limits, but not past ceiling)
  • future multi-source policy composition guardrail

Current state:

  • ceiling already exists as a distinct policy status with dedicated uniqueness constraints.
  • Runtime evaluation currently does not apply a separate enforcement branch for ceiling; it remains a governance/modeling marker until explicit ceiling enforcement is enabled.

Modeling guidance​

  • Keep feature codes stable and explicit.
  • Use wildcard policies only for broad baseline behavior.
  • Prefer explicit feature policies for product-critical paths.
  • Keep seats policies isolated to features that truly require concurrent identity control.

Next​