Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

84.0 KB
Raw Blame
/**
 * PortOS schema-version contract for cross-instance sync.
 *
 * Two PortOS instances that exchange data (federated peer push, snapshot
 * sync, share-bucket manifests) need a way to detect a version mismatch
 * BEFORE applying records the receiver can't parse. Without this, an
 * upgraded sender silently corrupts a downstream peer whose code doesn't
 * yet understand a new storage layout.
 *
 * `PORTOS_SCHEMA_VERSIONS` is the per-sync-category WIRE contract — distinct
 * from the storage-layout version stamped on `data/{type}/index.json` (see
 * each service's local `TYPE_SCHEMA_VERSION` const). Bump the wire contract
 * for either:
 *   (a) a storage layout change (e.g. universes 4→5 splitting out of the
 *       monolithic JSON), OR
 *   (b) an additive record-shape change that a not-yet-upgraded peer would
 *       silently strip on round-trip (e.g. pipelineSeries 1→2 for the
 *       `series.arc.readerMap` field).
 * For (a) ship the corresponding `scripts/migrations/NNN-…js` to update the
 * stamped storage version too; for (b) the local storage layout stays put.
 * The number flows through every outbound payload's `portosMeta.schemaVersions`;
 * receivers compare incoming vs local and reject ahead-mismatches (sender too
 * new) or behind-mismatches (sender too old to satisfy a forward-only field).
 *
 * Absent categories default to 0. Receivers choose which mismatch directions
 * to reject; live catalog rows require equality even for unversioned peers.
 * Future PRs that introduce a layout change for `series`, `issues`, etc.
 * add an entry here.
 */

import { join } from 'path';
import { PATHS, tryReadFile, safeJSONParse } from './fileUtils.js';

