Notarizing documentation

Upgrade notes

Developer preview. Not yet production ready. This page is rendered from docs/upgrade.md of the Notarizing repository at revision d23579e737f9d1e16e07b3c6b21a51282d64027e. It describes the behavior of that revision.

Contents

A workspace has a schema version. A new notarizing binary can add schema migrations. A command that owns the workspace applies the pending migrations when it opens the workspace: init, serve and the commands that write, for example change import. Read-only commands and mcp refuse a workspace that needs a migration. Run init on purpose after a backup, so that the migration happens at a time that you select.

Before you upgrade

Stop notarizing serve. A migration needs the workspace owner lock.

Make a backup with the old binary:

notarizing backup --output /backups/ws-before-upgrade
notarizing backup verify /backups/ws-before-upgrade

Keep the backup until you have checked the upgraded workspace.

A migration is not reversible. An old binary cannot open a workspace that a new binary migrated. To go back, restore the backup with the old binary (see the operator guide).

Upgrade

Install the new binary.

Apply the migrations:

notarizing --workspace /srv/notarizing/ws init

Check the workspace:

notarizing --workspace /srv/notarizing/ws doctor

Start serve again.

If the workspace has a newer schema than the binary, the binary refuses it with unsupported_schema (exit code 1) and changes nothing. Install the newer binary.

Schema versions

Each migration applies once, in order, in one transaction. The workspace records the SHA-256 of each applied migration. A released migration never changes.

Version	Migration	What it adds
1	`0001_evidence`	Reports and artifacts by digest, receipts, report IDs for retries.
2	`0002_sources`	Registered repositories, source snapshots, effective targets, check bindings and the assessment policy.
3	`0003_review`	The append-only review journal and its projections: assumptions, relationships, decisions, notes, wording drafts and saved views.
4	`0004_graph`	Reserved. It applies no change.
5	`0005_search`	The search index, the embedding provider configuration, retention purges and imported evidence bundles.
6	`0006_assessments`	Immutable assessment records and an index for the evidence of one requirement.
7	`0007_corrections`	Collector records of corrected results (`evidence correct`).
8	`0008_bundle_review`	Review events and corrections of imported evidence bundles, as claims of the exporting workspace.
9	`0009_empirical_relations`	Four empirical relation kinds of the review journal: `observes`, `hypothesizes`, `regresses` and `fixes`.
10	`0010_review_supersessions`	The scope of reviewed supersessions: a later receipt supersedes a corrected failure for one requirement and dimension.
11	`0011_source_access`	The source access changes of registered repositories (`repo access revoke` and `repo access restore`).
12	`0012_repository_locations`	The path changes of registered repositories (`repo set-path`).

The current schema version is 12. A test checks that this table names every migration of the binary.

After the upgrade

Search indexes stay valid when the extractor and chunker versions do not change. If notarizing search status shows a stale index, run notarizing search index --target ID.
Check the CLI reference for new commands. This revision adds notarizing graph whatif, notarizing repo access revoke and notarizing repo access restore.
Migration 11 adds an empty table. Every registered repository keeps its source access.

All Notarizing documents