Forward Compatibility

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 in the current SDK and sandbox implementation. The sandbox capabilities document supplies the evaluation vocabulary; the registry is not bundled into the SDKs.

A new sandbox rule entry can therefore be exercised without an SDK upgrade.

// This works today for any category the census introduces — no SDK upgrade
const verdict = gk.isAllowed({ category: "age_appropriate_profile_mode" })
// decision: "block" if no cached rule (fail-closed), or the rule's decision if present

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 Trust List entries, keys, and draft tier fields

New synthetic parties propagate through the runtime-fetched, signed sandbox registry. The SDK can pick them up on a later refresh. In the target production architecture, the same mechanism would distribute independently governed signer updates.

This demonstrates runtime key discovery; it does not establish a production network or peer standing.

Your own rating vocabularies

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

const gk = createGatekeeper({
  // ...
  ratingMappings: [
    { ocssCategory: "content_rating",  myField: "mpaaRating",  vocabulary: "mpaa" },
    { ocssCategory: "age_gate",        myField: "maturityAge",  vocabulary: "age_band" },
    // Add new mappings here — no SDK reinstall
  ],
})

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

OCSS-Spec-Version: 1.0    ← client sends; server returns agreed version
OCSS-Spec-Version: 1.2    ← server may have updated; client running 1.0 still works

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

# Inspect the sandbox capabilities document
phosra caps
 
# Machine-readable
phosra caps --json | jq '.rule_categories | length'
# 123

The sandbox capabilities document is the runtime source of truth for what the evaluation host accepts. It does not prove downstream enforcement by a real platform.

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

• CLI quickstart — phosra caps to inspect the live capabilities document
• OCSS Conformance Status — live vs. preview surface-by-surface