The scope of the 1.0.1 corrective delta

Status

Accepted — 23 August 2026. Implemented in standards/ver/1.0.1/ and classified in `COMPATIBILITY.md`.

Context

The August 2026 audit produced 189 findings, of which 82 are classified patch-correction: defects that could, in principle, be fixed without adding capability. The schema alone has 22 findings against it (SCH-01–SCH-22), most of them real.

The temptation is to fix all of them. It is the wrong instinct, for a reason that is easy to state and easy to forget: a corrective release's value is entirely in the confidence that it changes nothing you depend on. A 1.0.1 that touches twenty schema constraints is not a correction, it is an unversioned minor release, and every consumer must re-test against it as though it were one. At that point the release has cost more than it saved and nobody will adopt it.

Three specific pressures had to be resisted:

• Closure inconsistency. Seven objects in the schema are accidentally open — sha256Hash, spaceDescriptor.model, .reference, .provenance, metadata.trust[], conflicts[].values[], embedding.recipe — with no stated policy (SCH-04). Closing all of them is a one-line-each change that feels free.
• Pattern defects. The space_id pattern rejects hyphenated authority labels (SCHEMA-05) and contradicts the word "semver" it implements (SCH-10). Both are audit-classified patch-correction.
• Missing constraints. embedding.space_id is unpatterned (SCH-06), preprocessing has no required members (SCH-11), and tolerance_cosine admits 0.0001 (SCH-20).

Each is a genuine defect. None of them meets the bar below.

Options

(a) Fix every patch-correction finding the schema can express. Maximally correct schema; roughly twenty constraint changes. Consumers must re-validate their entire corpus against a schema that differs from the published one in twenty places, and any one of those could reject a Record that a defensible reading of 1.0.0 permitted. Adoption cost approaches that of a minor release.

(b) Ship no schema change at all; make 1.0.1 a pure prose annex. Zero risk of invalidating anything. Also leaves the golden example failing its own specification's §5, which is the defect most likely to be noticed by the first person who reads the artifacts, and leaves the identity object demonstrably unclosed despite carrying evidence that closure was intended.

(c) A surgical delta: schema changes only where the prose already required the constraint and the schema forgot to enforce it. Fixes the defects that make published artifacts self-contradictory, and defers everything else — including genuine patch-correction items — to 1.1, where a ver_version bump gives consumers the signal they need.

Decision

Option (c). The 1.0.1 delta is exactly:

Three schema constraint changes, each meeting the bar "1.0.0 prose already required this; the schema simply failed to check it":

1. Perceptual digest values become algorithm-conditional — pdq/1.0 ⇒ ^[a-f0-9]{64}$, phash-dct/64 ⇒ ^[a-f0-9]{16}$, as if/then subschemas inside the perceptual item. Backed by §5's "256-bit" and "64-bit". The alg enum is unchanged.
2. identity.pixel_hash gains "additionalProperties": false. Its own inert "alg": true, "value": true entries are proof that closure was intended and forgotten (SCH-03).
3. identity.content_hash becomes {"allOf": [{"$ref": "#/$defs/sha256Hash"}], "unevaluatedProperties": false}. The shared sha256Hash definition is deliberately not closed — closing it breaks the pixel_hash allOf branch — so closure is applied at each use site.

Metadata only, otherwise: $id → …/ver-record-1.0.1.json, title names the artifact release, description points at the annex. ver_version stays const: "1.0".

Five example edits, all valid under both the 1.0.0 and the 1.0.1 schema: the 96-hex pdq/1.0 value truncated to its recoverable 64-hex digest; the placeholder raw-segment digest replaced with the real digest of the bytes present; the @context replaced with one that defines the prefixes the document uses; a second embed chain event so the chain accounts for both embeddings; and the elided 30-octet ICC fragment replaced with a real, complete APP2 payload (ICC_PROFILE\0 + sequence octets + a genuine 588-octet sRGB profile) so the golden example satisfies E11/E26 at its declared L3 (annex §2.2, edit (e)).

One normative annex, VER-1.0.1-errata-annex.md, carrying every correction as a numbered E-item — E1 is the identity-gradient correction, E29 the weights_sha256 preimage note — plus a short editorial-notes section. Items append; none is renumbered, so a citation stays valid. The specification .docx is never edited.

Everything else defers. Notably: all seven remaining open objects, the space_id pattern relaxations, embedding.space_id patterning, required preprocessing members, and the tolerance_cosine floor. Where the audit classified those patch-correction and this branch dispositioned them to 1.1 or to the profile validator, the ledger records the divergence and names this ADR.

Consequences

Good.

• The compatibility statement is short enough to verify by hand: three constraints, each a tightening, each rejecting only Records that already violated 1.0.0 prose. COMPATIBILITY.md §2 enumerates all three.
• The corrected example validates under both schemas. The golden example never becomes the artifact that forces an upgrade.
• Deferred items lose nothing. Constraints that cannot go in the schema go into the conformance profile as error codes, where they are enforced and labelled as profile rules rather than silently smuggled into a patch release.

Bad.

• The schema stays wrong in known ways. preprocessing: {} still validates; embedding.space_id still accepts anything; seven objects still accept undeclared members. Anyone reading only the schema sees defects that this branch found and did not fix. Mitigated by the errata ledger and by the profile validator, but the schema itself remains the weaker artifact.
• The space_id pattern relaxation is genuinely inconvenient to defer: producers with hyphenated authorities cannot mint conformant ids until 1.1. Relaxing it in a patch release, though, produces 1.0.1-valid Records that the 1.0.0 schema rejects — a Q2 failure — which is exactly what a patch release must not do.
• Three separate documents now have to agree on what changed. Mitigated by generating the ledger's tables from the audit index and cross-checking the annex's own §2 tables against COMPATIBILITY.md §2 and §3.

Neutral.

• The seven open objects become an extension point by accident, and some producer will use one for as long as 1.0.x is current. 1.1 §13 gives them a real one (extensions), and 1.1 §15.2 closes all seven — under the VERSIONING.md §2.3 evident-intent carve-out, as a named row on the 1.1 ratification checklist. (An earlier revision of this bullet said 1.1 would leave them open to keep its schema a clean superset of 1.0.1; the 23 August owner review withdrew that superset goal — ledger REV-21 — and nothing about this ADR's decision changes either way: deferring the closure out of 1.0.1 was the right call for a corrective release, and where it lands afterwards is 1.1's question.)