export const PORTOS_SCHEMA_VERSIONS = Object.freeze({
  // Numeric-only peer wire payload (v1); read-through, never imported into local records.
  // Checked-in `.quality.json` is file schema v2 and must not bump this number.
  appQuality: 1,
  // Memory pull negotiates this capability explicitly. Version numbers describe
  // the sender's local history; receivers retain their own monotonic history.
  memoryHistory: 1,
  // Type-level (storage layout) version for `data/universes/{id}/index.json`.
  // v5 = post-split. Migration 034 introduced it. The independent per-record
  // shape is currently v5 (stamped inside each record by `sanitizeTemplate`).
  // v6 = canon characters gained `relationshipLinks[]` (structured
  // character-to-character links + opposing-force tags, #1287). Additive +
  // gracefully degrading, but version-gated for the same reason as
  // `pipelineIssues`/`pipelineSeries` v2: a not-yet-upgraded peer that receives
  // and re-sanitizes a universe through its relationshipLinks-unaware
  // `sanitizeCharacter` would silently strip the field and last-writer-wins the
  // loss back onto the newer peer. Bumping makes the older peer reject the
  // ahead-version universe transfer instead. Per-category gate → only universe
  // sync pauses with old peers; pipeline/catalog/etc keep flowing.
  // v7 = canon objects gained `attachments[]` (structured object↔character
  // emotional-attachment links — emotion/significance/origin/role, #1288).
  // Same rationale as v6: additive + gracefully degrading, but version-gated so
  // a not-yet-upgraded peer that re-sanitizes a universe through its
  // attachments-unaware `sanitizeObject` can't silently strip the field and
  // LWW the loss back onto the newer peer.
  //
  // v8 adds shared styleReferences[]. Older peers must not sanitize the field
  // away and LWW-sync that loss back to a newer install.
  // v9 = `moodBoardId` added (#4188) — the universe's linked mood board. The
  // pointer rides the wire (mood boards federate, so the id resolves on peers);
  // same rationale as v6/v7/v8: additive + gracefully degrading, but an older
  // peer that re-sanitizes a universe through its moodBoardId-unaware
  // `sanitizeTemplate` would silently strip the link and LWW the loss back.
  // v10 = character `voiceCanon` and `identityPack` added (#5378). These are
  // portable, federated production-canon fields; a ≤v9 peer would sanitize
  // them away and LWW the loss back after an unrelated Universe edit.
  // v11 = character `psychology` added (#6414) — the optional structured
  // theory-of-control + survival/connection/status drive profile. Additive and
  // gracefully degrading, but version-gated for the same reason as v6–v10: a
  // ≤v10 peer that re-sanitizes a universe through its psychology-unaware
  // `sanitizeCharacter` would strip the profile and last-writer-wins the loss
  // back onto the newer peer. Per-category gate → only universe sync pauses
  // with old peers.
  // v12 = universe `factual` added (#7616) — the factual/fiction axis that
  // tells the catalog extractor to read a world's material as lived record
  // rather than invented story. Persisted only when true, but federated: a
  // <=v11 peer would strip it in its `factual`-unaware `sanitizeTemplate`
  // and last-writer-wins the loss back, silently reclassifying the user's
  // Reality universe as fiction.
  // v13 = durable character sheet request identities (#11669). Older peers
  // must not strip supersession state during an unrelated canon edit.
  // v14 = canon entries gained optional `forms[]` (alternate ages, eras and
  // looks/styles beside the canonical present-story form). A <=v13 peer would
  // sanitize them away and LWW the loss back.
  universes: 14,
  // v1 = post-split. Migrations 035/036 introduced the pipeline collection
  // layout for issues and series.
  // v2 = `stages.audio.audioMode` + `stages.audio.cues[]` added (whole-episode
  // audio, issue #863). Additive, but version-gated for the same reason
  // `pipelineSeries 1→2` (readerMap) is: an older, audioMode/cues-unaware peer
  // that receives and re-sanitizes the record would silently strip the new
  // fields and last-writer-wins the loss back onto the newer peer. Bumping
  // makes the older peer reject the ahead-version issue transfer instead.
  // Per-category gate → only issue sync pauses with old peers; series/universes
  // keep flowing.
  // v3 = `issue.arcRole: "climax"` added (#4454). A <=v2 peer rejects the
  // ahead-version transfer; when its older snapshot is later received by a v3
  // peer, the merge preserves an existing climax role instead of letting the
  // older sanitizer's omission LWW-strip or overwrite it.
  // v4 = text-stage generation identity for owner-scoped restart recovery.
  // Older sanitizers strip it; gate transfers to keep execution ownership intact.
  pipelineIssues: 4,
  // v2 = `series.arc.readerMap` added (Unified Story Builder). Additive +
  // gracefully-degrading, but version-gated so a not-yet-upgraded peer can't
  // round-trip a series through its readerMap-unaware sanitizer and LWW-strip
  // the field back onto a newer peer. Per-category gate → only series sync
  // pauses with old peers; issues/universes keep flowing.
  // v3 = `series.arc.tickingClock` added (#1289). Same situation as readerMap:
  // an additive field INSIDE the series.arc payload, so a ≤v2 peer that receives
  // and re-sanitizes a series through its tickingClock-unaware `sanitizeArc`
  // would silently strip the countdown and last-writer-wins the loss back onto
  // the newer peer. Bump makes the older peer reject the ahead-version series
  // transfer instead. Per-category gate → only series sync pauses with old peers.
  // v4 = `series.styleGuide` added (#1303) — a top-level series house-style
  // field (tense/POV/audience/rating/reading-level/tone/conventions). Same
  // silent-strip-then-LWW corruption as readerMap/tickingClock, just one level
  // up: a ≤v3 peer re-sanitizes a series through its styleGuide-unaware
  // `sanitizeSeries`, drops the guide, and last-writer-wins the loss back onto
  // the newer peer. Bump makes the older peer reject the ahead-version series
  // transfer instead. Per-category gate → only series sync pauses with old peers.
  // v5 = `series.coverImage` added — a top-level derived field holding the
  // filename of a rendered volume/issue cover, shown as a thumbnail on the
  // pipeline series list. Derived (any peer can recompute it from its own
  // seasons/issues), but it's only recomputed on cover-render or the one-time
  // boot backfill — never on every read — so a ≤v4 peer that re-sanitizes a
  // series through its coverImage-unaware `sanitizeSeries` would drop the
  // pointer and LWW the loss back onto the newer peer, where it may never
  // recompute (a finished series renders no new cover). Gate so the older peer
  // rejects the ahead-version transfer instead. Per-category gate → only series
  // sync pauses with old peers.
  // v6 = `series.characterArcs[]` added (#1293) — per-character story arcs
  // (want/need, start → end state, transition beats). Same silent-strip-then-LWW
  // corruption as readerMap/tickingClock/styleGuide: a ≤v5 peer that re-sanitizes
  // a series through its characterArcs-unaware `sanitizeSeries` would drop the
  // arcs and last-writer-wins the loss back onto the newer peer. Bump makes the
  // older peer reject the ahead-version series transfer instead. Per-category
  // gate → only series sync pauses with old peers.
  // v7 = `series.factCritical` + `series.factReference` added (#1588) — the
  // opt-in flag + author-supplied real-world fact reference the gated
  // `research.fact-accuracy` editorial check reconciles the prose against. Same
  // silent-strip-then-LWW corruption as styleGuide/characterArcs: a ≤v6 peer
  // that re-sanitizes a series through its factReference-unaware `sanitizeSeries`
  // would drop the reference (and reset the flag) and last-writer-wins the loss
  // back onto the newer peer. Bump makes the older peer reject the ahead-version
  // series transfer instead. Per-category gate → only series sync pauses with old peers.
  // v8 = `series.editorialCheckConfig` added (#1591) — a per-series map of
  // editorial-check config overrides ({ [checkId]: { [key]: value } }) that tune a
  // check's thresholds (e.g. comic lettering density) for one series without
  // touching the global catalog. Same silent-strip-then-LWW corruption as
  // styleGuide/characterArcs: a ≤v7 peer that re-sanitizes a series through its
  // editorialCheckConfig-unaware `sanitizeSeries` would drop the overrides and
  // last-writer-wins the loss back onto the newer peer. Bump makes the older peer
  // reject the ahead-version series transfer instead. Per-category gate → only
  // series sync pauses with old peers.
  // v9 = `series.severityWeights` + `series.blockingSeverities` added (#1616) —
  // per-series overrides of the editorial health-score severity weights (default
  // high:12/medium:5/low:1) and of which severities count as blocking for each
  // autopilot gate (arc/beatContinuity/editorial). Both default to `{}` (no
  // override → frozen defaults apply). Same silent-strip-then-LWW corruption as
  // editorialCheckConfig: a ≤v8 peer that re-sanitizes a series through its
  // severityWeights/blockingSeverities-unaware `sanitizeSeries` would drop the
  // overrides and last-writer-wins the loss back onto the newer peer. Bump makes
  // the older peer reject the ahead-version series transfer instead. Per-category
  // gate → only series sync pauses with old peers.
  // v10 = `series.arc.foreshadowing` added (#2172) — the arc-overview-emitted
  // plant → reinforce → payoff ledger the Chekhov check consumes. Same additive
  // field INSIDE the series.arc payload as readerMap (v2) / tickingClock (v3): a
  // ≤v9 peer that re-sanitizes a series through its foreshadowing-unaware
  // `sanitizeArc` would silently strip the ledger and last-writer-wins the loss
  // back onto the newer peer. Bump makes the older peer reject the ahead-version
  // series transfer instead. Per-category gate → only series sync pauses with old peers.
  // v11 = `series.styleGuide.voiceExemplars` + `series.styleGuide.voiceAntiExemplars`
  // added (#2179) — the voice exemplar / anti-exemplar "tuning fork" passages. Same
  // additive field INSIDE the federated `styleGuide` sub-object as styleGuide itself
  // (v4): a ≤v10 peer that re-sanitizes a series through its voiceExemplars-unaware
  // `sanitizeStyleGuide` would silently strip the passages and last-writer-wins the
  // loss back onto the newer peer (`preserveAbsentAdditiveFields` only restores a
  // wholly-absent `styleGuide`, not a present-but-sub-field-stripped one). Bump makes
  // the older peer reject the ahead-version series transfer instead. Per-category gate
  // → only series sync pauses with old peers.
  // v12 = `series.exportSettings` added (#2181) — the per-series prose-export
  // config (trim size, interior font, title-page fields) for the compiled-
  // manuscript / ePub / print-interior-PDF exports. Top-level additive field
  // like styleGuide (v4): a ≤v11 peer that re-sanitizes a series through its
  // exportSettings-unaware `sanitizeSeries` would silently strip it and
  // last-writer-wins the loss back onto the newer peer
  // (`preserveAbsentAdditiveFields` restores a wholly-absent `exportSettings`
  // from a BEHIND-version SAME-schema peer, but a wire-received record from an
  // OLDER peer must be rejected outright). Bump makes the older peer reject the
  // ahead-version series transfer instead. Per-category gate → only series sync
  // pauses with old peers.
  // v13 = `series.characterArcs[].evolution` added (#6440) — the optional
  // five-stage character evolution lens (belief under test → pressure → choice
  // → consequence, with a declared outcome). Same additive field INSIDE an
  // already-federated sub-object as voiceExemplars (v11) inside styleGuide: a
  // ≤v12 peer that re-sanitizes a series through its evolution-unaware
  // `sanitizeCharacterArc` would silently strip the lens and last-writer-wins
  // the loss back onto the newer peer (`preserveAbsentAdditiveFields` restores
  // a wholly-absent `characterArcs`, not a present-but-sub-field-stripped
  // one). Bump makes the older peer reject the ahead-version series transfer
  // instead. Per-category gate → only series sync pauses with old peers.
  // v14: author-owned arc.seriesDesign; older sanitizers must not erase it.
  pipelineSeries: 14,
  // NOT bumped for the manuscript-review sibling doc now bundled on series
  // pushes/exports (`data/pipeline-series/{id}/manuscript-review.json`).
  // Unlike `readerMap` (v2), the review is NOT a field inside the series
  // record — it's a separate doc that rides a dedicated `manuscriptReview`
  // payload key, so an older peer never round-trips it through the series
  // sanitizer (no silent-strip-then-LWW-back corruption — the readerMap gate's
  // whole reason to exist). It is additive + gracefully degrading: a pre-feature
  // receiver ignores the unknown key (review just doesn't reach it) and ships
  // no review back, so the newer peer's `if (manuscriptReview)` receive guard
  // is a no-op and the local review is preserved. Bumping `pipelineSeries` here
  // would be actively harmful — it would 409-reject the ENTIRE series push
  // (record + issues) to every not-yet-upgraded peer over an OPTIONAL doc that
  // degrades fine. Registering a brand-new gated category would hit the same
  // whole-payload footgun documented for `videoHistory` below. So manuscript-
  // review is intentionally UNGATED today (all peers ship review-doc shape v1).
  // The FIRST incompatible review-doc shape change (manuscriptReview.js
  // SCHEMA_VERSION 1→2, where an older peer's sanitizer would strip a field and
  // LWW it back) MUST introduce a gate then — mirroring the catalog
  // payloadSchemaVersion lockstep note below.
  // ALSO not bumped for the reverse-outline sibling doc (#1348), bundled on
  // series pushes/exports as `data/pipeline-series/{id}/reverse-outline.json`
  // via a dedicated `reverseOutline` payload key. Identical reasoning to the
  // manuscript-review note above: it's a separate doc (not a series field), so
  // an older peer never round-trips it through `sanitizeSeries`; it's additive +
  // gracefully degrading (a pre-#1348 receiver ignores the unknown key and ships
  // none back, so the newer peer's `if (reverseOutline)` receive guard is a
  // no-op and the local outline is preserved); and the sender's legacy-strip
  // retry drops the key so the record/issues still land. Whole-doc LWW on
  // `generatedAt` means there's no per-field strip-then-LWW-back corruption to
  // gate against. The FIRST incompatible outline-doc shape change (reverseOutline.js
  // SCHEMA_VERSION 1→2) MUST introduce a gate then, same as the review above.
  // mediaCollections v2 = per-item `removedItems` removal records (#12433). A
  // v1 peer's sanitizer strips them and its union merge re-adds the removed
  // item, so a v2 sender is ahead and that peer refuses its collections until
  // it upgrades. A v1 sender stays accepted: its copies keep their original
  // `addedAt`, which the v2 receiver's removal records already supersede.
  mediaCollections: 2,
  // v1 = card decks (PostgreSQL `decks` + `deck_cards`) federated via the
  // per-record peer-sync push pipeline (record kind `deck`, sync category
  // `decks`). A brand-NEW synced record type, so it gets its own per-category
  // gate: a v1 sender pushing to a ≤v0 (pre-feature) receiver is sender-ahead
  // on `decks` and gets a 409 — only the decks category pauses, every other
  // category keeps flowing. A v1 receiver still accepts a ≤v0 sender
  // (sender-behind): pre-feature peers never push a `deck` record at all. The
  // v2 = deck-level `cardOrientation` + optional `cardOrientationPrompt`.
  // A v1 peer would round-trip the deck through an unaware projection and
  // silently strip a user's face-orientation choice, so only the decks
  // category pauses until that peer upgrades.
  decks: 2,
  // v1 = storyboards (PostgreSQL `storyboards`) federated via the per-record
  // peer-sync push pipeline (record kind `storyboard`, sync category
  // `storyboards`). A brand-NEW synced record type, so it gets its own
  // per-category gate: a v1 sender pushing to a ≤v0 (pre-feature) receiver is
  // sender-ahead on `storyboards` and gets a 409 — only this category pauses.
  // The FIRST incompatible board/beat/panel/take shape change MUST bump this to
  // 2 (a v1 peer would round-trip the new shape through an unaware sanitizer
  // and LWW the strip back onto the newer peer).
  // v2 = board-level `plot` (the plot summary beats are drawn from) and
  // `plotLlm` (provider/model/effort last picked for it); a v1 peer would strip
  // both, so only the storyboards category pauses until it upgrades.
  // v3 = board-level `tempTrack` (the demo song the animatic plays with); a v2
  // peer would strip it the same way.
  // v4 = song markers on the temp track (`sections`, `lines`) and a beat's
  // `pin` to one of them.
  // v5 = board-level `source` (the FableLoom episode it was made from) and a
  // panel's `sourceSceneId`, which "Use as scene art" sends art back through.
  // v6 = a `source` of kind `pipeline` (a Series Pipeline issue) and a
  // panel's `sourceShotId`; a v5 peer would drop both.
  // v7 = a panel's `sourceRev` (what its pipeline shot last took from it, so
  // only a panel edited since reads as changed); a v6 peer would drop it.
  storyboards: 7,
  // v1 = author personas (PostgreSQL `authors` table) federated via the
  // per-record peer-sync push pipeline (record kind `author`, sync category
  // `authors`). A brand-NEW synced record type like `storyBuilder` below, so it
  // gets its own per-category gate: a v1 sender pushing to a ≤v0 (pre-feature)
  // receiver is sender-ahead on `authors` and gets a 409 (the older peer's
  // `sanitizeAuthor` would silently strip any future field and LWW it back) —
  // only the authors category pauses; every other category keeps flowing
  // (per-category gate via scopeVersionDiff). A v1 receiver still accepts a ≤v0
  // sender (sender-behind): pre-feature peers never push an `author` record at
  // all, so there's nothing to gate. The FIRST incompatible author-shape change
  // MUST bump this to 2 then (where a v1 peer would round-trip the new shape
  // through an unaware sanitizer).
  authors: 1,
  // v1 = music artists/albums/tracks (PostgreSQL `artists`, `albums`, and
  // `tracks` tables) federated via the per-record peer-sync push pipeline.
  // Each kind gets its own category gate so an older peer can reject only the
  // music record type it cannot parse while unrelated categories keep flowing.
  artists: 1,
  albums: 1,
  // tracks v2 = `track.renders[]` render-history added (every generated/uploaded
  // take, so the studio shows each render as a card + can re-select an earlier
  // one). Additive + gracefully degrading, but version-gated for the same reason
  // as the universes relationshipLinks/attachments fields: a ≤v1 peer that
  // receives and re-sanitizes a track through its renders-unaware `sanitizeTrack`
  // would silently strip the history (keeping only the active pointer) and
  // last-writer-wins the loss back onto the newer peer. Bumping makes the older
  // peer reject the ahead-version track transfer instead. Per-category gate →
  // only track sync pauses with old peers; artists/albums keep flowing. The
  // backfill itself needs no migration — `sanitizeTrack` synthesizes a render
  // from the legacy active pointer on read (see services/tracks/logic.js).
  // tracks v3 = `track.chiptuneScore`/`chiptunePrompt` (#2911, the LLM-composed
  // looping 8-bit score). Version-gated for the identical strip-and-push-back
  // reason as v2: a ≤v2 peer re-sanitizing through its chiptune-unaware
  // `sanitizeTrack` would silently drop the score and LWW the loss back onto
  // the composing peer. (As of #2912 the fields DO participate in the
  // conflict-journal content hash, version-gated so it doesn't retroactively
  // invalidate a base hash stamped before they existed — see
  // lib/conflictJournal.js HASH_FIELDS, whose own version number for this
  // field was chosen to match this one for a human reading both files; the
  // two mechanisms are otherwise independent — HASH_FIELDS gates a purely
  // local hash-store concern, not cross-peer wire compatibility.)
  // tracks v4 = `track.concept` for resumable stepped music-designer drafts.
  // Older peers must reject the record rather than round-trip it through a
  // concept-unaware sanitizer and silently erase the saved creative brief.
  // tracks v5 = render-history entries gained `authoredPrompt` and the explicit
  // nullable `instrumentalOnly` decision. A <=v4 peer would strip both, then LWW
  // the ambiguous render back and make a later remix silently change vocal mode.
  // tracks v6 = render history entries preserve the effective generation
  // executionProfile. Older peers would strip the measured placement on sync.
  // tracks v7 = `track.waveSketch`/`waveSketchPrompt` (#8376, the Music
  // Designer's LLM-drawn wave sketch). Same strip-and-push-back reason as v3:
  // a <=v6 peer's sketch-unaware sanitizer would drop the drawing and LWW the
  // loss back. The accepted sender-behind direction is covered by the
  // absent-key carry in services/tracks/logic.js mergeTrackRecord.
  // tracks v8 = `track.waveSketch` may hold a `version: 2` painted-spectrogram
  // canvas (#8464, lib/paintedCanvas.js). A <=v7 peer runs every sketch through
  // its v1-only normalizeWaveSketch, which strips a painting to null, and would
  // LWW that loss back — so it must reject the record instead. Stored v1
  // sketches still normalize and render unchanged; nothing to migrate.
  // tracks v9 = render-history entries record their provenance `source`
  // (`'suno'` for a hand-imported Suno export, `'youtube'`, `'upload'`, #8967).
  // A <=v8 peer's sanitizer would strip it and LWW the unlabelled take back, so
  // an exported song would silently lose its attribution. Pre-v9 renders read
  // as `source: ''` (unrecorded); nothing to migrate.
  // tracks v10 = render-history entries gained `codeProvenance` (#9414: the
  // language, source, hash, seed, runtime version and settings of a
  // server-rendered SuperCollider take). A <=v9 peer's sanitizer would strip it
  // and LWW the unreproducible take back. Absent on every older render; nothing
  // to migrate.
  // tracks v11 = exact local audio captions and labeled prompt additions on
  // takes. Older sanitizers would erase the record of what the model received.
  // Optional on older takes; no stored records need rewriting.
  // tracks v12 = exact local audio lyric sheets and labeled lyric additions
  // on takes. A <=v11 peer would strip sentLyrics/lyricAdditions, including
  // on newly received takes where the sender-behind merge cannot restore them.
  // Optional on older takes; no stored records need rewriting.
  tracks: 12,
  // v1 = creative ingredients catalog (Postgres tables: catalog_scraps,
  // catalog_ingredients, catalog_ingredient_sources, catalog_ingredient_refs).
  // v2 = `catalog_ingredients.search_tsv` expanded to also index the
  // character canon fields (physicalDescription, personality) and the
  // type-specific role/motivations/significance fields, so bible-promoted
  // characters become searchable on their main narrative text. The schema
  // is a DROP+re-ADD of the STORED generated column (Postgres can't ALTER
  // its expression); applied in lockstep by `ensureSchema`.
  // v3 = `catalog_ingredient_refs` gained `deleted`/`deleted_at` soft-delete
  // tombstones + an UPDATE trigger that bumps sync_sequence on delete/revive.
  // Older peers (≤v2) hard-DELETE on unlink and never tombstone, so the
  // version gate prevents a v3 receiver from accepting an older sender's
  // payload that would silently miss tombstones.
  //
  // Per-category gate so a new peer can sync its catalog independently of
  // whether other categories are version-locked. Since v10, live catalog
  // rows require an exact version match; tombstones stay version-independent.
  // `cat-ingredient` and `cat-scrap` record kinds map back
  // here via RECORD_KIND_SCHEMA_CATEGORIES.
  //
  // NOT bumped for the per-record `payload.schemaVersion` stamp added by
  // catalog-payload-schemaversion: that key is additive JSONB that both old
  // and new peers store verbatim (`upsertIngredientFromPeer` writes payload
  // as-is — no sanitizer strips it), and all types are payload-v1 today so no
  // shape actually changed on the wire. The FIRST type that bumps its
  // registry `payloadSchemaVersion` to 2 with a genuine shape change (a peer
  // ≤ that version would round-trip the new shape through an unaware
  // sanitizer) MUST bump `catalog` here in lockstep.
  //
  // v4 = `catalog_ingredient_relations` table (ingredient↔ingredient edges)
  // + a new `relations: [...]` block in the catalog sync envelope. An older
  // (≤v3) receiver doesn't understand the relations block, so a v4 sender
  // pushing to it is sender-ahead on `catalog` and gets a 409 — correct,
  // since the older peer would silently drop every relation edge. v4 receivers
  // still accept ≤v3 senders (sender-behind): those envelopes simply carry no
  // `relations` block and the receiver applies the other four kinds as before.
  // v5 = `catalog_tags` first-class table (id, label, description?, color?,
  // parent_id?, created_at, sync_sequence) + a new `tags: [...]` block in the
  // catalog sync envelope. Same gating rationale as v4: a ≤v4 receiver doesn't
  // understand the `tags` block, so a v5 sender pushing to it is sender-ahead
  // and gets a 409 (otherwise the older peer would silently drop every canonical
  // tag row + its parent hierarchy). The freeform `catalog_ingredients.tags
  // TEXT[]` column is unchanged — canonical tag rows are an additive index, so
  // a v5 receiver still accepts ≤v4 ingredient/scrap/ref/relation pushes; those
  // envelopes simply carry no `tags` block.
  // v6 = `catalog_ingredient_media` join table (typed image/audio/video/doc
  // attachments) + a new `media: [...]` block in the catalog sync envelope.
  // Each media row ships a `media_key` REFERENCE into the receiver's own media
  // library (data/images + history.jsonl sidecar) — never the bytes. Same
  // gating rationale as v4/v5: a ≤v5 receiver doesn't understand the `media`
  // block, so a v6 sender pushing to it is sender-ahead on `catalog` and gets
  // a 409 (otherwise the older peer would silently drop every attachment). A v6
  // receiver still accepts ≤v5 senders (sender-behind); those envelopes carry
  // no `media` block. Media keys that don't resolve against the receiver's own
  // library surface via the metadata-missing integrity endpoint rather than
  // failing the apply.
  // v7 = `catalog_scraps` gained `chunk_index` + `parent_scrap_id` (a long paste
  // chunks into a parent + N child rows; the extractor unions per-child drafts).
  // Both fields ride the scrap sync envelope. Same gating rationale as v4–v6: a
  // ≤v6 receiver doesn't understand child scrap rows, so a v7 sender pushing to
  // it is sender-ahead and gets a 409. A v7 receiver still accepts ≤v6 senders
  // (their scraps carry no chunk fields → chunkIndex 0 / parentScrapId null).
  // v8 = user-defined ingredient types. The definitions are persisted in the
  // catalogUserTypes store (`catalog_user_types` as of #1001; settings.json
  // `catalogUserTypes` before that — the move did NOT bump this version because
  // the wire shape is storage-independent), merge into the active type registry
  // at boot/runtime, and ride a new additive `catalogTypes: [...]` block in the
  // catalog sync envelope (LWW-merged into the receiver's own user-type store).
  // Same gating rationale as v4–v7: a ≤v7 receiver doesn't understand the
  // `catalogTypes` block, so a v8 sender pushing to it is sender-ahead and gets
  // a 409 (otherwise the older peer would silently drop every user-type
  // definition, then reject every ingredient row carrying one of those unknown
  // types). A v8 receiver still accepts ≤v7 senders (sender-behind); their
  // envelopes carry no `catalogTypes` block and the receiver applies the other
  // kinds as before.
  // v9 = catalog media rows carry bounded Stable Diffusion-compatible
  // generation provenance (prompt, negative prompt, sampler, seed, model,
  // and related fields). The metadata field is additive and optional on the
  // wire; a v9 sender must not push it to a ≤v8 receiver that would silently
  // drop it. A v9 receiver still accepts ≤v8 media rows without metadata.
  // v10 = protect structured object `payload.attachments[]` from older
  // sanitizers. Live catalog transfers now require equal versions in BOTH
  // directions, including legacy senders with no version. Whole-row LWW from
  // an older peer can erase fields after an unrelated edit. Tombstone-only
  // transfers remain version-independent; no local storage migration is needed.
  // v11 = `catalog_ingredient_refs`/`_relations`/`_media` gained `updated_at`
  // (#8347) and their `upsertXFromPeer` apply guards now require it to be
  // strictly newer than the local row's before applying a peer's tombstone
  // OR revival — a ≤v10 sender's unguarded whole-row apply can revive a
  // newer local tombstone (soft-delete R at t2, then apply B's still-live
  // copy of R before B pulls the tombstone) whenever B re-sends R: a
  // role/caption edit, a reset rewind, or the #8315 upgrade replay that
  // resends every catalog row once. Same execution-semantics rationale as
  // v10: this is a receiver-side conflict-resolution change, not just an
  // additive field, so an equal-version requirement is the only way to know
  // BOTH sides apply the guard. Tombstone-only transfers already skip the
  // live-row equality check; a v11 receiver's guard still degrades safely
  // for a ≤v10 sender's tombstone-less payload (unchanged "no opinion" path).
  // v12 = `catalog_ingredient_media.library` (Casting reference library:
  // variant age/era/wardrobe, tags, render-guide flag). A ≤v11 receiver would
  // drop it and whole-row LWW it back, so live transfers need equal versions.
  // v13 = bible payloads gained optional `forms[]` (alternate ages/looks) and
  // media `library.variant.formId`. A <=v12 peer's sanitizer and library
  // normalizer would strip both and whole-row LWW the loss back.
  catalog: 13,
  // v1 = cross-machine resumable Story Builder sessions (#730). Sessions are
  // local-only by default and excluded from sync; only `sync: true` sessions
  // ride the `storyBuilder` snapshot category. This is a brand-NEW synced
  // record type (not a sibling doc on an existing bundle), so it gets its own
  // per-category gate: a sender ahead on `storyBuilder` would push a session
  // shape an older receiver's `sanitizeSession` would silently strip and then
  // LWW back, so a v1 sender pushing to a ≤v0 (pre-feature) receiver is
  // sender-ahead on `storyBuilder` and gets a 409 — only the storyBuilder
  // category pauses; every other category keeps flowing (per-category gate via
  // scopeVersionDiff). A v1 receiver still accepts a ≤v0 sender (sender-behind):
  // pre-feature peers never send a `storyBuilder` snapshot at all, so there's
  // nothing to gate. The FIRST incompatible session-shape change MUST bump this
  // to 2 then (where a v1 peer would round-trip the new shape through an
  // unaware sanitizer).
  storyBuilder: 1,
  // v1 = FableLoom stories federate through the per-record push pipeline
  // (record kind/category `fableLoom`). A pre-feature receiver has no merge
  // path for the whole-record story graph, so only this category pauses until
  // both peers upgrade; unrelated categories continue syncing.
  // v2 = scene nodes gained portable `visualCanon` bindings plus the latest
  // render's path-free `visualConditioning` provenance. A v1 peer would strip
  // both during whole-record LWW, so newer sends must pause until it upgrades.
  // v3 = typed playback assets retain one visual-conditioning manifest per
  // rendered clip, so entry/hold/exit provenance cannot overwrite each other.
  // A v2 peer would strip that map during whole-record LWW.
  // v4 = the loom pins one canonical protagonist and wardrobe, while each
  // scene records whether that protagonist is on-screen or speaking through a
  // side-device off-screen. A v3 peer would silently strip those fields on a
  // whole-record round trip and could restore wardrobe drift or put a removed
  // protagonist back into a scene. v4 ALSO introduced per-episode beat outlines
  // (`episode.storyOutline`) and the series delivery plan
  // (`seriesPlan.deliveryOptions` / `.interEpisodeVoicemails` /
  // `.nextSeasonTeaser`) — a v3 peer strips both, so the receiver restores them
  // from the local record rather than treating the omission as a delete.
  // v5 = one loom-level render format pins the aspect ratio and concrete
  // dimensions shared by storyboard stills and motion clips; plot points and
  // scenes gained durable playable-challenge kinds/phase mappings; and durable
  // editorial/final-delivery sign-offs let the ordered workflow survive a
  // reload. A v4 peer would strip those choices and silently reopen completed
  // gates, erase challenge-to-scene mapping, or reintroduce mixed geometry.
  // v6 = the loom-level render pin gained image/video backend, model, and
  // effort preferences. A v5 peer would preserve the format but strip these
  // additive preferences during an unrelated whole-record update.
  // v7 = shot duration and dramatic-scene grouping survive whole-record sync.
  // v8 = `seriesPlan.characterEvolutions[]` — the optional five-stage character
  // evolution lens per character (#6440). `sanitizeSeriesPlan` omits the key
  // entirely when no lens is authored, so a ≤v7 peer that re-sanitizes a loom
  // through its evolution-unaware sanitizer drops every authored lens and
  // last-writer-wins the loss back onto the newer peer. Bump makes the older
  // peer reject the ahead-version loom transfer; the receiver additionally
  // restores local lenses from a <v8 sender that omits the key
  // (`preserveLegacyCharacterEvolutions`), the same belt-and-braces the
  // delivery plan got at v4.
  // v9 = `seriesPlan.seriesDesign` — the optional shared finite/renewable
  // author brief. A <=v8 peer would strip it during an unrelated whole-record
  // edit, so newer transfers are gated and legacy omissions restore the local
  // value through `preserveLegacySeriesDesign`.
  // v10 = `renderSettings.imageMode`/`videoMode` may name the fal image and
  // fal/Runway video backends. A <=v9 peer's `sanitizeFableLoomRenderSettings`
  // nulls an unknown mode on receive, and its next edit would LWW that lost pin
  // back onto the newer peer. Backend values in `IMAGE_GEN_MODES` /
  // `VIDEO_GEN_MODES` are pinned in schemaVersions.test.js to move with this.
  // v11 adds Runway image backend pins; older peers would erase the unknown mode.
  fableLoom: 11,
  // v1 = Creative Director projects (PostgreSQL `creative_director_projects`)
  // federated via the per-record peer-sync push pipeline (record kind
  // `creativeDirectorProject`, sync category `creativeDirectorProjects`, #1564).
  // A brand-NEW synced record type like `authors`/`storyBuilder`, so it gets its
  // own per-category gate: a v1 sender pushing to a ≤v0 (pre-feature) receiver is
  // sender-ahead on `creativeDirectorProjects` and gets a 409 — only that
  // category pauses; every other keeps flowing (per-category gate via
  // scopeVersionDiff). A v1 receiver still accepts a ≤v0 sender (sender-behind):
  // pre-feature peers never push a `creativeDirectorProject` at all, so there's
  // nothing to gate. The FIRST incompatible project-shape change MUST bump this
  // to 2 then (where a v1 peer would round-trip the new shape through an unaware
  // sanitizer). The project body is LWW-overwritten whole; scene video renders
  // ride the project's linked media collection (federated separately).
  // v2 = `directive` + `plan` added (CDO Phase 2, #2184) — the production-plan
  // layer (a directive brief + a validated `plan.steps[]` the generalized advance
  // loop executes through the gated tool registry). Additive: a legacy video
  // project leaves both null and behaves exactly as before. Version-gated for the
  // same reason as every prior additive field — the project body is
  // LWW-overwritten WHOLE (`mergeProjectRecord`), so a ≤v1 peer that receives a
  // plan-driven project, re-sanitizes it through its directive/plan-unaware
  // path, and pushes back would silently strip both fields and last-writer-wins
  // the loss onto the newer peer. Bumping makes the older peer reject the
  // ahead-version project transfer instead. Per-category gate → only CD-project
  // sync pauses with old peers; every other category keeps flowing. No record
  // rewrite is needed — existing legacy projects simply lack both keys and the
  // advance loop treats an absent key identically to null (falsy → legacy video
  // flow); migration 175 only seeds the new `cd-plan` prompt stage.
  // v3 = cross-step result references (`{{steps.<stepId>.result.<key>}}` inside
  // `plan.steps[].args`, #2773). Unlike v2 this is NOT about a sanitizer
  // round-trip strip (the refs are free-form `args` strings a v2 sanitizer
  // preserves verbatim) — it's an EXECUTION-semantics break: only the v3 advance
  // loop resolves the syntax. A v2 peer that receives a running reference-plan and
  // then boot-recovers it (`recoverInFlightProjects` resets the step to pending)
  // would dispatch the literal `{{…}}` as e.g. a seriesId, fail/re-plan, and
  // LWW-push the damaged plan back onto the v3 peer — corrupting the newer peer's
  // healthy project. Bumping makes the v2 receiver reject the ahead-version
  // transfer (per-category 409) until it upgrades, so it never mis-executes a
  // syntax it can't resolve. No record rewrite needed — reference-free projects
  // are unchanged; the bump only gates cross-version CD-project sync.
  // v4: Video drafts must stay inert. Older peers ignore workspace and could
  // start them through the legacy planner; reject transfers until they upgrade.
  // Existing records remain unchanged and need no data rewrite.
  // v5: Video artifact revisions and stale-context tracking. A v4 peer can
  // edit a shot while preserving the old artifact revision, or replace the
  // treatment and drop its artifact. Gate that loss until both peers upgrade.
  // v6: Preserve Video treatment history; older writers discard prior snapshots.
  // v7: Planning binds to resolved source revisions; older writers skip that guard.
  // v8: Revision-bound approvals and machine-local execution authority.
  // v9: Bounded owner execution receipts and fail-closed restart reconciliation.
  // v10: Validated assembled cuts, retained cut history, and explicit standalone audio.
  creativeDirectorProjects: 10,
  // v1 = Mood boards (PostgreSQL `mood_boards`) federated via the per-record
  // peer-sync push pipeline (record kind `moodBoard`, sync category `moodBoards`,
  // #1564). Same posture as `creativeDirectorProjects` above: a brand-NEW synced
  // record type with its own per-category gate — a v1 sender pushing to a ≤v0
  // (pre-feature) receiver is sender-ahead on `moodBoards` and gets a 409 (only
  // that category pauses); a v1 receiver still accepts a ≤v0 sender (pre-feature
  // peers never push a `moodBoard`). The board body (name/description/items) is
  // LWW-overwritten whole; referenced image bytes ride the asset manifest.
  // v2 = `type: 'video'` board items (#4188). An EXECUTION-semantics break for
  // v1 receivers, not a sanitizer strip (the whole-record LWW passes unknown
  // item shapes through verbatim): a v1 renderer treats a non-image item as a
  // text note (blank card), and its updateItem gates a 'video' item onto the
  // text editable-keys — so a v1 peer that edits the board can mangle video
  // items and LWW the damage back. Bumping makes the v1 receiver 409-reject
  // the ahead-version push until it upgrades. Video bytes ride the existing
  // asset manifest (`video:<filename>` ref → PATHS.videos, receiver regenerates
  // the poster thumbnail on pull).
  // A board's composite `style` prompt, `posterImageRef` and `collageImageRef` are additive on
  // that same v2 record: whole-record LWW plus every local mutator spreads the
  // board, so an older peer preserves both keys and does not execute against
  // them. The poster file rides the asset manifest as a gallery image. No bump.
  moodBoards: 2,
  // v1 = Writers Room works (PostgreSQL `writers_room_works` + decomposed
  // `writers_room_draft_versions`) federated via the per-record peer-sync push
  // pipeline (record kind `writersRoomWork`, sync category `writersRoomWorks`,
  // #1565). Same posture as `creativeDirectorProjects`/`moodBoards`: a brand-NEW
  // synced record type with its own per-category gate — a v1 sender pushing to a
  // ≤v0 (pre-feature) receiver is sender-ahead on `writersRoomWorks` and gets a
  // 409 (only that category pauses); a v1 receiver still accepts a ≤v0 sender
  // (pre-feature peers never push a `writersRoomWork`). The FIRST incompatible
  // work-shape change MUST bump this to 2 then. The work manifest (metadata +
  // decomposed draft-version metadata in drafts[]) is LWW-overwritten whole; the
  // file-primary `.md` draft prose bodies ride a separate body manifest (SHA256
  // diff + receiver-pull), never round-tripped through the record.
  // Bible JSON siblings also ride an optional bibleManifest (#6943), with
  // independent file updatedAt LWW. Older receivers retry without that key;
  // omission never deletes files. The first incompatible bible shape needs its
  // own version gate before it can cross peers; this additive transport stays v1.
  writersRoomWorks: 1,
  // v1 = Writers Room folders (PostgreSQL `writers_room_folders`) federated via
  // the per-record peer-sync push pipeline (record kind `writersRoomFolder`,
  // #1645 — follow-up to #1565). Same posture as `writersRoomWorks`: a brand-NEW
  // synced record type with its own per-category gate, so a v1 sender pushing to
  // a ≤v0 (pre-feature) receiver is sender-ahead on `writersRoomFolders` and gets
  // a 409 (only that category pauses); a v1 receiver still accepts a ≤v0 sender.
  // Folders are body-less (no file-primary `.md`, no asset manifest) and
  // LWW-overwritten whole. The FIRST incompatible folder-shape change MUST bump
  // this to 2. Federating folders requires the soft-delete tombstone columns
  // (deleted/deleted_at) added in the same change — the LWW merge never
  // propagates a hard delete.
  writersRoomFolders: 1,
  // v1 = Writers Room exercises (PostgreSQL `writers_room_exercises`) federated
  // via the per-record peer-sync push pipeline (record kind `writersRoomExercise`,
  // #1645). Body-less + LWW-overwritten whole, same per-category gate semantics as
  // `writersRoomFolders`. Exercises predate federation and carry no
  // `updatedAt`/`createdAt` — the wire sanitizer derives a stable LWW key from
  // their existing `startedAt`/`finishedAt` (see sanitizeExerciseForSync). The
  // FIRST incompatible exercise-shape change MUST bump this to 2.
  writersRoomExercises: 1,
  // v1 = Music Video projects (PostgreSQL `music_video_projects`) federated via
  // the per-record peer-sync push pipeline (record kind `musicVideoProject`, sync
  // category `musicVideoProjects`, #1770 — follow-up to #1760 Phase 1). Same
  // posture as `creativeDirectorProjects`/`writersRoomFolders`: a brand-NEW synced
  // record type with its own per-category gate — a v1 sender pushing to a ≤v0
  // (pre-feature) receiver is sender-ahead on `musicVideoProjects` and gets a 409
  // (only that category pauses); a v1 receiver still accepts a ≤v0 sender
  // (pre-feature peers never push a `musicVideoProject`). The project body
  // (metadata + beat-aligned scenes) is LWW-overwritten whole; referenced media
  // (uploaded audio, scene images/rendered videos) is NOT bundled in this phase —
  // it federates via its own channels / a follow-up. The FIRST incompatible
  // project-shape change MUST bump this to 2.
  // v2 = timed lyric cues, phrase annotations, pacing, and explicit per-shot
  // `loop` semantics (#8964). The body is still stored verbatim by a v1
  // receiver, but a v1 peer would mis-execute it and LWW the damage back: its
  // renderer loops every clip (silently repeating footage in `loop: false`
  // shots the newer peer refuses to render that way), and its audio-source
  // change clears the analysis while leaving the lyric/phrase timings aligned
  // to the OLD track — an edit that then wins LWW onto the upgraded peer.
  // Gating makes a v1 receiver reject the ahead-version transfer until it
  // upgrades; pre-#8964 records need no rewrite (absent `loop` = legacy loop).
  // v3 = immutable scene takes + explicit selection and the project visual spec
  // (#8965). A v2 receiver stores the body verbatim but mis-executes it: its
  // completion hooks overwrite `referenceImageId`/`videoHistoryId` with the
  // newest render — replacing a take the director explicitly selected — and
  // record no take for it, an edit that then wins LWW onto the upgraded peer.
  // Gating makes a v2 receiver reject the ahead-version transfer until it
  // upgrades; pre-#8965 records need no rewrite (a selected slot with no take
  // is materialized as a `legacy` take on first use).
  // v4 = performance shots (#8977): `scene.shotMode` and a video take's
  // immutable `shotInstruction`. A v3 receiver stores both verbatim but
  // mis-executes them: it renders a performance take from frame 0 instead of
  // its edit in-point (and may loop it), desyncing the singer from the song,
  // and submits performance scenes to a cutaway-only lane — edits that then win
  // LWW onto the upgraded peer. Pre-#8977 records need no rewrite (absent
  // `shotMode` = cutaway; takes without an instruction render as before).
  // v5 = authored universe style and cast/place/object snapshots in concept.
  // Older peers ignore these when generating, losing character continuity.
  // v6 = word-level lyric timings (`lyricCues[].words`, #9074). A v5 receiver
  // stores the body verbatim but mis-executes it: an audio-source change clears
  // startSec/endSec and leaves `words` aligned to the OLD vocal, and that edit
  // wins LWW onto the upgraded peer. Gating makes a v5 receiver reject the
  // ahead-version transfer until it upgrades. Records without `words` need no
  // rewrite.
  // v7 = composition mode `code` (#9076). A v6 peer's normalizeComposition
  // collapses an unknown mode to `concat` and would last-writer-wins that
  // loss back, so the gate rejects the ahead transfer. The older peer is
  // never handed `mode: "code"` (an enum value it cannot store). It keeps
  // the concat/composed project it already understands.
  // v8 = lyric-sheet structure (`lyricMarkers`: section headers and stage
  // directions anchored to lyric-line indices) and lyric-derived analysis
  // section names (`audioAnalysis.sections[].labelSource`/`analysisLabel`).
  // A v7 receiver stores the body verbatim but mis-executes it: its lyric
  // import replaces the lines without replacing the markers, leaving them
  // anchored to the wrong lines, and that edit wins LWW onto the upgraded
  // peer. Records without either field need no rewrite.
  // v9 = autopilot check-in gates (`automation.checkins.castAndSets`:
  // `review` | `auto`). A v8 peer's automation normalizer rebuilds the brief
  // from tools/guidance/budget only, so its next brief edit would drop the
  // gate and win LWW back onto the upgraded peer, silently turning an
  // auto-approve setting back into a stop. Gating makes a v8 receiver reject
  // the ahead-version transfer until it upgrades; a record without the gate
  // needs no rewrite (absent = `review`). The Cast & Sets checkpoint
  // (`castAndSets`) and the development artifacts (`devArtifacts`) that ship
  // with it are wire-local like `productionRuns` (lib/syncWire.js): their files
  // live under this install's data/music-video/ and are not in the project's
  // asset manifest, so they are never sent. What an approved check-in writes
  // into ordinary fields (visual-spec references, concept subjects) syncs.
  // The fully-autonomous run (`autonomousRun`, services/musicVideo/autonomousService.js)
  // is wire-local like `productionRuns`: it names this install's providers, Suno
  // songs and production run, and a peer must never execute it — no bump.
  // v10 = composition mode `document` (a project-owned HTML composition
  // document) and `composition.overlay` (its HUD settings). A v9 peer's
  // normalizeComposition collapses the unknown mode to `concat` and drops the
  // overlay, and its next composition edit would last-writer-wins both losses
  // back, so the gate rejects the ahead transfer. The document pointer itself
  // (`composition.document`) is wire-local like `devArtifacts`: its files live
  // under this install's data/music-video/<projectId>/composition/ and are not
  // in the asset manifest, so a peer keeps its own pointer (or none, and then
  // refuses to render with COMPOSITION_DOCUMENT_MISSING).
  // v11 = phrase-alignment confidence (`lyricCues[].matched`). Older peers
  // drop it on edits or retain stale confidence after audio changes. Existing
  // records need no rewrite: absent means alignment has not measured it.
  // v12 = code-first production policy and pinned per-shot medium plans.
  // Older treatment writers drop these fields and can reinterpret them as
  // footage. Absent policy remains legacy; no existing record needs rewriting.
  // v13 = authored/applied shot action contracts; older treatment writers drop intent.
  // Additive optional metadata on existing project records; no backfill is needed.
  // v14 = selected conditioning source/speaker and separate temporal lip-sync
  // evidence (#9347). Older peers can drop source intent and pass equal-length
  // misaligned output, so reject ahead transfers. Absent fields stay legacy.
  // v15 = versioned take and review dependency evidence. Older peers would
  // reuse stale passes or render clips derived from a replaced plate. Legacy
  // evidence remains unknown; no historical verdict is retroactively blessed.
  // v16 = accepted-prefix continuation edit points and one-generation repair
  // reservations. Older peers could regenerate accepted footage or duplicate
  // a submitted suffix after restart. Absent repair metadata stays legacy.
  // v17 = piecewise audio timing receipts and historical source/timing snapshots.
  // Optional on legacy records; no backfill. Older peers cannot apply receipts safely.
  // v18 = named narrative event anchors and bounded section reactivity. Older
  // composition normalizers drop these fields on edit. Absent remains legacy;
  // no stored row rewrite is needed. Document manifests remain wire-local.
  // v19 pins whole-workflow media policy; older peers cannot enforce it.
  // v20 adds the Eidoverse render mode and scene source. Older normalizers
  // would collapse the mode to footage and discard the authored scene.
  // v21 adds compressed lyric timing warnings (`lyricCues[].suspect`). Older
  // normalizers drop the warning on edits. Absent remains legacy; no backfill.
  // v22 = stored shape added since v21 that a v21 build rebuilds as an explicit
  // object (or copies by an explicit field list) and so drops on its next save;
  // the whole-record LWW merge then returns that loss to the upgraded peer as
  // the newer record. Covered: the title card's end-credits showing
  // (`titleCard.outro`/`outroStartSec`/`outroEndSec`); `statsOutro`'s custom
  // `title`/`subtitle`/`hidden` lines; catalog links on creative-setup subjects
  // (`concept.subjects[].ingredientId`/`localOnly`, which a v21 strict subject
  // schema also rejects with a 400); the `video:runway` automation tool id
  // (`normalizeMusicVideoAutomation` filters unknown ids); and the per-shot
  // fields a v21 re-plan (`replaceScenes`) or split (`splitScene`) discards:
  // `endImageId`/`endFramePrompt` (style-break end frame, take kind `endImage`,
  // which a v21 take selection files under a bogus slot), `frameFit`, `speedFps`,
  // `offsetFrames`, `reverse`, `holdLastFrame`, `filmLook`, `transitionIn`/
  // `transitionOut`, `glitches`, `cutEffect`, `imageEffect`/`imageEffectSec`,
  // `stillMove` and `performanceStyle`. Optional fields on the same layout; no
  // migration or backfill.
  // v23 = a shot's storyboard panel link (`scene.panelId`/`panelRev`, Fit to
  // song), which a v22 re-plan or split rebuilds without. Optional, no backfill.
  // v24 = the panel's art as the shot's frame reference (`scene.panelArt`),
  // which a v23 re-plan or split rebuilds without. Optional, no backfill.
  // A field added to these normalizers later needs v25.
  musicVideoProjects: 24,
  // v1 = Creative Commission FEEDBACK federation (PostgreSQL `commission_feedback`)
  // via the per-record peer-sync push pipeline (record kind `commissionFeedback`,
  // sync category `commissionFeedback`, #2686 — split-record follow-up to #2657).
  // The taste reactions federate (so a 👍/👎 carries across a user's machines and
  // conditions the same commission's next run) while the parent commission stays
  // machine-local (a synced schedule would double-run). Body-less whole-record
  // LWW with soft-delete tombstones — the merge never propagates a hard delete.
  // The FIRST incompatible reaction-shape change MUST bump this to 2.
  commissionFeedback: 1,
  // v1 = Creative Commission BRIEF federation (PostgreSQL `creative_commissions`)
  // via the per-record peer-sync push pipeline (record kind `creativeCommission`,
  // sync category `creativeCommissions`, #2686). The brief/identity federates so a
  // synced reaction attaches to the SAME commission on every peer, while
  // `schedule`/`runs`/`assignment` stay MACHINE-LOCAL (stripped from the wire —
  // see syncWire's `creativeCommission` case) so only the owning machine fires the
  // cron (no double-run). Soft-delete tombstones; the FIRST incompatible
  // brief-shape change MUST bump this to 2.
  // v2 = per-output-type commissions (#2769): `targetAbility` widened past `video`
  // and `generation` became per-type (image `imageCount`, music `lengthSeconds`,
  // series `episodeCount`). A pre-#2769 (v1) peer's sanitizer only understands the
  // video generation shape, so it would silently drop those type-specific keys on
  // receive — and could push the video-shaped downgrade back via LWW. The bump
  // gates mixed-version transfers of this category so a v1 peer never mangles a v2
  // brief (compareSchemaVersions marks a v2 sender "ahead" of a v1 receiver).
  // v3 = per-commission render-backend pin (#3135): `generation` gained
  // `imageMode`/`videoMode` (+ optional `imageModelId`/`videoModelId`), naming the
  // backend (local diffusion / Codex / Grok) a scheduled fire must render on.
  // Exactly the #2769 failure mode: `generation` is a FEDERATED field, and a v2
  // peer's `ABILITY_GENERATION_KEYS` doesn't list these keys — its
  // `sanitizeGenerationFor` keeps only the keys it knows, so it would silently
  // strip the user's pinned backend on receive and then push the un-pinned
  // downgrade back via LWW.
  // v4 = opt-in Digital Twin musicTaste configuration in the federated brief
  // (#4347). The bounded config is understood by this sanitizer; a v3 peer
  // would reconstruct the brief without it and could push that downgrade back
  // through the brief-scoped LWW merge. Per-run recipes remain local because
  // syncWire already strips `runs[]`.
  // v5 = `generation.imageMode`/`videoMode` may pin the fal image and fal/Runway
  // video backends. A <=v4 peer's `coerceGenerationValue` turns an unknown enum
  // value into `auto`, and its next edit would LWW that un-pinned downgrade back
  // onto the newer peer. Any new `IMAGE_GEN_MODES`/`VIDEO_GEN_MODES` value needs
  // another bump (guarded in schemaVersions.test.js).
  // v6 adds Runway image backend pins; older peers would coerce them to auto.
  creativeCommissions: 6,
  // v1 = standalone media-library federation (#1566). NOT a record kind — it's
  // the wire contract for the library-level asset manifest a full-sync peer
  // advertises at GET /api/peer-sync/library-manifest. The receiver-pull sweep
  // (syncMediaLibraryFromPeer) reads the sender's advertised `schemaVersion` and
  // GENTLY SKIPS (logs, no reject) a sender ahead of its local `mediaLibrary` —
  // unlike the push gate's hard 409, because a library sweep is best-effort
  // background convergence, not an authoritative record transfer. The asset
  // BYTES themselves are version-agnostic (an image is an image); only the
  // MANIFEST envelope shape is gated, so the FIRST incompatible manifest-shape
  // change (new required field, kind semantics) MUST bump this to 2. Adding a
  // new media KIND to the manifest is additive — the receiver ignores kinds it
  // can't route (directoryForAssetKind returns null) — and does NOT require a
  // bump on its own.
  mediaLibrary: 1,
  // v1 = completed-agent CoS history federation (#1650, part of epic #1561). NOT
  // a record kind — it's the wire contract for the archive manifest a full-sync
  // peer advertises at GET /api/peer-sync/cos-history-manifest. The receiver-pull
  // sweep (syncCosHistoryFromPeer) reads the sender's advertised `schemaVersion`
  // and GENTLY SKIPS (logs, no reject) a sender ahead of its local `cosHistory` —
  // same posture as `mediaLibrary` above, because a history sweep is best-effort
  // background convergence, not an authoritative record transfer. The archive
  // BYTES (metadata.json / output.txt / prompt.txt) are version-agnostic; only
  // the MANIFEST envelope shape is gated, so the FIRST incompatible
  // manifest-shape change (new required entry field, segment semantics) MUST bump
  // this to 2.
  cosHistory: 1,
  // v1 = live CoS task-list + claim-metadata federation (#1712, second half of
  // #1650, part of epic #1561). NOT a record kind — it's the wire contract for
  // the task payload a full-sync peer advertises at GET /api/peer-sync/cos-tasks.
  // Unlike the immutable, append-only `cosHistory` archives (pure byte
  // replication), the task queues (`cos_tasks`, both sources) are mutated
  // live by BOTH peers and carry `claimedBy`/`claimedAt`/`leaseExpiresAt` (#1563),
  // so they ride a claim-aware per-task LWW merge (syncCosTasksFromPeer →
  // cosTaskStore.mergePeerTasks), not the asset path. The receiver reads the
  // sender's advertised `schemaVersion` and GENTLY SKIPS (logs, no reject) a
  // sender ahead of its local `cosTasks` — same posture as `mediaLibrary` /
  // `cosHistory`, because a task sweep is best-effort background convergence, not
  // an authoritative record transfer. Only the payload envelope + task-entry
  // shape is gated; the FIRST incompatible change (new required entry field, new
  // claim semantics) MUST bump this to 2.
  // v2 = the `challenged` task status + its challenge case/resolution metadata
  // (#2441). A ≤v1 receiver's `TASK_STATUSES` enum lacks `challenged`, so its
  // wire validation would REJECT the whole payload (peerCosTasksSchema.safeParse
  // fails → the sweep skips, never mis-merges). Bumping makes the receiver's
  // GENTLE schema-ahead skip fire FIRST with a clear "schema v2 > local v1"
  // log, instead of a confusing blanket "failed validation" skip. The challenge
  // record itself (`challenge`/`challengeResolution`/`challengeCount`) rides the
  // permissive `metadata` map and round-trips the markdown store like any other
  // metadata, so no new top-level wire field is added — only the status vocab
  // widened. Per-category gate → only cos-tasks sync pauses with old peers.
  // v3 = the PR-follow-up disposition markers `reviewLoopMergeOnly` /
  // `reviewLoopLeaveOpen`. This is an EXECUTION-semantics break, not a shape
  // change: both ride the permissive `metadata` map, so a ≤v2 receiver validates
  // and stores the task fine — and then MIS-RUNS it. Its prompt builder doesn't
  // know either marker, so it re-defaults the deliberately-empty reviewer list
  // back to `[copilot]` and runs a review the task explicitly disabled; on a
  // GitLab MR (the copilot-only fallback) it emits GitHub-only commands that
  // cannot land the MR, orphaning it; and on a JIRA hand-off it merges a PR that
  // must stay open. A claimed-and-mis-run task then LWW-pushes its damaged state
  // back onto the v3 peer, which is exactly the bump trigger (see the
  // `creativeDirectorProjects` 2→3 precedent). Per-category gate → only cos-tasks
  // sync pauses until the peer upgrades.
  // v4 = the `workTracker` dispatch marker (repo-study / tracker-filing tasks) and
  // the `reviewerEfforts` per-reviewer effort pins. Same EXECUTION-semantics break
  // as v3, for the same reason: both ride the permissive `metadata` map, so a ≤v3
  // receiver validates and stores the task fine — and then MIS-RUNS it.
  // `taskTypeHooks.isTrackerFilingDispatch` reads `metadata.workTracker` to decide
  // that a run which filed issues and left the tree clean SATISFIED its criterion;
  // a ≤v3 peer only knows the `TRACKER_FILING_TASK_TYPES` set, so it grades that
  // same run a validation miss, finalizes it failed, poisons the provider/model
  // learning bucket, and LWW-pushes the damaged state back onto the v4 peer.
  // `reviewerEfforts` is the milder instance: a ≤v3 peer runs the review at the
  // reviewer CLI's default effort instead of the pinned tier, silently downgrading
  // a review the user deliberately strengthened. Per-category gate → only cos-tasks
  // sync pauses until the peer upgrades.
  // v5 = the `metadata.prompt` / `metadata.context` split (#4153): the full
  // agent-facing payload now rides `prompt` and `context` reverts to the
  // one-line human note. Same EXECUTION-semantics break as v3/v4 — `prompt`
  // rides the permissive `metadata` map, so a ≤v4 receiver validates and stores
  // the task fine and then MIS-RUNS it: its prompt builder only knows
  // `metadata.context`, so the agent is handed a one-line description with the
  // entire Phase 1–7 body (or `/do:*` claim prompt) missing, does the wrong
  // work, and LWW-pushes that damaged state back onto the v5 peer. Readers on
  // v5 fall back to `metadata.context`, so the reverse direction degrades
  // gracefully — the gate exists for the forward one. Per-category gate → only
  // cos-tasks sync pauses until the peer upgrades.
  // v6 = `metadata.targetInstanceId`, the per-task pin to ONE federated instance
  // (#4520). Same EXECUTION-semantics break as v3/v4/v5 — the pin rides the
  // permissive `metadata` map, so a ≤v5 receiver validates and stores the task
  // fine and then RUNS IT ANYWAY: its spawn guards only know the opportunistic
  // claim/lease, so the laptop happily claims the task the user pinned to the
  // GPU box, executes it with the wrong hardware/tooling, and LWW-pushes that
  // run's state back onto the v6 peer — which by then had correctly passed over
  // the task. Per-category gate → only cos-tasks sync pauses until the peer
  // upgrades.
  // v7 = plan-only issue-filing tasks (metadata.planOnly, the forced
  // plan-task --yes invocation, and the task-description context
  // bridge). A <=v6 peer accepts the permissive metadata map but does not
  // understand the no-delivery execution contract, so it can claim the task
  // and run the workflow without the description context needed to file the
  // issue. Per-category gate -> only cos-tasks sync pauses until the peer
  // upgrades.
  // v8 = provider:<id> reviewers. Older peers drop these identities and could
  // execute a task without its required review. Gate only task synchronization.
  // v9 = strict large-input PR review fallback pins and complete linked issue
  // evidence. Older peers may clip that evidence or substitute a smaller model.
  cosTasks: 9,
  // v1 = the Eidoverse foundation promote-candidate envelope (#7455, epic
  // #7453) — authorized to cross the federation layer by the federated
  // Eidoverse foundations ADR (docs/decisions/2026-09-18-federated-eidoverse-foundations.md).
  // A sender advertises its promoted
  // `baseline` foundations at GET /api/peer-sync/eidoverse-foundations; a
  // receiver pulls, re-runs the full accept-side gate per envelope
  // (`verifyFoundationCandidate`), and stores each acceptance under a
  // `peer:<originInstanceId>:<foundationId>` ledger key.
  //
  // Receiver-pull like `mediaLibrary`/`cosHistory`/`cosTasks`, so it rides
  // NON_RECORD_SCHEMA_CATEGORIES below and has no RECORD_KIND_SCHEMA_CATEGORIES
  // entry: there is no push to gate. The receiver GENTLY SKIPS a sender ahead of
  // its local version rather than 409-ing, because the envelope carries a body
  // whose vocabulary is still being written (#7456) — a v1 receiver that applied
  // a v2 envelope would store a foundation it cannot interpret, and the ledger
  // has no re-fetch path that would later correct it.
  //
  // The envelope ALSO carries its own `candidateVersion` literal
  // (EIDOVERSE_FOUNDATION_CANDIDATE_VERSION in lib/eidoverseFoundations.js),
  // which the two prior slices added before any transport existed. The two are
  // deliberately separate: `candidateVersion` pins ONE envelope's shape and is
  // hashed into its content-addressed fingerprint, while this category gates the
  // TRANSPORT payload (its wrapper, its caps, and which foundations an install
  // offers). A change to either must bump its own number; a change to the
  // envelope shape bumps both, because the wrapper's contents changed too.
  //
  // v2 (#7631): the envelope gained the `derived-from` edge, so both numbers
  // moved together exactly as the note above requires. A v2 RECEIVER still
  // accepts a v1 offering unchanged (the edge is absent by construction there),
  // and a v1 receiver gently skips a v2 one rather than storing an envelope
  // whose attribution it would read as plain local authorship.
  //
  // v3 (#7632): the WRAPPER gained `tombstones` — withdrawal, so a promoted
  // foundation can be recalled from the installs that pulled it. `candidateVersion`
  // does NOT move with it: a tombstone names a candidate by the fingerprint it
  // already had, and no envelope field changed. A v2 sender simply omits the
  // key and a v3 receiver reads that as "nothing to retract"; a v2 RECEIVER
  // gently skips a v3 offering and therefore keeps a copy it should have
  // dropped — the degradation is deliberate and documented in
  // `docs/features/eidoverse.md`, because the alternative (a receiver acting on
  // a wrapper it cannot fully read) is worse, and a retraction that reaches
  // nobody is still better than one that corrupts.
  eidoverseFoundations: 3,
  // v1 = identified daily-log events (#8143). The meatspace snapshot's
  // `daily-log.json` alcohol drinks and nicotine items now carry `id` +
  // `createdAt`/`updatedAt`; a v1 receiver merges them by id (newest copy wins)
  // so identical independently-logged events stay distinct and a replay stays
  // idempotent. NOT a record kind — it gates the 60s meatspace snapshot in
  // dataSync `applyRemote` (SNAPSHOT_CATEGORY_SCHEMA_KEYS), so it rides
  // NON_RECORD_SCHEMA_CATEGORIES below.
  //
  // Mixed versions are deliberately NOT blocked, because neither direction can
  // corrupt the other and pausing would strand drinks logged meanwhile:
  //  - v0 → v1: a v0 payload is `behind` (never gated). Its rows without an `id`
  //    keep the old content-keyed dedupe; copies of an id'd row that the v0 peer
  //    bumped in place (it folds a same-product log into the existing row without
  //    restamping) resolve to the larger `count` on equal stamps.
  //  - v1 → v0: a v0 receiver scopes meatspace to no schema keys, so it cannot
  //    gate; it unions the id'd rows by content and keeps them verbatim.
  //    Its content union still keeps an edited row beside the unedited copy (it
  //    cannot read `replaces`) — the same double row an edit between two v0
  //    peers has always produced, cleared once that peer upgrades.
  //
  // Still v1 after #8154, which added deletes and date moves for id'd events:
  // a top-level `eventTombstones: [{ id, deletedAt }]` list (unioned both ways)
  // and a whole-log pass that keeps one copy per id, on whichever date the
  // newest copy lives. That is additive, and a bump would make every older
  // receiver refuse ALL daily-log data, new drinks included. With a pre-#8154
  // peer in the federation:
  //  - It keeps a deleted or moved-away copy (it cannot read tombstones and
  //    merges ids per date) and sends it back each cycle. A current receiver
  //    drops that copy again — it is not newer than the tombstone, and the
  //    moved copy's newer stamp wins the id — so only the old peer
  //    double-counts, until it upgrades.
  //  - It cannot strip tombstones from a current peer: the list is unioned, and
  //    the old peer's own writes keep unknown top-level fields. Its own copy of
  //    the list only refreshes when its local file lacks the key, so it may
  //    send a stale subset back, which a union ignores.
  // Rows without an `id` (logged before #8143) are still add-only: deleting
  // or moving one does not reach peers.
  //
  // v2 (#12432): blood/epigenetic/eye rows merge by identity. A row without
  // `createdAt` (an id-less legacy row, or one a pre-v2 reader stamped with a
  // random id) also answers to a content-derived `legacy-` key every machine
  // computes alike, copies of one row resolve by per-row `updatedAt`, and a
  // delete rides a top-level `rowTombstones: [{ id, deletedAt }]` list in the
  // row's file. A v1 receiver must refuse that: its union keys a stamped row by
  // its id alone, so a `legacy-` id would append a second copy of a row it
  // holds under its own stamp, and it cannot read tombstones or edits. v1 → v2
  // stays accepted: a v2 receiver matches the v1 sender's random-stamped legacy
  // rows by their content key, so they converge instead of duplicating.
  // An edit made on a v1 peer still arrives as a second row, as it always did.
  // Until a v1 peer upgrades it refuses the whole meatspace snapshot from a v2
  // peer, daily log included; the gap shows on the Instances page.
  meatspace: 2,
  // v1 = the paired-peer credential (#8356): `X-PortOS-Peer-Auth`, an HMAC of the
  // pair `syncSecret` bound to the sender's instance id, replacing the instance
  // password over HTTP Basic between paired peers. Not a record or snapshot
  // category — it versions the authentication handshake. A receiver advertises it
  // as `peerAuth.version` in GET /api/system/health/details together with
  // `peerAuth.accepted` (whether THIS request's token verified). A sender drops
  // the Basic header only after that confirmation (`peer.peerAuthAccepted`), so
  // an older receiver, which never answers, keeps getting Basic.
  peerAuth: 1,
  // NOTE: `videoHistory` is intentionally NOT listed here. The version gate
  // rejects the ENTIRE snapshot/push payload on ANY ahead-mismatch (the
  // comparator walks the union of keys), so declaring a brand-new key would
  // make every not-yet-upgraded peer reject ALL categories (universe,
  // pipeline, …) — severing sync across a federation that upgrades on
  // independent schedules. videoHistory is a flat append-only array merged by
  // id with LWW-on-createdAt; the merge already tolerates unknown/extra rows,
  // so it does not need whole-payload gating. An older peer that lacks the
  // `videoHistory` route simply rejects that one category request and keeps
  // syncing everything else.
  //
  // The gate is now PER-CATEGORY (see `scopeVersionDiff` below + its three
  // call sites: dataSync `applyRemote`, peerSync push, sharing importer), so
  // adding a new key here or bumping one category only gates transfers of
  // THAT category — unrelated categories keep flowing. videoHistory stays
  // unlisted because it has no versioned storage layout at all, not because
  // of the old whole-payload footgun.
});

