Bump the share archive to schemaVersion 8 for userFigures, once builds that refuse a newer archive are retired

Start with packages/compendium_core/lib/src/serialization/compendium_archive.dart and archive_codec.dart, then read the specified archive user figures tests and docs/dev/releasing.md. The issue proposes adding share-only schema v8 stamping, corresponding tests, docs, and a changelog fragment. Before implementation, the maintainer must confirm the release and end-of-life gate in a comment; done means every gate item is met and the implementation acceptance criteria pass.

Summary

Since #1804, a shared archive can carry a userFigures section: the definitions of the user's own new figures (#1023) that its dances use. It is deliberately written without an archive schemaVersion bump. This issue tracks adding that bump, to schemaVersion 8, and the conditions that must hold before it may land.

Do not start the implementation until every item under When is checked. Merging it earlier strands users on 0.7.0 and older: a bundle someone shares with them is refused outright.

Background: what was decided, and by whom

The maintainer decided this during the #1023 work (PR 10, which became #1804). It was asked in the session that implemented #1023, and these are the maintainer's words, verbatim:

Don't bump for now but make an update to support 'always bump' so that in the future we can bump with the originally intended outcome. Track a new TODO at the end of your plan to open a tracking issue, since opening one now wouldn't have the context it needs to make sense.

#1804 did both halves of that decision:

1. No bump. encodeArchive writes userFigures in share mode only, and requiredSchemaVersion ignores it. The reason is written in the doc comment on archiveSchemaVersion (packages/compendium_core/lib/src/serialization/compendium_archive.dart, the "Not versioned:" paragraph) and in docs/design/imports.md (the "Not versioned, by the maintainer's decision" bullet).
2. "Support always bump". ArchiveIntakeService.validateJson (app/lib/src/data/archive_intake_service.dart) no longer refuses an archive whose schemaVersion is newer than the build knows. It lets the archive through to the review, which reads the fields it knows and shows one "made by a newer version" warning, as the Import screen always has.

The "when" conditions and the implementation steps below are the issue author's proposal (Claude, working on #1023), not a maintainer decision. They are derived from the code as of main at ccc50690. The maintainer should confirm or amend the gate before it is acted on, and record that confirmation in a comment here.

Why the bump is wanted

Each earlier bump (v2–v7) exists so that an older reader, which skips keys it doesn't know, warns instead of silently losing data (see the version history on archiveSchemaVersion). The same holds for userFigures. A build that predates the section ignores it, and imports the dances with each use of a figure as its stored line of plain text. The figure definitions are dropped without a word. With the bump, such a reader shows the "made by a newer version" warning, so the loss is visible.

Why it cannot land yet

On 0.7.0 and every earlier build, opening an archive with a newer schemaVersion from the share sheet or "Open with" is refused: the bundle is not imported at all. (Their Import screen still reads it, with the warning.) Only builds containing #1804 accept it at the share intake. So, while 0.7.0 is in use, a bump turns "imports with plain-text figures" into "refused" for the commonest way bundles arrive. That outcome is worse than the one the bump fixes.

git tag shows v0.7.0-beta as the latest release, and #1804 merged after it. No released build has the tolerant intake yet.

When (the gate)

All of the following must be true before the implementing PR is merged. It may be drafted earlier, but must not merge, because main is what the next release ships.

• A stable release containing #1804 has shipped. That is the first release after 0.7.0: check that its tag is a descendant of #1804's merge commit, 90d78fbf. Call it R. A beta tag alone is not enough: a beta release refreshes only beta.json, so stable-channel users never see it (docs/dev/releasing.md, "Channel routing").
• An end-of-life notice for builds through 0.7.0 has shipped in a stable release. That is an entry {"through": "0.7.0", "endOfLife": "<date>"} in tools/release/retirements.json, committed before tagging a stable release. The procedure is docs/dev/releasing.md, "Announcing an end of life for older builds". 0.7.0 is the right through because it is the newest release whose share intake refuses a newer archive. A release cannot retire itself, so this can ride in R only if R is newer than 0.7.0, which it will be.
• That endOfLife date has passed at the time the implementing PR merges.
• The maintainer has confirmed in a comment on this issue that the gate is met, or has amended it.

Known limitation, accepted by this proposal: builds up to and including 0.6.0-beta cannot show the end-of-life notice at all (releasing.md). They also predate the tolerant intake, so after the bump they refuse figure-carrying bundles at the share sheet, as they already refuse any newer archive. The maintainer should decide whether that population still matters.

How (the implementation)

One PR, in packages/compendium_core plus docs. Follow AGENTS.md: docs in the same PR, a changelog fragment, every new guard test proven to fail, and the full python3 tools/preflight.py --require-available before pushing.

1. The version constant

In packages/compendium_core/lib/src/serialization/compendium_archive.dart:

• Add const int archiveSchemaVersionUserFigures = 8;, with a doc comment in the style of archiveSchemaVersionDeletedTags. It should say:
  • what an older reader does without the bump (drops the definitions silently);
  • that the stamp applies to share mode only;
  • that it is stamped only when the section is written.
