Skip to main content
The integration contract is the wire protocol, not your installed SDK version. Most evolution reaches you as runtime data, so you keep the package you have installed.

​
What is zero-reinstall today

​
New rule categories

rule_category is an opaque string end-to-end — @phosra/link.directive() forwards it verbatim, and @phosra/gatekeeper evaluates whatever category the census-served profile carries, generically. The census is the sole vocabulary authority; the rule registry is not bundled into the SDKs. A new rule is a census-side change — your installed SDK already routes it.

​
New parameters on an existing rule

Parameters are carried in the open params JSON object and validated server-side per category. Add a new parameter to an existing rule → census-side deploy, zero client change.

​
New accredited parties, keys, and trust tiers

New parties propagate through the runtime-fetched, signed Trust List — verified to root locally, refreshed at runtime. When a new router, issuer, or verifier joins the network and is added to the Trust List, your SDK picks it up on the next refreshProfile poll. No reinstall required to trust a new signer.

​
Your own rating vocabularies

The platform’s ratingMappings are runtime config passed to createGatekeeper:

​
What happens with an unrecognized rule

A category your gatekeeper has no interpretation for fails closed (blocks). This is the correct safe default — enforcement never silently passes an unknown rule. To interpret a genuinely new rating semantic (a new params.scale value), add a ratingMappings entry at runtime. You do not need to upgrade the SDK to handle the new vocabulary.

​
API evolution rules Phosra holds to

​
Additive-only

We never remove or repurpose a response field. New behavior arrives as new optional fields that your installed SDK simply ignores. Breaking-field changes are not permitted without a major version bump (see below).

​
Major-only version negotiation

The OCSS-Spec-Version negotiation contract:
  • Negotiation happens on the major version only
  • Higher minor versions are tolerated — a minor spec revision is a server-only deploy
  • Installed clients and cached profiles are never locked out by a minor bump
phosra doctor checks this negotiation (check 4, version_negotiates) every time.

​
Capability discovery — /.well-known/ocss/capabilities

The census publishes a root-signed capabilities document at /.well-known/ocss/capabilities. Your SDK fetches and verifies it at runtime to discover:
  • Current OCSS spec version and version range
  • All 123 rule categories with their tiers (anchored / provisional) and floors
  • Decision verbs and safety classes
  • Parameter families and rating crosswalk ordinals
The capabilities document is the runtime source of truth for what the census currently enforces — the SDK does not bundle a static copy of the rule vocabulary.

​
When a reinstall IS needed

Only for a genuinely new client-side local verb (a new SDK method). Examples:
  • A new rule category that requires new local decision logic (not just a new opaque string)
  • A new SDK API method added to @phosra/link or @phosra/gatekeeper
These ship as opt-in, non-breaking semver-minor releases and are server-gated — an installed client that does not upgrade continues to work exactly as before. The new surface is additive; existing integrations do not need it to stay green. A breaking wire change (a fleet-wide major bump) is reserved for true protocol breaks and should be near-never. phosra doctor would surface this as a version_negotiates: FAIL.

​
Hardening items in progress

The following items make every minor spec change a zero-reinstall deploy. They are tracked in docs/superpowers/specs/2026-06-27-zero-reinstall-extensibility.md (checklist D1–D6):

​
Next