Versioning & support

Will the next fidra release break your integration? The honest answer: the wire contract is frozen and CI-enforced, pinning works by deployment URL, and here is exactly what each mechanism does and does not give you.

What counts as a breaking change

• The fidra:v1:* message names and payload shapes are additive-frozen. New message types may be added; changing the shape of an existing one requires a protocol bump (a new proto value), enforced by a CI contract test. You can branch on proto.
• The raw event schema is versioned by schemaVersion on every payload. Any field change to the envelope or any event type fails CI unless the version is bumped in the same commit. If you consume raw events, branch on that number.
• The outcome (measurement) contract has its own independent schemaVersion; a breaking change bumps it and keeps the prior validator running.

How you pin — stated plainly

• Auto-updating (default): embed fidra-embed.js from the production host — always the current release. Safe for the event contract because fidra:v1 is additive-frozen. window.Fidra.version reports the running SDK version, window.Fidra.protocol the wire protocol.
• Pinned: embed from a specific immutable deployment URL and upgrade deliberately. Every Vercel deployment is immutable and stays addressable.
• What does NOT exist today: a config key that pins a major version on the auto-updating URL (e.g. version: 1 in the mount config). Pinning is by URL only. If URL-pinning does not fit your change-management process, raise it at kickoff — do not assume config-pinning exists.

Release & rollback discipline

• Every build bakes a release tag (fidra@<version>+<commit>) into client error reports and /api/health — a crash or a probe is attributable to an exact build.
• Deployments are immutable; production rollback is a re-alias of a previous known-good deployment — near-instant, no rebuild.
• Staging (https://staging.fidra.tech) runs ahead of production and is where your integration should live until go-live.

Deprecations

Superseded surfaces keep working alongside their replacement (the pattern to date: the legacy pre-v1 event message still ships alongside fidra:v1:event for already-integrated hosts — new integrations must not use it).

Support