Notarizing documentation
Compatibility
Developer preview. Not yet production ready. This page is rendered from docs/compatibility.md of the Notarizing repository at revision d23579e737f9d1e16e07b3c6b21a51282d64027e. It describes the behavior of that revision.
Contents
This page states what stays stable between versions of notarizing, and what can change. Notarizing is a developer preview. No version has been released. The rules describe how the readers and writers of this revision behave and how later changes must be made. Section 60.1 of n0-decisions.md records the decision.
How versions work
Each public format has a version name in its schema_version or profile member, for
example notarizing.policy/1. The number after the slash is the major version.
| Change | Allowed within /1 | Needs /2 |
|---|---|---|
| Add an optional member to a document that notarizing writes | Yes | No |
| Add an optional member to a document that notarizing reads | Yes | No |
| Remove or rename a member | No | Yes |
| Make an optional member required | No | Yes |
| Change the type, unit, default or meaning of a member or value | No | Yes |
| Any change to a frozen contract | No | Paired review in ka2a and notarizing |
Input documents are strict
Notarizing refuses an unknown member in every document and request that it reads. It
never ignores one. It refuses another version with unsupported_schema or invalid_input.
This has two results:
- A document that was valid for an earlier release stays valid for a later release of the same major version.
- An earlier release refuses a document that uses a member that a later release added. It does not drop the member in silence. Keep your files to the members of the oldest release that must read them.
Output documents can grow
Within one major version, a later release can add optional members to its output. Earlier
releases did this, for example commit and platform in the result of version.
- If you write a program that reads notarizing output, ignore unknown members.
- Do not expect a member that is absent when it does not apply.
- The readers inside notarizing are strict. An earlier release can refuse a bundle or a
graph/1file that a later release wrote with a new member. Read such files with the same release or a later one.
Contract by contract
The JSON Schemas in schemas/ describe the input files with
additionalProperties: false, as the parsers read them. They are for editors and other
tools. The parsers stay the authority and check more, for example unique keys and files
(section 61.5 of n0-decisions.md). Tests check that each schema accepts the documented
examples that its parser accepts.
| Contract | Direction | Promise |
|---|---|---|
notarizing.check-report/1 | Input | Frozen. The schema and the fixtures change only with a paired review in ka2a and notarizing. scripts/spec/check.py holds their SHA-256 digests. |
notarizing.evidence-over-ka2a/1 | Input and output over ka2a | Frozen, as above. The body of change.report is notarizing.ka2a-change-report/1 and follows the output rule. |
notarizing.cli/1 | Output of --output json | The envelope members stay: schema_version, command, ok, access and warnings, with result on success and error (code, message, exit_code, optional hint and details) on failure. A result can gain optional members. Error codes are the domain codes; a new code can appear. |
| Exit codes | Output | 0 success, 1 failure, 2 usage error, 3 workspace busy, 4 unknown outcome, 5 unsupported, 130 interrupted. A code keeps its meaning. A new kind of failure gets 1 unless the specification adds a code first. |
notarizing.graph/1 | Output of graph export; input of graph export --view FILE | Output rule. The re-export reads strictly. |
notarizing.bundle/1 | Output of bundle export; input of bundle import | Output rule. An earlier release refuses a bundle with a section that it does not know (for example review events or corrections) and never drops it. The schema of manifest.json is bundle-manifest.schema.json; it describes what the bundle reader of this release accepts. |
notarizing.bindings/1, notarizing.policy/1 | Input | Strict input rule. Schemas: bindings.schema.json, policy.schema.json. |
notarizing.ka2a-adapter/1 | Input | Strict input rule. An unknown member stops serve. Schema: ka2a-adapter.schema.json. |
gotestreport.mapping/1 | Input of the example producer examples/producers/gotestreport | Strict input rule. Schema: gotestreport-mapping.schema.json. |
notarizing.review-command/1 | Input from the browser | Strict input rule. The schema is in openspec/changes/reimplement-notarizing/schemas/review-command.schema.json. |
notarizing.review-export/1, notarizing.change-report/1 | Output | Output rule. |
notarizing.backup/1 | Output of backup; input of backup verify | Output rule. backup verify reads strictly. |
| MCP tools | Input and output over stdio | The nine tool names stay: list_changes, get_change_report, get_requirement_history, get_receipt, get_assumption, get_graph_neighborhood, get_graph_suggestions, compare_snapshots and search_specs. A tool refuses an unknown argument. A result can gain optional members. Each tool publishes an input and an output schema, with additionalProperties: false, for the binary that serves it. A removed tool answers unsupported, as the pre-R2 tools do. |
| Browser HTTP API (http-api.md) | Between the embedded browser assets and serve | No promise. The browser assets and the server ship in one binary and change together. The API refuses unknown request members. Other clients are not supported. |
Control API (notarizing.control/1) | Between the CLI and serve | No promise. Use the same binary for the CLI and serve. The CLI refuses an answer that it does not know: "the control response does not match this client version". |
| Workspace schema | On disk | See below. |
Internal version names, such as notarizing.assessment-rules/2, the search chunker and
corpus versions and notarizing.suggest/1, identify computations in stored records. They
are not contracts for other programs.
Workspace schema
- A later binary can add migrations. A migration applies once, in order, and goes forward only. A released migration never changes.
- A command that owns the workspace applies the pending migrations. Read-only commands and
mcprefuse a workspace that needs a migration. - A binary refuses a workspace or a backup with a newer schema with
unsupported_schemaand changes nothing. - There is no downgrade. To go back, restore a backup that the older binary made.
The upgrade notes list each migration.
Before 1.0
A contract that is not frozen can still change in an incompatible way before a 1.0 release. Such a change gets a new version name. A change to a surface without a version name, such as a CLI flag or an exit code, gets an entry under "Changed" or "Removed" in CHANGELOG.md. No contract changes in silence.