musher-dev · justinmerrell · Aug 9, 2026 · Aug 9, 2026 · Aug 9, 2026
@@ -163,12 +163,13 @@ later-phase diagnostic before the earlier phases pass.
 ## Coverage status
 
 `parser`, `structural` and `semantic` are covered. Every diagnostic code the
-three `spec.md` files declare is exercised by at least one case, with one
-exception:
+three `spec.md` files declare is exercised by at least one case, with two
+exceptions, both `capability`:
 
 | Code | Why it has no case |
 |---|---|
 | `ERR_UNKNOWN_COMPONENT` | `capability` — resolving a published reference needs the catalog, and no phase a client runs may reach the network |
+| `ERR_VERSION_NOT_MONOTONIC` | `capability` — comparing a version against the lineage it extends needs the catalog, and a fixture is one document with no previous release to be greater than |
 
 That table is not prose anyone has to remember to update.
 `task check:conformance` derives it: every `ERR_*` row in a family's own

@@ -137,6 +137,41 @@
       "phase": "structural",
       "path": "structural/023-field-from-newer-release"
     },
+    {
+      "id": "structural-024-container-port-below-range",
+      "phase": "structural",
+      "path": "structural/024-container-port-below-range"
+    },
+    {
+      "id": "structural-025-container-port-above-range",
+      "phase": "structural",
+      "path": "structural/025-container-port-above-range"
+    },
+    {
+      "id": "structural-026-privileged-container-port",
+      "phase": "structural",
+      "path": "structural/026-privileged-container-port"
+    },
+    {
+      "id": "structural-027-public-tcp-endpoint",
+      "phase": "structural",
+      "path": "structural/027-public-tcp-endpoint"
+    },
+    {
+      "id": "structural-028-public-grpc-endpoint",
+      "phase": "structural",
+      "path": "structural/028-public-grpc-endpoint"
+    },
+    {
+      "id": "structural-029-endpoint-name-not-a-slug",
+      "phase": "structural",
+      "path": "structural/029-endpoint-name-not-a-slug"
+    },
+    {
+      "id": "structural-030-two-public-endpoints",
+      "phase": "structural",
+      "path": "structural/030-two-public-endpoints"
+    },
     {
       "id": "semantic-001-floating-tag-image-reference",
       "phase": "semantic",
@@ -146,6 +181,31 @@
       "id": "semantic-002-probe-names-unknown-endpoint",
       "phase": "semantic",
       "path": "semantic/002-probe-names-unknown-endpoint"
+    },
+    {
+      "id": "semantic-003-platform-default-names-unknown-endpoint",
+      "phase": "semantic",
+      "path": "semantic/003-platform-default-names-unknown-endpoint"
+    },
+    {
+      "id": "semantic-004-platform-default-names-private-endpoint",
+      "phase": "semantic",
+      "path": "semantic/004-platform-default-names-private-endpoint"
+    },
+    {
+      "id": "semantic-005-no-primary-endpoint-elected",
+      "phase": "semantic",
+      "path": "semantic/005-no-primary-endpoint-elected"
+    },
+    {
+      "id": "semantic-006-primary-endpoint-elected",
+      "phase": "semantic",
+      "path": "semantic/006-primary-endpoint-elected"
+    },
+    {
+      "id": "semantic-007-probe-on-endpointless-workload",
+      "phase": "semantic",
+      "path": "semantic/007-probe-on-endpointless-workload"
     }
   ]
 }
