Versioning

#Introduction

There are two version numbers in the zipRACK standard, and they move independently:

Your applet binds to both. As long as neither changes, an applet built two years ago keeps working on a Rack built today.

#The Format String

"schema": "ziprack/1" versions the envelope (ns, v, the ack shape), the core manifest fields, and the installer's file rules. A Rack refuses a manifest with any other schema, and the error names what it speaks.

#Capability Versions

Your manifest declares id@version references. Each Rack implements its own set of them and can report that set. For example, a Rack implementing every capability in this documentation reports:

format: ziprack/1
capabilities: activity@1, ai@1, attempt@1, auth@1, broadcast@1, db@1, storage@1

An applet requesting something outside that set is refused at install, not at runtime, with a message naming what is implemented. A portability problem therefore surfaces when you upload the package, never in the middle of a participant's session.

#Version Pinning

You do not declare pinning. The Rack derives it from the capabilities you request:

A pinned participant stays on the version their attempt started on, because activity ids cannot shift mid-attempt without corrupting the export. An app rolls, so nobody is stranded on a stale build. See Attempts for the authoring consequences.

#Applet Versions

Your own version field is semver, unique per applet, and uploadable exactly once. Bump it for every upload, including test builds. The installer refuses a duplicate rather than overwriting it: a version is immutable, so what a participant ran is always recoverable.

Between versions:

• Changing an activity id splits an export column.
• Changing a label changes only the header.
• Adding a capability or a profile attribute blocks promotion until approved.
• Adding or removing attempt@1 flips the applet between pinned and rolling, and is flagged prominently in the diff.
• Adding, dropping or reshaping a collection is checked against the data at promotion.

#Applet Versions and Data

Versions are immutable; data is not. db@1 records in user, room and applet scope belong to the applet and carry over every promotion, forward or back, so a new version starts from the data the last one left. attempt records stay with their attempt and the version it ran on.

What changes between versions is the shape the data must have. At promotion, the Rack compares the outgoing collections with the new ones, validates the existing records against the new schemas, and refuses to lose data silently. A version whose schema rejects existing records, or that drops a collection holding records, waits for an explicit confirmation.

When a version needs records reshaped, you may ship a data migration with up and down. The Rack runs it at promotion and records it per applet, and every cutover that changes data is preceded by a snapshot. Data Across Versions has the full list of cases.