/**
 * Map a federated record KIND (the unit a peer push or share manifest moves)
 * to the `PORTOS_SCHEMA_VERSIONS` categories its storage layout touches. The
 * per-category gate uses this to block a transfer ONLY when the sender is
 * ahead on a category that record actually writes.
 *
 * Kinds absent from this map carry no versioned storage layout and are never
 * gated — media-job records (flat re-render metadata), media-annotations,
 * goals/character/digitalTwin/meatspace, videoHistory, etc. A `series` push
 * that bundles issues, or a universe/series push that bundles a linked media
 * collection, unions the additional kinds' categories at the call site.
 */
export const RECORD_KIND_SCHEMA_CATEGORIES = Object.freeze({
  universe: Object.freeze(['universes']),
  series: Object.freeze(['pipelineSeries']),
  issue: Object.freeze(['pipelineIssues']),
  mediaCollection: Object.freeze(['mediaCollections']),
  author: Object.freeze(['authors']),
  artist: Object.freeze(['artists']),
  album: Object.freeze(['albums']),
  track: Object.freeze(['tracks']),
  'cat-ingredient': Object.freeze(['catalog']),
  'cat-scrap': Object.freeze(['catalog']),
  storyBuilder: Object.freeze(['storyBuilder']),
  fableLoom: Object.freeze(['fableLoom']),
  creativeDirectorProject: Object.freeze(['creativeDirectorProjects']),
  moodBoard: Object.freeze(['moodBoards']),
  writersRoomWork: Object.freeze(['writersRoomWorks']),
  writersRoomFolder: Object.freeze(['writersRoomFolders']),
  writersRoomExercise: Object.freeze(['writersRoomExercises']),
  musicVideoProject: Object.freeze(['musicVideoProjects']),
  commissionFeedback: Object.freeze(['commissionFeedback']),
  creativeCommission: Object.freeze(['creativeCommissions']),
  deck: Object.freeze(['decks']),
  storyboard: Object.freeze(['storyboards']),
});

