feat: reconcile the value-shape vocabulary — STRING, NUMBER, BOOLEAN, JSON

[justinmerrell]

What changes

The value-shape vocabulary on schema.type becomes STRING, NUMBER, BOOLEAN, JSON in both the component and blueprint families. INTEGER is withdrawn. Alongside it, pattern and enum are forbidden on a JSON value and format is confined to STRING — two restrictions the schema's own description fields already claimed and nothing enforced. New component §6.3 Value schemas publishes the vocabulary in prose for the first time, with three requirement IDs; blueprint §5.3 cites it rather than restating it.

Why

Closes #54 — but not as filed, and the difference is the point.

The issue asked for a two-file rename of INTEGER → NUMBER, citing a "§10" that defines the vocabulary. No such section exists in this repository. Component §10 is Known debt; blueprint and listing §10 are Security considerations. The §10 it cites belongs to musher-dev/platform.

The vocabulary lived only in a schema enum, which CONTRIBUTING ground rule 1 makes informative — so type: NUMBER was rejected here, and applying the rename as filed would have broken CI in exactly the two ways the issue described, mirrored back:

• structural-036 (a pass case) would fail with ERR_INVALID_VALUE;
• semantic-012 would die structurally before reaching the ERR_INCOMPATIBLE_TYPE it exists to pin.

Verified against main before touching anything:

{ "ok": false, "phase": "structural",
  "diagnostics": [ { "code": "ERR_INVALID_VALUE",
                     "path": "/spec/contract/inputs/gamePort/schema/type" } ] }

Scope was 7 corpus hits, not 2, plus 3 stale uses in blueprint prose and the two schema modules themselves. So this is a specification/platform divergence of the class ADR 0005 and ADR 0010 handle, and it is settled the same way: decided on the merits, recorded, then schema, prose and corpus moved together.

ADR 0013 carries the reasoning — six decisions, each decidable on its own, plus the two silences it deliberately leaves open (a default is not checked against the constraints beside it; semanticType is not paired with type).

Why now

git tag -l is empty, published.json reads "releases": {}, and #1/#2/#3 are still open, so ADR 0005 §1's pre-publication window is open — check:compat reports "No releases to replay yet", which is the mechanical form of the same fact. Adding a member stays free forever; withdrawing one is free now and never again.

On INTEGER vs keeping both

Keeping INTEGER alongside NUMBER was the cheaper change — purely additive, not breaking. It was rejected on what it would have obliged the contract to answer: is 5432.0 an INTEGER; does an INTEGER output satisfy a NUMBER input given §4.2 permits no widening in either direction; what would a bound mean on each. Under that no-widening rule, two near-synonymous numeric shapes make independently authored components reject each other over a difference no consumer can observe. Integrality is now written as a constraint: type: NUMBER with pattern: '^-?[0-9]+$', which says strictly more about a port than type: INTEGER ever did (the value schema has never carried minimum/maximum).

Controlled-vocabulary justification (GOVERNANCE.md)

type is an ADR 0003 placement-one vocabulary, so the two additions justify themselves against the terms that exist:

• NUMBER — replaces INTEGER rather than joining it. It is JSON's own numeric kind and the only numeric term the transport can distinguish.
• JSON — no existing term covers a structured value. STRING would carry the document, but a consumer that will parse what it receives and one that will not are asking for different things, and nothing in the contract could tell them apart.

Compatibility

• Breaking — a previously valid document now fails.

Two ways: any document using type: INTEGER, and any pairing format with a non-STRING type. No example and no fixture carried the second, so it cost nothing now and would have cost a major version later.

Per ADR 0005 §1 and GOVERNANCE.md § Compatibility review, the window waives the v<N> directory and the migration note while a family is unpublished. It waives nothing else: this needs CODEOWNERS approval, and both feature commits carry a BREAKING CHANGE: trailer.

task changes — 12 changes can reject a document that validates today

### blueprint/v1
- spec.parameters.*.schema.enum — maxItems — → 0
- spec.parameters.*.schema.format — type — → "null"
- spec.parameters.*.schema.pattern — type — → "null"
- spec.parameters.*.schema.type — enum removed INTEGER
- spec.parameters.*.schema.type — enum added NUMBER, JSON

### component/v1
- spec.contract.inputs.*.schema.enum — maxItems — → 0
- spec.contract.inputs.*.schema.format — type — → "null"
- spec.contract.inputs.*.schema.pattern — type — → "null"
- spec.contract.inputs.*.schema.type — enum removed INTEGER
- spec.contract.inputs.*.schema.type — enum added NUMBER, JSON
- spec.contract.outputs.*.schema.enum — maxItems — → 0
- spec.contract.outputs.*.schema.format — type — → "null"
- spec.contract.outputs.*.schema.pattern — type — → "null"
- spec.contract.outputs.*.schema.type — enum removed INTEGER
- spec.contract.outputs.*.schema.type — enum added NUMBER, JSON

#### Requirements
- COMP-VAL-001, COMP-VAL-002, COMP-VAL-003 — requirement added

Conformance

Nine new fixtures; five existing ones migrated with their declared diagnostics unchanged (NUMBER ≠ STRING exactly as INTEGER ≠ STRING, so every mismatch survives).

Case	Expected	Pins
component/structural/039-integer-value-type	fail — ERR_INVALID_VALUE	COMP-VAL-001
component/structural/040-number-value-type	pass	COMP-VAL-001
component/structural/041-json-value-type	pass	COMP-VAL-001
component/structural/042-json-value-with-pattern	fail — ERR_INVALID_TYPE	COMP-VAL-002
component/structural/043-json-value-with-enum	fail — ERR_INVALID_VALUE	COMP-VAL-002
component/structural/044-format-on-a-non-string-value	fail — ERR_INVALID_TYPE	COMP-VAL-003
blueprint/structural/024-integer-parameter-type	fail — ERR_INVALID_VALUE	COMP-VAL-001
blueprint/structural/025-json-parameter-with-pattern	fail — ERR_INVALID_TYPE	COMP-VAL-002
blueprint/structural/026-json-parameter	pass	COMP-VAL-001

structural-039 is the one that matters for review: it passed before this branch and fails after, which is what makes the withdrawal executable rather than declared. The blueprint cases are not redundant — the two families hold separate $defs, so a component fixture proves nothing about a blueprint document.

Zero new diagnostic codes, zero registry rows, zero UNCOVERED entries, and no change to tools/ — the runner compares schema.type by string equality and maps Ajv keywords to codes generically, so the vocabulary was never encoded there.

Checklist

• task check passes locally (exit 0; 155 cases, 36/40 requirements pinned, Ajv/Blaze agree on 143 subjects with 0 disagreements)
• schemas/dist/ regenerated with task bundle and committed (never edited by hand)
• Conformance fixtures added for every behavioural change, each citing a clause
• Normative prose updated in the affected spec.md
• Commit messages are Conventional and correctly scoped
• Commits are DCO signed off

Follow-ups

1. musher-dev/platform PR #1997 carries the vocabulary but not the pattern/enum/format restrictions — the one half where this repository is ahead. Its pin for the two fixtures can be lifted once this lands.
2. minimum/maximum on a value schema is a separate design surface, and additive, so it stays available after the window closes.