Appearance
Versioning
The business rules will keep changing. This page is the contract for how a change is made without rewriting history. Rationale: ADR 0004.
flowchart TD
Q{What is changing?}
Q -->|a product rule or behaviour| S[Spec: bump SPEC_VERSION, changelog entry]
Q -->|a number or switch the owner tunes| ST[Setting: new revision, effectiveFrom, reason]
Q -->|a price or document wording| T[Template: new version, publish]
Q -->|a sent quote or signed contract| X[Never changes: it is a snapshot]
Q -->|shape of a JSON column or queue message| J[schemaVersion + upgrade step]
Q -->|a table or column| M[New migration, append-only]
Q -->|an API call's input or output| A[Additive: stay in v1. Breaking: add v2]
Q -->|a UI component from beUI| U[ui:update, lockfile records it]
1. Versioned JSON
Use for any JSON column whose shape may change: lead form answers, snapshot payloads, comment anchors, quote line items.
Store { schemaVersion, data }. Define the schema once with defineVersionedSchema (@shootgrow/domain):
ts
const formAnswers = defineVersionedSchema({
name: "lead.formAnswers",
current: 2,
schema: formAnswersV2, // Zod schema of the latest shape
upgrades: { 1: (v1) => ({ ...v1, social: [] }) }, // v1 -> v2, pure
});
formAnswers.wrap(input); // write: validates, stamps current version
formAnswers.read(row.answers); // read: upgrades any old version, validatesRules: versions start at 1 and increase by exactly 1; every version below current needs an upgrade (the definition throws at startup if one is missing); upgrades are pure and never throw on valid old data; a stored version newer than the running code throws, because it means the older build must not touch that row.
To change a shape: bump current, add upgrades[old], keep reading old rows lazily. Rewrite stored rows only if you need to query inside the JSON, and then in a separate migration.
2. Snapshots
Use for anything sent or signed: quotes, contracts, crew contracts.
When the owner sends or the client signs, call freezeSnapshot({ kind, templateVersionId, schemaVersion, data }). It returns the data plus a SHA-256 over the canonical JSON (keys sorted), and stores the template version id for audit. Store the whole object on the document row. From then on:
- The document never reads the live template or live prices.
verifySnapshotcan prove the stored terms still match their hash.- Editing the template only affects documents created afterwards.
Example. A client signs 4 months at £1,000. The owner publishes plan version 2 at £1,200. The signed contract still reads £1,000 from its snapshot; new quotes pick version 2.
3. Effective-dated revisions
Use for settings and anything whose "current" value changes over time (crew pay terms, rates).
Append a row; never update one. "What applied at time T?" is resolveEffective(rows, T): the latest effectiveFrom <= T, ties broken by revision. Ledger lines store the rate they used, so past pay never moves.
Settings specifically:
- The registry (
packages/domain/src/settings.ts) defines each key: Zod schema, default, group, label, the open-decision number it answers, and aprovisionalflag when the spec gave no value. - The
settingtable stores revisions:key,revision,value,effectiveFrom,reason,createdBy. Triggers reject UPDATE/DELETE. - Reading: resolve the revision,
parseSetting, elsegetSettingDefault. - Writing: insert
revision = max + 1, seteffectiveFrom(usually now; a future date schedules a change), record a reason, and write anaudit_logrow in the same batch. - Adding a key: add it to the registry with a default. No migration; code works before any row exists.
- Renaming or changing the meaning of a key: add a new key, read the old one as a fallback for a release, then retire it. Never reuse a key.
- A changed schema for a key's value: widen the Zod schema compatibly, or add a new key.
4. Templates (plans, quotes, contracts)
template_version rows: (kind, key, version) unique, status of draft | published | retired.
| Status | Editable | Used for new documents |
|---|---|---|
draft | yes, and deletable | no |
published | no (trigger) | yes: the highest published version for (kind, key) |
retired | no | no |
Publishing sets status, content_hash and published_at. A published row may only move to retired. To change wording or a price: copy the published row into a new draft (version + 1), edit, publish. Prices are kind = plan templates, not settings.
5. Database schema
Append-only migrations, enforced by bun run db:check and CI. Make each migration backward compatible with the previous build for one release. Details: Database.
6. HTTP API
The oRPC router is namespaced: orpc.v1.<router>.<procedure>. The web app and server deploy together, so versioning exists to keep deploys safe and to leave room for other clients later.
- Additive changes (new procedure, new optional input, new output field) stay in
v1. - Breaking changes add the new shape under
v2.<same name>. Move callers, then delete thev1procedure in the same change as its last caller. v1.meta.inforeturnsapiVersionandspecVersion; the app footer displays them.
7. Background jobs
Queue messages are versioned envelopes with idempotency keys. A consumer accepts the current and previous payload version for one release. See Background jobs.
8. UI components
beUI source is vendored; packages/ui/beui.lock.json records each component's upstream updated_at and a hash of every file as written. bun run ui:status shows local edits and available updates; ui:update refuses to overwrite edited files without --force.
9. The spec itself
SPEC_VERSION (packages/domain/src/spec.ts) names the spec the code was last reconciled with. The app footer shows it. Bump it as described in Changing the spec.
Checklist for a change
- [ ] Is the value something the owner might change? Make it a setting, not a constant.
- [ ] Does it touch a sent or signed document? It must come from a snapshot.
- [ ] Does it change a stored JSON shape? Bump the schema version and add an upgrade.
- [ ] Does it change a table? New migration; compatible with the previous build.
- [ ] Does it break an API caller? Add
v2, do not mutatev1. - [ ] Did the spec change? Update the chapter, bump
SPEC_VERSION, add a changelog entry. - [ ] Is the decision hard to reverse? Write an ADR.