feat: close the endpoint, environment-variable, and graph-rule specification gaps

[justinmerrell]

What changes

Closes the five open specification issues that were either silent where the platform ships behaviour, or decided against it. Two revisit rules merged eight days ago in #27 (§5.2's PUBLIC protocol restriction and the endpoint-name grammar); three close TODO markers and registry gaps left open by #13 and #9. Component spec.md now carries no TODO sections at all.

Six commits, one per issue plus a documentation correction, scoped so release-please reads them correctly.

Why

Closes #28. Closes #29. Closes #17. Closes #18. Closes #30.

§5.2 — PUBLIC on every protocol (#28)

§5.2 restricted a PUBLIC endpoint to the HTTP family on two arguments, and the edge-port address form answers both. An HTTP-family PUBLIC endpoint publishes a URL; a TCP/UDP one publishes a host:port address. Exposing a database, a broker or a game server is a capability that ships today and that a conformant document could not express.

Rule	Before	After
PUBLIC protocol	HTTP/HTTPS/WS/GRPC only	Any of the six
readiness REQUIRED	SERVICE with any PUBLIC endpoint	SERVICE with a PUBLIC HTTP-family endpoint
Probe / platformDefault endpoint	Any declared endpoint	Must resolve to an HTTP-family endpoint — new ERR_ENDPOINT_NOT_HTTP

The readiness narrowing is not a new argument. §5.4 already exempts PRIVATE because "a private consumer inside the mesh retries; a browser does not" — an L4 consumer connecting to an edge port retries in exactly the same way. Compelling a probe there would also compel an HTTP path against a port that speaks no HTTP, which is a rule no document can satisfy.

structural-027-public-tcp-endpoint inverts to a pass case and drops its readiness probe: the probe is no longer compelled, and keeping it would now fail the semantic phase instead. structural-028-public-grpc-endpoint stands unchanged.

Whether the contract should expose the edge address is left undecided and recorded as such in §5.2, rather than left to be inferred.

§5.2 — endpoint-name grammar (#29)

The name does not become a DNS label; it is composed into one beside the component and application names, and the slug grammar breaks that composition twice. A name drawn from the same alphabet as the parts it joins to cannot be delimited — with a hyphen separator, endpoint api on component web and component api-web compose to the same label, and doubling the separator only helps if neither side may contain the doubled form, which the slug grammar permits. And a 63-character label shared with three other parts leaves no room for a name allowed to reach 62, forcing every implementation into a truncation rule that reintroduces the collisions the grammar was meant to prevent.

Now ^[a-z][a-z0-9]{0,19}$, applied in the three places that carry it: the endpoints map's propertyNames, ComponentProbe.endpoint, and ComponentPlatformDefault.endpoint.

§5.3 — environment variables (#17)

§5.3 was a bare TODO while the schema already carried the whole shape.

• Key grammar is REQUIRED, not conventional: ^[A-Z_][A-Z0-9_]*$, structural, already enforced and now stated.
• Precedence has no answer, because a collision is an error. envVars is a sequence rather than a mapping, so §5's "a repeated key is ERR_DUPLICATE_KEY in the parser phase" does not reach it — two entries of a sequence repeat nothing at the YAML level, and a repeated key today means whatever an implementation's last write happens to be. An input's target.envVarKey binds into the same namespace and competes with those entries. Both are now semantic errors: ERR_DUPLICATE_ENV_KEY and ERR_CONFLICTING_ENV_KEY. Ranking the two instead would settle the ambiguity without telling anyone there was one — the trade blueprint §5.2 refused for input merging.
• Because the anchor is normative, the tiebreak is written down: the collision anchors at an input's target/envVarKey, and where two inputs collide, at the later in lexicographic input-name order.
• Sensitivity: isSensitive on a LITERAL obliges the handling §6.1 already requires of a generated input. A CONFIG_REF needs no marking — the document holds the name, not the value. A SHOULD prefers either to a marked literal, since isSensitive governs handling and not the fact that the value is bytes in a committed file.

§4.2 — connection type compatibility (#18)

The last place a composition could be internally inconsistent and still validate. Both ends resolved; neither was asked whether it fit.

type is compared for equality, with no widening in either direction. An INTEGER output feeding a STRING input looks harmless — everything is a string at the container boundary — but which string is a per-language formatting decision, and a contract that permitted the wire would be promising a value it cannot describe.

semanticType must agree wherever the consuming input names one. A consumer declaring null accepts any producer; a consumer declaring a tag requires the same tag, including rejecting a null producer, because an unconstrained producer does not satisfy a constrained consumer. That is also the answer to what the tag is for given type exists: type is the primitive shape, semanticType is the backing service, and a Postgres connection string and a MySQL one are both STRING.

Two codes rather than one, so a diagnostic names the axis that failed — ERR_INCOMPATIBLE_TYPE and ERR_INCOMPATIBLE_SEMANTIC_TYPE, both anchored at the connection's fromOutput. Both ends always carry a schema with a required type, so #18's fourth question — an unconstrained producer — has no case to except.

format, enum, pattern, default and isSensitive take no part in the decision, and §4.2 records those silences as gaps rather than as permissions.

§7 — the remaining graph-rule codes (#30)

Each platform code is answered, and the two that need no row say so rather than going unmentioned.

Platform code	Disposition
UNDECLARED_INPUT_KEY	ERR_UNKNOWN_INPUT, semantic. A plain omission — §4.2 resolved the producer end of a wire and left the consumer end.
UNWIRED_REQUIRED_INPUT	ERR_UNWIRED_REQUIRED_INPUT, semantic. A CONNECTION input never reaches the install form, so a graph that leaves one unwired has no later chance to supply it.
COMPONENT_NOT_PUBLISHED	ERR_COMPONENT_NOT_PUBLISHED, capability, in UNCOVERED with a reason. §4.1 says why it reads differently from ERR_UNKNOWN_COMPONENT: a component that exists and is not yet released is a wait rather than a typo.
NO_COMPONENTS	Answered structurally. spec.components is now REQUIRED with minProperties: 1; §1 already made a blueprint a composition of one or more components while the schema accepted spec: {}. No new code — ERR_MISSING_FIELD / ERR_INVALID_VALUE.
DUPLICATE_WIRE_TARGET	No row, and §4.2 records why. connections is a mapping keyed by the consumer input, so a second wire to one input is a repeated key and already ERR_DUPLICATE_KEY in the parser phase. Impossible by construction rather than unenforced.
INCOMPATIBLE_SEMANTIC_TYPE	Answered by #18 above.

Three findings worth a reviewer's attention

1. ERR_UNKNOWN_INPUT caught a live bug in the corpus. blueprint/v1/semantic/010-well-formed-item — the fixture whose own comment calls it "the regression pin" — wired DATABASE_URL into a component that declared no such input, and had been passing as well-formed since it was written. That is precisely the failure #30 says the missing rule permitted, found by the rule itself. The fixture is corrected here, and its comment now enumerates the consumer-end rules it pins.

2. One rule was widened slightly beyond what the issues asked for. checkEndpointReference now resolves a null reference to the elected primary and then applies the same rules to it, rather than returning early. §5.2 makes the primary "what null selects", so a rule about the endpoint a reference names reaches it equally. The consequence is that ERR_ENDPOINT_NOT_PUBLIC can now fire on an elected primary where it previously could not. No existing fixture changed behaviour, but this is a deliberate widening rather than a mechanical one and should be reviewed as such.

3. A sixth commit corrects §10. "Every section above marked TODO…" became false once #17 and #18 closed the last two. It is replaced with the debt that actually remains — schema description fields speaking platform vocabulary (snapshot compute, unpublished Compute Profile slugs). Scoped docs(component) so it cuts no release of its own.

One scoping note: feat(blueprint): decide connection type compatibility also edits component §6.2's TODO into a pointer. That is deliberate — the normative rule lives in blueprint §4.2, and a component document sees only one end of a connection — and component still gets a release from the three feat(component) commits, so the prose ships either way.

Compatibility

• Breaking — a previously valid document now fails.

Six narrowings across the two families: the endpoint-name grammar, the two env-var key rules, the two connection-compatibility axes, the four blueprint graph rules, and a non-empty spec.components. The #28 changes run the other way and are strictly loosening — every document that validates today still validates, and a PUBLIC-TCP-only SERVICE without readiness is now accepted where the current bundle rejects it, which is the correct direction inside a major per §3.

No new v<N> directory, and the reason is that v1 has never been published. git tag -l is empty and .github/release-please/manifest.json reads 0.0.0 for all three families. §3's guarantee — "a document that validated against v1.0.0 MUST validate against every later v1.x.y" — has no released v1.0.0 to run from, so there is no document anywhere that was validated against a published v1 and would now fail. A migration note would have nothing to migrate from.

That argument expires when #1, #2 and #3 merge. #24 sets the same deadline for its divergence 3, and #28/#29 both name it explicitly. If the release PRs land first, this becomes a v2 change.

Corpus impact — verified before each narrowing

• Endpoint names in use are api, console, db, internal, metrics, primary, rpc, web — all inside the new 20-character alphanumeric grammar. The only name outside it is web.api, which is the fixture that exists to be rejected.
• Every blueprint document declares spec.components. The two that do not are parser-phase cases that fail before structural is entered.
• No document in the corpus paired a duplicate env-var key, a colliding target.envVarKey, or an incompatible connection — except semantic-010-well-formed-item, discussed above.

Checklist

• task check passes locally
• 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 — schema descriptions are explanatory, not normative
• Commit messages are Conventional and correctly scoped (the scope drives release-please)
• Commits are DCO signed off (git commit -s)

12 new fixtures, 88 → 100 cases, 0 skipped. Every new code is exercised except ERR_COMPONENT_NOT_PUBLISHED, which is capability and sits in UNCOVERED with a reason. All four component examples and all three blueprint examples validate.

🤖 Generated with Claude Code