feat: reconcile the specification/platform divergences, and expose the edge address

[justinmerrell]

What changes

Closes the last two open issues in this repository, and does it before the first
release rather than after. Closes #24. Closes #32.

#24 collects three places where PR #13 decided against implemented platform behaviour.
Each is a live divergence — a conformant implementation and the platform return
different verdicts on the same document. #32 records a capability the platform ships
that no document could reference.

Four decisions, one ADR, ten commits scoped so release-please reads them correctly.

#	Subject	Decision	Direction
1	Cycle detection (blueprint §4.2)	Adopt the platform — cycles permitted, ERR_DEPENDENCY_CYCLE withdrawn	loosening
2	Parameter merge (blueprint §5.2)	Hold ERR_CONFLICTING_INPUT_SCHEMA	unchanged
3	SERVICE endpoints (component §5)	Adopt the platform — at least one required	breaking
4	Edge address (#32)	PUBLIC_ADDRESS and PUBLIC_PORT added	additive

After this, no divergence survives except 2, where ADR 0001 §1 already supplies
the answer and the platform has a defect to fix.

Why now

git tag -l is empty, .github/release-please/manifest.json reads 0.0.0 for all
three families, and #1/#2/#3 have sat open since 2026-08-08. Component §3's guarantee
is stated against a released version, and there is none — so decision 3 lands free
today and costs a v2 directory the moment a tag exists.

That argument had been relied on twice (#31, #1) and existed only in PR descriptions.
ADR 0005 §1 writes it down, GOVERNANCE.md → Compatibility review now points at it,
and it names its own closing condition exactly.

The decisions

1. Cycles permitted (ADR 0005 §2)

§4.2 required acyclicity while conceding in the same clause that "acyclicity is not a
resolution hazard". The rule was held on three arguments; the load-bearing one does
not survive contact:

It obliges every implementation to be a two-pass resolver in perpetuity.

It obliges nothing. Component §6.2 already makes an output a function of its own node,
normatively and permanently — so resolving outputs before binding edges is what the
contract already describes, not a burden acyclicity would have lifted. Against
that stood mutual service discovery, a composition with a live consumer that the rule
made inexpressible.

What the loosening forecloses is stated in the clause rather than discovered later: no
later rule may assume a materialisation order without being a major version.

2. The merge conflict stands (ADR 0005 §3)

Unchanged, and §5.2's argument is unchanged with it — silent first-wins hands the
second component a value validated against the first's rules and fails at deploy time,
far from the two documents that disagreed.

The new pin caught a defect rather than merely describing one. §5.2 says two
declarations are identical "when their schema blocks are equal once defaults are
applied". tools/src/semantic.ts compared JSON.stringify(schema) — key-order
sensitive, no defaults applied — so it rejected two declarations the prose calls the
same. semantic-022 varies ui, isRequired, key order and written-out defaults;
it was red on arrival and canonicalValueSchema fixes it.

3. A SERVICE must declare an endpoint (ADR 0005 §4) — BREAKING

This is the divergence that ran the other way. Everywhere else the specification
rejected a document the platform accepted, so an author following the contract was
safe. Here the specification was looser: it called a document valid that the
platform will not deploy. That is the one direction a contract must not be wrong in.

Structural, no new code — absent block is ERR_MISSING_FIELD, empty block is
ERR_INVALID_VALUE, matching the two-spelling distinction §5 already makes in the
forbidden direction.

4. The edge address is readable (ADR 0005 §5)

platformDefault.source gains PUBLIC_ADDRESS (host:port) and PUBLIC_PORT (the
allocated port alone). The four sources now pair exclusively with §5.2's two address
forms, with ERR_ENDPOINT_NOT_L4 as the mirror of ERR_ENDPOINT_NOT_HTTP — two codes
so a diagnostic names the axis that failed.

Admitting an HTTP-family endpoint to PUBLIC_ADDRESS was refused deliberately, and
§6.1 says why: it is published through the shared ingress rather than on an allocated
port, so the derivation would yield the ingress address — true, and not what an author
asking for an edge address wants. #32's self.publicAddress.<ep> alternative is
rejected in ADR 0005 §5; this contract has no expression language.

Three findings worth a reviewer's attention

1. #24 understates divergence 3's blast radius by an order of magnitude. It names
examples/minimal.yaml and structural-001-minimal-valid. The sweep found 30
documents declaring a SERVICE with no endpoints.

2. Seventeen negative fixtures stopped pinning their own rule, and the runner could
not have told us. conformance.ts matches declared diagnostics as a subset, so an
extra ERR_MISSING_FIELD is tolerated — none of them was failing. But a negative
fixture that fails for two reasons is not a pin: structural-011-schedule-on-service
would have stayed red with the schedule rule deleted. Each now carries a PRIVATE
endpoint and fails only for its own rule. Seven component documents inside listing item
trees were silently non-conformant for the same reason and are fixed too.

3. semantic-007-probe-on-endpointless-workload became unwritable and is re-based
onto a WORKER. Its premise is a probe on a workload declaring no endpoint, which is
now impossible as a SERVICE. The other three kinds declare none and may still carry a
probe, so the ERR_AMBIGUOUS_ENDPOINT it pins survives intact — and that is exactly
why §5.2 still has to say what happens when nothing is elected.

Compatibility

• Breaking — a previously valid document now fails.

One narrowing only: a SERVICE declaring no endpoints, or an empty mapping.
Decisions 1 and 4 run the other way and are strictly loosening or additive.

No new v<N> directory, for the reason in ADR 0005 §1 — v1 has never been
published. That argument expires when #1/#2/#3 merge, so this should land first.

Corpus impact — verified, not assumed

• minimal.yaml and structural-001-minimal-valid gain a PRIVATE endpoint;
  §5.4 compels a readiness probe only on a PUBLIC HTTP-family one, so "minimal"
  stays minimal.
• Three documents still declare a SERVICE with no endpoints, all deliberate: the two
  parser cases, which fail before structural is entered, and
  structural-033, which exists to be this.
• ERR_DEPENDENCY_CYCLE appears nowhere in the corpus, prose, or tooling.

Three coverage gaps closed in passing

Found while scoping #32, and worth fixing whatever it decided: no fixture exercised
PUBLIC_HOSTNAME (only PUBLIC_URL appeared anywhere), none exercised a
platformDefault omitting its endpoint and relying on §5.2's election, and none
exercised a PUBLIC UDP endpoint.

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
• Commit messages are Conventional and correctly scoped
• Commits are DCO signed off (git commit -s)

Each behavioural change lands as a deliberately red test(...) commit followed by the
commit that turns it green, with the failing output quoted in the message — the
fail-before evidence CLAUDE.md non-negotiable 3 requires.

task check green: 3 modules linted, 3 bundles match a fresh compile, 9 examples
validate, 130 conformance cases pass, 0 skipped (122 → 130).

Follow-ups

ADR 0005 records two platform defects to file: the merge conflict check, and the merge
sort key ((ordering, componentId) names two fields this contract does not have).