Skip to content

Commit d3eefef

Browse files
authored
docs(storage): define compatibility rules for structural format changes (#1824)
## What it does Adds a "Stored-format changes" section to docs/development.md and links it from the "What a change needs" list in CONTRIBUTING.md. It sets the rules for the next PR that changes the structure of a store Ovis owns: an `ovis:` record in `localStorage`, or a bridge document in the state directory such as `preferences.json` or `devices.json`. That PR has to name the store's owner, the old and new shape, which releases read and write each shape, and the contract that carries it. It also has to keep five rules: - tabs that are already open keep running their old code; - migration stays passive, with no corrective PUT; - data too new to read is never written over; - `devices.json` fails closed; - the supervisor's rollback restores code, not data. The section also lists the tests such a change has to bring. It points out that the `preferences.json` revision is not a schema version, and that the transcript layout check in `server/session-history.ts` is not a bridge-store migration. ## Why Most stores carry no schema version. A careless structural change could wipe settings through an old tab, overwrite another browser's data, or reopen device pairing after a rollback. Writing the rules down before that PR exists means it gets them right the first time. ## Verification - Rebased onto current origin/main. Updated for the rename: the storage keys are now `ovis:*`, where they were `herdr-web-ui:*`. - `bun run check fast` passes. - A code-review agent traced every code claim to its source (`themeBoot.ts`, `settings.ts` `saveSettings`, `preferencesSync.ts` `takePreferences`, `devices.ts` `error`/`gated`/`assertWritable`, the rollback in `supervisor.ts`) and checked that every link and anchor resolves. No HIGH findings. Its MEDIUM finding was that the two named keys read as the complete list of browser records, so they are now given as examples. Its LOW finding was that the too-new-devices sentence read as current behaviour, so it now says "must". Documentation only: no product code, wire type or test changes, so there is no changelog fragment.
1 parent b09a849 commit d3eefef

2 files changed

Lines changed: 55 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,8 @@ the context does not make it clear. The dialog that makes a workspace is
106106
- **HTTP or WebSocket contract:** change both sides through `shared/protocol.ts` and cover it with a
107107
contract test (`server/api.contract.test.ts` for endpoints). A test that needs a live herdr is named
108108
`*.contract.test.ts`.
109+
- **Stored formats:** a change to the structure of a stored browser record or state-directory
110+
file follows the [stored-format rules](docs/development.md#stored-format-changes).
109111
- **herdr wire types:** never edit `shared/herdr-api.generated.ts`; run `bun run generate:types`.
110112
- **Theme colors:** edit them only in the theme blocks of `src/styles.css`. Never edit
111113
`src/lib/themes.generated.ts` or the generated copies in DESIGN.md, `index.html` and

‎docs/development.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -604,6 +604,59 @@ dependencies. Keep each PR focused on one change. Squash merge it after required
604604
delete its remote branch after merging only when dependent work is preserved. There is no permanent
605605
`develop` branch. Release metadata changes also go through a PR.
606606

607+
### Stored-format changes
608+
609+
These rules bind the next PR that changes the structure of a store this app owns: a browser record
610+
(an `ovis:` key in `localStorage`, such as `ovis:settings` or `ovis:themes`) or a bridge document in the
611+
state directory (`preferences.json`, `devices.json` and the others beside them). Renaming, moving,
612+
splitting or re-encoding a field, or changing what a stored value means, is structural. So is adding a field to a record an older
613+
writer rewrites whole: an old tab's next unrelated save writes the record back without the field
614+
it does not know, and erases it. Only an addition an older writer cannot erase, such as a value
615+
kept in its own key or document, is not structural and needs none of this.
616+
617+
Most stores carry no schema version today. What follows is what the format-changing PR has to
618+
bring, not a description of what every store already does. The `revision` in `preferences.json`
619+
orders writes; it is not a schema version and says nothing about whether a reader understands
620+
the document. The layout check in [`server/session-history.ts`](../server/session-history.ts)
621+
validates a native agent transcript the bridge only reads; it is not a bridge-store migration and
622+
no precedent for one.
623+
624+
The PR description names the store's owner (the key or file, and the module that writes it), the
625+
old and the new shape, which releases read and which write each shape (and what the oldest reader
626+
still running does with the new one), and the HTTP or WebSocket contract that carries the store,
627+
or that none does. Then the change keeps these rules:
628+
629+
- **Tabs already open keep their old code.** An old tab that saves an unrelated setting after the
630+
new code wrote must not erase the new shape. Already in place for the theme pair: it lives in
631+
its own key, and the main record keeps the legacy mirrors an old sanitizer reads (`saveSettings`
632+
in [`src/lib/settings.ts`](../src/lib/settings.ts), old code pinned in
633+
[`settings.legacy-fixture.ts`](../src/lib/settings.legacy-fixture.ts)).
634+
- **Migrate passively.** A browser that reads an old shared document derives the new shape into
635+
its own state and advances its baseline to it. It never sends a corrective PUT that writes its
636+
interpretation back, and a value it cannot read stays the other browsers'. Already in place for
637+
the theme sides (`takePreferences` in [`src/lib/preferencesSync.ts`](../src/lib/preferencesSync.ts)).
638+
- **Never write over data too new to read.** A reader that finds a structural version it does not
639+
know keeps the bytes as they are and refuses to write that store. It does not treat the unknown
640+
version as absent, and does not sanitize the document to defaults and save them over it.
641+
- **Devices fail closed.** A `devices.json` that is damaged or too new keeps the gate closed and
642+
the registry unwritable. It is never a first installation or an empty registry, and nothing
643+
reopens pairing. [`server/devices.ts`](../server/devices.ts) already does this for a damaged
644+
file (`error`, `gated`, `assertWritable`); a too-new version must take the same path.
645+
- **Rollback restores code, not data.** The update supervisor restores the previous release when
646+
a candidate bridge fails its startup health check
647+
([`server/supervisor.ts`](../server/supervisor.ts), [app updates](app-updates.md#boundaries)).
648+
Both releases share one state directory, so this does not undo a rewrite the candidate already
649+
made, and a later manual downgrade meets the new shape too. Make old readers safe before the new
650+
shape is written: ship the reading side or the too-new refusal in a release before the one that
651+
writes, or keep writing a shape the previous release reads.
652+
653+
The PR's tests, on `mkdtempSync` state directories or a stand-in `localStorage` and event-driven,
654+
cover: an old-shape fixture loading into the new shape; an old tab's unrelated save after the new
655+
code wrote; old and new readers and writers side by side, each keeping the other's values with no
656+
corrective write; a too-new document read without being written (its bytes unchanged after a
657+
write is refused, and for devices the gate still closed); and a failed activation, where the
658+
previous release serves again and reads, or refuses, what the candidate left on disk.
659+
607660
### Coordinated work
608661

609662
For coordinated work, record one small task entry in the existing PR/issue or another single,

0 commit comments

Comments
 (0)