• Set const int archiveSchemaVersion = archiveSchemaVersionUserFigures;.
• Add a v8 bullet to the version history in archiveSchemaVersion's doc comment.
• Replace the "Not versioned:" paragraph. Its history belongs in the v8 bullet: written unversioned from #1804, versioned from this change, and why the wait.

Don't confuse the two version numbers. docs/design/storage.md lists a database schema "v8 (2026-07-14)". That is unrelated to the archive envelope version.

2. Stamp it, in share mode only

requiredSchemaVersion(archive, {includeDeletedTags = true}) takes the minimum version an archive needs.

• Add a parameter includeUserFigures that defaults to false. It must not default to true, because compendium_archive_import.dart (the archiveCarriesVenueLinks line) calls requiredSchemaVersion(archive) >= archiveSchemaVersionVenues to decide whether an archive has venue semantics. If the default were true, any imported share bundle carrying figures would read as v8, so ≥ 2. Its programs' null venueIds would then overwrite venue links the user set after an earlier import.
• Check it first. The function documents "Keep new cases in descending version order or a lower version will shadow a higher one". Add if (includeUserFigures && archive.userFigures.isNotEmpty) return archiveSchemaVersionUserFigures; above the deletedTags check, and update the function's doc comment.
• In encodeArchive (packages/compendium_core/lib/src/serialization/archive_codec.dart), pass includeUserFigures: mode == ArchiveSerializationMode.share, beside the existing includeDeletedTags.
  • Backup mode never writes userFigures (a backup carries the whole glossary in its own section), so a backup must never be stamped 8 on its account.
  • Fix the comment on the 'userFigures' entry, which says "never a version bump (see archiveSchemaVersion)".
• Leave the share intake alone. It must keep letting newer archives through; that is what makes the next bump safe too.

3. Tests (each new guard shown red, per docs/dev/agents/verification.md)

In packages/compendium_core/test/serialization/archive_user_figures_test.dart:

• Rewrite the test share mode writes each figure without its notes or kind, and the stamp is what it would be without them. Its last two expectations pin "no bump". They become:
  • a share archive carrying a figure is stamped archiveSchemaVersionUserFigures;
  • the same archive with no figure keeps its earlier stamp.
• Fix the file's header comment ("never a version bump (maintainer decision on PR 10)").
• Add a test that a backup of an archive whose userFigures is non-empty is not stamped 8.
• Add a test that requiredSchemaVersion(archive), with no arguments, ignores userFigures. This guards the venue check above.
• Add a test that a share archive with a figure and a tombstoned tag is stamped 8. Share mode never writes deletedTags, so this pins the ordering.

Red runs to record in the PR (each mutation made on a commit, restored with git checkout <sha> -- <path>, never git stash):

Mutation	Expected red
Delete the new check in requiredSchemaVersion	The share-stamp test
Pass includeUserFigures: true in backup mode as well	The backup test
Default includeUserFigures to true	The no-argument test
Move the new check below the deletedTags check	No test goes red: it is shadowed only if a share archive could carry deletedTags, which it can't. Say so in the PR rather than claiming a red run.

Also run archive_deleted_tags_test.dart, unreadable_figures_test.dart and unreadable_tunes_test.dart, which call requiredSchemaVersion directly, and the app's share-bundle tests under app/test/export/.

4. Docs

• docs/design/imports.md: replace the "Not versioned, by the maintainer's decision" bullet under "Your own figures" with the v8 rule and its history (decided in #1804, landed here once the gate in this issue was met).
• docs/user/imports.md: check the "made by a newer version" passages. A person on R or later who receives a v8 bundle from a newer build sees that warning even though their build reads the figures. That is expected and harmless, but the text must not promise otherwise.
• Changelog: a changelog.d/<id>.json fragment with a core "changed" entry (archiveSchemaVersion is 8; a shared archive carrying the user's own figures is stamped 8). Add an app entry only if user-visible behaviour changes for the sender. The sender's app writes the same bundle, and only older receivers react differently, so user_visible: false is probably right. Follow changelog-structure: a fragment with user_visible: false cannot have an app entry.

5. Before merging

• Re-check every box under When on the day of merge, and link the release tag and the retirements.json commit in the PR body.
• Re-derive the "newest refusing release" from source, as docs/dev/agents/releasing.md asks for versions. The refusal is the enum value ArchiveIntakeRejectionReason.newerVersion, which #1804 removed:
  • git show v0.7.0-beta:app/lib/src/data/archive_intake_service.dart | grep -n newerVersion finds it;
  • the same command on R's tag, and on every later tag, must find nothing.

Acceptance criteria

• A share-mode archive with a non-empty userFigures is stamped schemaVersion 8. Every other archive is stamped exactly as before, backups included.
• requiredSchemaVersion called without the new argument returns what it returns today.
• Every gate item above was met before merge, with links in the PR.
• The design and code docs no longer say the section is unversioned.

Related

• #1023: user-defined figures (closed).
• #1804: the userFigures section and the tolerant share intake.
• #1810: receiving a bundle's figures.
• docs/dev/releasing.md: "Announcing an end of life for older builds".

---

Generated by Claude Code