/**
 * Schema-version categories that are versioned but NOT reachable from a record
 * push — they ride their OWN transport with their OWN compatibility gate, not the
 * per-record push gate that `RECORD_KIND_SCHEMA_CATEGORIES` drives. Listing one
 * here is the explicit, reviewed way to say "this version is gated elsewhere, so
 * the gate-map-completeness guard should not require a record-kind mapping."
 *
 * - `mediaLibrary` (#1566): the standalone media-library manifest a full-sync
 *   peer advertises at GET /api/peer-sync/library-manifest. The RECEIVER pulls
 *   it and GENTLY SKIPS a sender ahead of its local version (see
 *   syncMediaLibraryFromPeer) — there is no push to gate, so it has no entry in
 *   RECORD_KIND_SCHEMA_CATEGORIES by design.
 * - `cosHistory` (#1650): the completed-agent CoS history archive manifest a
 *   full-sync peer advertises at GET /api/peer-sync/cos-history-manifest. Same
 *   receiver-pull shape as `mediaLibrary` (see syncCosHistoryFromPeer) — no push
 *   to gate, so no RECORD_KIND_SCHEMA_CATEGORIES entry.
 * - `cosTasks` (#1712): the live CoS task-list + claim-metadata payload a
 *   full-sync peer advertises at GET /api/peer-sync/cos-tasks. Receiver-pull +
 *   claim-aware per-task merge (see syncCosTasksFromPeer) — no push to gate, so
 *   no RECORD_KIND_SCHEMA_CATEGORIES entry.
 *
 * - `eidoverseFoundations` (#7455): the promoted Eidoverse foundation candidates
 *   an install advertises at GET /api/peer-sync/eidoverse-foundations. Same
 *   receiver-pull shape as `cosTasks` (see syncEidoverseFoundationsFromPeer) —
 *   no push to gate, so no RECORD_KIND_SCHEMA_CATEGORIES entry. A foundation is
 *   not a peer-subscribable record kind and never rides the record pipeline.
 *
 * `appQuality`: numeric-only local evidence at GET /api/apps/quality-federation,
 * validated against its exact wire version by collectAppQuality; never written or pushed.
 * The repository file format is versioned separately (`appQualitySnapshotFormat.js`)
 * and a file-schema change must not bump this wire version.
 *
 * `meatspace` (#8143): the daily-log snapshot category, gated by dataSync
 * `applyRemote` through SNAPSHOT_CATEGORY_SCHEMA_KEYS; meatspace is never a
 * per-record push.
 *
 * `peerAuth` (#8356): the peer credential handshake version, advertised by the
 * receiver's health details; it gates which header a sender presents, never a
 * record transfer.
 *
 * Do NOT add a real record-push category here to silence the guard — that would
 * leave its push transfers ungated (silent cross-install corruption). Only
 * genuinely non-push categories belong.
 */
