Cohorts & releases
Understand why publishing creates immutable, content-addressed history instead of editing live rows.
A plan key such as pro is a lineage. Each material contract change mints a
new immutable compiled plan and a new immutable
commercial release that contains it.
Subscribers still served under the same release form a cohort.
Why releases are immutable
A customer's invoice, entitlement, route policy, measurement schema, and rating must be explainable from the terms that applied when the request was admitted. Editing one live row in place would erase that evidence and make retries or delayed events ambiguous.
A release is therefore content-addressed: its id is derived from the hash of every artifact it binds — compiled plans, route grants, measurement schema, admission descriptors, rating contexts, commercial policy. Republishing identical content yields the same id. Activation appends to a per-business release log; it never rewrites.
Usage is rated under the admitting release
The gateway stamps the served identity — subscription, release, rating context — inside the signed usage event. Core rates against that stamped release, not against whatever release is current when the event arrives. A later publish or rollback cannot invalidate already-admitted work.
A diff compares two releases
farthershore commercial-release diff <from-release.json> <to-release.json> --format json
The output names compiled plans added, removed, and changed; rating-context versions added and removed; and every changed manifest path.
Cohorts are not product plans
Do not create a new plan key merely to represent every historical price. Keep a stable key for one intended plan lineage and let releases preserve its history. Create a distinct plan key when the product offer is genuinely different.
Old does not mean mutable or abandoned
An older cohort can remain active indefinitely. Usage, limits, and rating continue against its frozen release. Runtime code must resolve the subscriber's served release rather than assuming the latest source contract applies to everyone.
Operational implications
- Inspect active dependents before removing routes, backends, integrations, or meters.
- Do not delete source declarations while retained cohorts still reference them.
- Treat delayed settlement events as events about the release recorded in their durable state, not whatever is current now.
- Treat move-to-latest as a separate post-launch operation; release activation never changes subscriber pins.
Continue with Plan transitions.