@@ -0,0 +1,33 @@
+# The platform default derives from "console", and the only endpoint is "api".
+# JSON Schema cannot catch it: the endpoint names are mapping keys elsewhere
+# in the document.
+specVersion: v1
+kind: COMPONENT
+metadata:
+  version: 1
+spec:
+  workload:
+    kind: SERVICE
+    source:
+      type: IMAGE
+      ref: nginx:1.29.4-alpine
+    endpoints:
+      api:
+        containerPort: 8080
+        protocol: HTTP
+        visibility: PUBLIC
+    health:
+      readiness:
+        path: /healthz
+        endpoint: api
+  contract:
+    inputs:
+      consoleUrl:
+        schema:
+          type: STRING
+        platformDefault:
+          source: PUBLIC_URL
+          endpoint: console
+        ui:
+          label: Console URL
+    outputs: {}
@@ -0,0 +1,6 @@
+[
+  {
+    "code": "ERR_UNKNOWN_ENDPOINT",
+    "path": "/spec/contract/inputs/consoleUrl/platformDefault/endpoint"
+  }
+]
@@ -0,0 +1,7 @@
+{
+  "id": "semantic-003-platform-default-names-unknown-endpoint",
+  "phase": "semantic",
+  "expected": "fail",
+  "clause": "specifications/component/v1/spec.md#inputs",
+  "summary": "A platform default naming an endpoint the workload does not declare is rejected."
+}
@@ -0,0 +1,28 @@
+# PUBLIC_URL derives an externally reachable address, and a PRIVATE endpoint
+# has none to give.
+specVersion: v1
+kind: COMPONENT
+metadata:
+  version: 1
+spec:
+  workload:
+    kind: SERVICE
+    source:
+      type: IMAGE
+      ref: nginx:1.29.4-alpine
+    endpoints:
+      internal:
+        containerPort: 8080
+        protocol: HTTP
+        visibility: PRIVATE
+  contract:
+    inputs:
+      selfUrl:
+        schema:
+          type: STRING
+        platformDefault:
+          source: PUBLIC_URL
+          endpoint: internal
+        ui:
+          label: Own URL
+    outputs: {}
@@ -0,0 +1,6 @@
+[
+  {
+    "code": "ERR_ENDPOINT_NOT_PUBLIC",
+    "path": "/spec/contract/inputs/selfUrl/platformDefault/endpoint"
+  }
+]
@@ -0,0 +1,7 @@
+{
+  "id": "semantic-004-platform-default-names-private-endpoint",
+  "phase": "semantic",
+  "expected": "fail",
+  "clause": "specifications/component/v1/spec.md#inputs",
+  "summary": "A platform default deriving a public address from a PRIVATE endpoint is rejected."
+}
@@ -0,0 +1,25 @@
+# Two PUBLIC endpoints, and the probe names neither. Section 5.2 elects no
+# primary here and the reference is rejected rather than resolved by sort
+# order, which would let a new endpoint silently re-point this probe.
+specVersion: v1
+kind: COMPONENT
+metadata:
+  version: 1
+spec:
+  workload:
+    kind: SERVICE
+    source:
+      type: IMAGE
+      ref: nginx:1.29.4-alpine
+    endpoints:
+      api:
+        containerPort: 8080
+        protocol: HTTP
+        visibility: PUBLIC
+      console:
+        containerPort: 8081
+        protocol: HTTP
+        visibility: PUBLIC
+    health:
+      readiness:
+        path: /healthz
@@ -0,0 +1,6 @@
+[
+  {
+    "code": "ERR_AMBIGUOUS_ENDPOINT",
+    "path": "/spec/workload/health/readiness/endpoint"
+  }
+]
@@ -0,0 +1,7 @@
+{
+  "id": "semantic-005-no-primary-endpoint-elected",
+  "phase": "semantic",
+  "expected": "fail",
+  "clause": "specifications/component/v1/spec.md#endpoints",
+  "summary": "A reference omitting the endpoint is rejected where the workload elects no primary."
+}
@@ -0,0 +1,24 @@
+# One PUBLIC endpoint beside a PRIVATE one. The sole PUBLIC endpoint is the
+# primary, so the probe naming none resolves to "web".
+specVersion: v1
+kind: COMPONENT
+metadata:
+  version: 1
+spec:
+  workload:
+    kind: SERVICE
+    source:
+      type: IMAGE
+      ref: nginx:1.29.4-alpine
+    endpoints:
+      web:
+        containerPort: 8080
+        protocol: HTTP
+        visibility: PUBLIC
+      metrics:
+        containerPort: 9090
+        protocol: HTTP
+        visibility: PRIVATE
+    health:
+      readiness:
+        path: /healthz
@@ -0,0 +1,7 @@
+{
+  "id": "semantic-006-primary-endpoint-elected",
+  "phase": "semantic",
+  "expected": "pass",
+  "clause": "specifications/component/v1/spec.md#endpoints",
+  "summary": "The sole PUBLIC endpoint is the primary a probe naming none resolves to."
+}
@@ -0,0 +1,17 @@
+# Section 5 permits a SERVICE to declare no endpoint. A probe on one polls a
+# port that does not exist: the election finds no primary here for the
+# opposite reason it finds none among two PUBLIC endpoints, and rejects it
+# just the same.
+specVersion: v1
+kind: COMPONENT
+metadata:
+  version: 1
+spec:
+  workload:
+    kind: SERVICE
+    source:
+      type: IMAGE
+      ref: nginx:1.29.4-alpine
+    health:
+      liveness:
+        path: /healthz
@@ -0,0 +1,6 @@
+[
+  {
+    "code": "ERR_AMBIGUOUS_ENDPOINT",
+    "path": "/spec/workload/health/liveness/endpoint"
+  }
+]
@@ -0,0 +1,7 @@
+{
+  "id": "semantic-007-probe-on-endpointless-workload",
+  "phase": "semantic",
+  "expected": "fail",
+  "clause": "specifications/component/v1/spec.md#endpoints",
+  "summary": "A probe on a workload declaring no endpoint has no port to poll."
+}
@@ -0,0 +1,16 @@
+# Port 0 binds nothing. The bound is a grammar, so the schema carries it.
+specVersion: v1
+kind: COMPONENT
+metadata:
+  version: 1
+spec:
+  workload:
+    kind: SERVICE
+    source:
+      type: IMAGE
+      ref: nginx:1.29.4-alpine
+    endpoints:
+      web:
+        containerPort: 0
+        protocol: HTTP
+        visibility: PRIVATE
@@ -0,0 +1,6 @@
+[
+  {
+    "code": "ERR_INVALID_VALUE",
+    "path": "/spec/workload/endpoints/web/containerPort"
+  }
+]
@@ -0,0 +1,7 @@
+{
+  "id": "structural-024-container-port-below-range",
+  "phase": "structural",
+  "expected": "fail",
+  "clause": "specifications/component/v1/spec.md#endpoints",
+  "summary": "A containerPort below 1 is rejected."
+}
@@ -0,0 +1,16 @@
+# 65535 is the last port there is; 65536 names one that cannot exist.
+specVersion: v1
+kind: COMPONENT
+metadata:
+  version: 1
+spec:
+  workload:
+    kind: SERVICE
+    source:
+      type: IMAGE
+      ref: nginx:1.29.4-alpine
+    endpoints:
+      web:
+        containerPort: 65536
+        protocol: HTTP
+        visibility: PRIVATE
@@ -0,0 +1,6 @@
+[
+  {
+    "code": "ERR_INVALID_VALUE",
+    "path": "/spec/workload/endpoints/web/containerPort"
+  }
+]
@@ -0,0 +1,7 @@
+{
+  "id": "structural-025-container-port-above-range",
+  "phase": "structural",
+  "expected": "fail",
+  "clause": "specifications/component/v1/spec.md#endpoints",
+  "summary": "A containerPort above 65535 is rejected."
+}
@@ -0,0 +1,18 @@
+# A port below 1024 is discouraged and not rejected: whether the container can
+# bind one depends on a capability the runtime grants, which this document
+# cannot see. This case is what keeps that a SHOULD NOT.
+specVersion: v1
+kind: COMPONENT
+metadata:
+  version: 1
+spec:
+  workload:
+    kind: SERVICE
+    source:
+      type: IMAGE
+      ref: nginx:1.29.4-alpine
+    endpoints:
+      web:
+        containerPort: 80
+        protocol: HTTP
+        visibility: PRIVATE
@@ -0,0 +1,7 @@
+{
+  "id": "structural-026-privileged-container-port",
+  "phase": "structural",
+  "expected": "pass",
+  "clause": "specifications/component/v1/spec.md#endpoints",
+  "summary": "A privileged containerPort is discouraged but validates."
+}