export const NON_RECORD_SCHEMA_CATEGORIES = Object.freeze(new Set(['memoryHistory', 'mediaLibrary', 'cosHistory', 'cosTasks', 'appQuality', 'eidoverseFoundations', 'meatspace', 'peerAuth']));

/**
 * Lazy-read the current PortOS version from the ROOT package.json so a
 * pull-and-restart picks it up without a process-relative cache.
 *
 * Tested-without-files fallback: when PATHS.root is mutated for a test to
 * a directory without package.json, return '0.0.0' instead of throwing.
 * Mirrors `getCurrentVersion` in `server/services/updateChecker.js`.
 */
export async function getPortosVersion() {
  const pkgPath = join(PATHS.root, 'package.json');
  const raw = await tryReadFile(pkgPath);
  if (!raw) return '0.0.0';
  const parsed = safeJSONParse(raw, null);
  return typeof parsed?.version === 'string' && parsed.version ? parsed.version : '0.0.0';
}

/**
 * Build the `portosMeta` envelope that every outbound sync payload carries
 * at the top level. Receivers feed `meta.schemaVersions` into
 * `compareSchemaVersions(sender, PORTOS_SCHEMA_VERSIONS)` to decide whether
 * to apply the payload.
 *
 *   {
 *     "portosMeta": {
 *       "portosVersion": "2.7.0",
 *       "schemaVersions": { "universes": 5 }
 *     }
 *   }
 *
 * `portosVersion` is informational — for UI surfacing only. The gate logic
 * runs on `schemaVersions` because the on-disk shape is what matters; the
 * PortOS version is just a friendly label users recognize.
 */
export async function buildPortosMeta(overrides = {}) {
  const portosVersion = await getPortosVersion();
  return {
    portosVersion,
    schemaVersions: { ...PORTOS_SCHEMA_VERSIONS, ...(overrides.schemaVersions || {}) },
  };
}

/**
 * Compare a peer's schemaVersions against the local code's expectations.
 *
 * Returns a structured diff so callers (push-rejection, UI surfacing) can
 * tell users WHICH category is mismatched and in which direction.
 *
 *   ahead[]  — categories where the SENDER has a newer schema than the
 *              RECEIVER. The receiver can't safely apply the payload; reject.
 *   behind[] — categories where the SENDER is older than the receiver. The
 *              sanitizer can usually backfill, but some forward-only
 *              contracts may still require the sender to upgrade. Callers
 *              decide whether to gate.
 *
 *   compatible — `true` only when neither list has entries.
 *
 * Absent or invalid entries are compared as zero. A legacy sender without
 * `portosMeta` is behind every versioned receiver category; callers decide
 * whether those behind gaps block the transfer.
 */
export function compareSchemaVersions(senderVersions = {}, receiverVersions = PORTOS_SCHEMA_VERSIONS) {
  const sender = senderVersions && typeof senderVersions === 'object' ? senderVersions : {};
  const receiver = receiverVersions && typeof receiverVersions === 'object' ? receiverVersions : {};
  const ahead = [];
  const behind = [];
  // Walk the UNION of keys so we catch (a) sender has a category receiver
  // doesn't know (sender ahead), AND (b) receiver requires a category the
  // sender doesn't carry (sender behind on that category).
  const keys = new Set([
    ...Object.keys(sender),
    ...Object.keys(receiver),
  ]);
  for (const cat of keys) {
    const senderV = Number.isInteger(sender[cat]) ? sender[cat] : 0;
    const receiverV = Number.isInteger(receiver[cat]) ? receiver[cat] : 0;
    if (senderV === 0 && receiverV === 0) continue;          // no contract on either side
    if (senderV === receiverV) continue;                      // exact match
    if (senderV > receiverV) ahead.push({ category: cat, senderV, receiverV });
    else behind.push({ category: cat, senderV, receiverV });
  }
  return { ahead, behind, compatible: ahead.length === 0 && behind.length === 0 };
}

/** Catalog row blocks share `deleted`, except user types use `deletedAt`.
 * Unknown blocks and malformed rows conservatively count as live so a future
 * payload cannot bypass the version gate. Envelope metadata is not a row block.
 */
export function catalogEnvelopeHasLiveRows(envelope) {
  return Object.entries(envelope).some(([kind, block]) => Array.isArray(block) && block.some(
    (row) => kind === 'catalogTypes' ? !row?.deletedAt : row?.deleted !== true,
  ));
}

/**
 * Restrict a comparator result to the categories actually being transferred.
 *
 * `compareSchemaVersions` walks the UNION of every known category so the full
 * diff stays useful for diagnostics/UI. But the GATE decision must be
 * per-category: a sender that bumped (or added) one category should only be
 * blocked for transfers of THAT category — not for unrelated categories that
 * happen to ride a federation upgrading on independent schedules. Pass the
 * schema-version keys this transfer actually moves; categories outside the
 * set are dropped from `ahead`/`behind` so they can't block (and the scoped
 * `ahead` is what callers report, so a "pipeline" snapshot rejection never
 * mis-attributes a `universes` gap).
 *
 * `categories` non-array (null/undefined) → returns the diff unchanged
 * (whole-payload gate; the comparator's union result is used as-is). An empty
 * array → nothing can block (the transfer touches no versioned category).
 */
export function scopeVersionDiff(diff = {}, categories) {
  if (!Array.isArray(categories)) return diff;
  const allow = new Set(categories);
  const ahead = (Array.isArray(diff.ahead) ? diff.ahead : []).filter((g) => allow.has(g.category));
  const behind = (Array.isArray(diff.behind) ? diff.behind : []).filter((g) => allow.has(g.category));
  return { ahead, behind, compatible: ahead.length === 0 && behind.length === 0 };
}

/**
 * Human-readable explanation of a comparator result. Used both for log lines
 * and for the UI badge tooltip. Keeps the wording in one place so a peer-
 * sync 409 message, the Instances UI, and the share-bucket panel all
 * describe the gap identically.
 *
 *   formatVersionGap({ ahead: [{ category: 'universes', senderV: 5, receiverV: 4 }] })
 *     → 'sender ahead of receiver on universes (v5 vs v4)'
 */
export function formatVersionGap({ ahead = [], behind = [] } = {}) {
  const parts = [];
  if (ahead.length) {
    parts.push(`sender ahead of receiver on ${ahead.map((g) => `${g.category} (v${g.senderV} vs v${g.receiverV})`).join(', ')}`);
  }
  if (behind.length) {
    parts.push(`sender behind receiver on ${behind.map((g) => `${g.category} (v${g.senderV} vs v${g.receiverV})`).join(', ')}`);
  }
  return parts.join('; ') || 'compatible';
}