Add Family Connection and Context v1 conformance vectors

.github/workflows/ci.yml

@@ -6,6 +6,17 @@ on:
   pull_request:
 
 jobs:
+  family-connection-v1-vectors:
+    name: family connection v1 vectors
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - run: python -m pip install --require-hashes -r scripts/requirements-family-connection-v1-vectors.txt
+      - run: python3 scripts/validate-family-connection-v1-vectors.py
+
   python:
     name: python launcher
     runs-on: ubuntu-latest

AGENTS.md

@@ -40,8 +40,12 @@ that ties the family together and reserves the `determa` name on every registry.
 - **No AI/assistant attribution** anywhere (commits, PRs, comments, docs).
 - Keep the three launchers **behaviorally identical** (same dispatch, env-var selection, `list` grouping, help text). Each has its own test suite.
 
-## Gates (`ci.yml` runs all three)
+## Gates (`ci.yml` runs the family vectors and all three launchers)
 ```sh
+# family connection/context vectors
+python3 -m pip install --require-hashes -r scripts/requirements-family-connection-v1-vectors.txt
+python3 scripts/validate-family-connection-v1-vectors.py
+
 # python
 cd python && pip install -e '.[dev]' && ruff check . && pytest -q
 # rust

README.md

@@ -41,6 +41,10 @@ reserves the language-neutral connection, context, endpoint-routing, and future
 family command contract. It is design documentation only: the current launchers
 remain local dispatchers and do not yet implement remote connections or clients.
 
+The machine-readable [v1 conformance vectors](conformance/family-connection-v1/)
+fix the expected configuration, endpoint, environment-name, and routing results
+without adding those behaviors to the launchers.
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

conformance/family-connection-v1/README.md

@@ -0,0 +1,87 @@
+# Family Connection/Context v1 conformance vectors
+
+These JSON fixtures are the ecosystem-neutral executable examples for
+[Family Connection and Context Configuration v1](../../docs/family-connection-context-v1.md).
+They do not define a production client or resolver.
+
+## Suites
+
+- `configuration.json` stores configuration inputs as JSON source strings so
+  integer spellings and duplicate keys remain testable. Successful cases return
+  the closed normalized logical value; rejected cases return an error code.
+- `endpoints.json` maps endpoint inputs to canonical endpoints or rejection
+  codes.
+- `environment.json` maps product/resource names to environment override names
+  and declares sets that must remain pairwise distinct.
+- `routing.json` defines reusable valid configurations and request cases for
+  precedence, exact/product matching, invalid-value handling, and context
+  fallback.
+
+Every case has a repository-wide unique `id` and an `expect` object containing
+exactly one of:
+
+```json
+{"value": "canonical output"}
+```
+
+```json
+{"error": "stable_error_code"}
+```
+
+## Error codes
+
+| code | meaning |
+|---|---|
+| `duplicate_key` | a source object repeats a key before model construction |
+| `invalid_source` | source JSON is malformed, unavailable as a string, or contains a non-JSON numeric constant |
+| `missing_field` | a required closed-model field is absent |
+| `unknown_field` | a closed-model object contains an undeclared field |
+| `invalid_type` | a value has a type not accepted at that location |
+| `invalid_version` | `version` is not the integer token `1` |
+| `invalid_name` | a connection, context, provider, product, or resource name is invalid |
+| `invalid_reference` | a context or route names an absent object |
+| `invalid_endpoint_type` | an endpoint is not a string |
+| `invalid_endpoint_characters` | an endpoint contains forbidden whitespace, controls, surrogates, or backslash |
+| `invalid_endpoint_syntax` | an endpoint is empty, relative, opaque, or has a query/fragment |
+| `unsupported_endpoint_scheme` | an endpoint scheme is not HTTP(S) |
+| `invalid_endpoint_authority` | authority structure, user-info, or IP brackets are invalid |
+| `invalid_endpoint_host` | IDNA, IPv4, IPv6, zone, or host-label validation fails |
+| `invalid_endpoint_port` | a port is empty, non-canonical, zero, or out of range |
+| `invalid_endpoint_path` | path syntax or percent encoding is unsupported |
+| `insecure_endpoint` | HTTP targets a non-loopback host |
+| `invalid_environment` | environment overrides are not a string map |
+| `invalid_connection` | a present override is empty or names an absent connection |
+| `invalid_context` | a selected context is not a configured context name |
+| `unresolved_connection` | every resolution level is absent |
+
+These codes classify vector outcomes only. A later public client/protocol error
+contract requires its own specification and conformance work.
+
+## Validation
+
+From the repository root:
+
+```sh
+python3 -m pip install --require-hashes \
+  -r scripts/requirements-family-connection-v1-vectors.txt
+python3 scripts/validate-family-connection-v1-vectors.py
+```
+
+The test-only IDNA path uses the hash-pinned `idna==3.7` package as a source for
+tables generated from the official [Unicode 15.1.0 IDNA mapping table](https://www.unicode.org/Public/idna/15.1.0/IdnaMappingTable.txt)
+and for the ContextJ and RFC 5893 bidi helpers referenced by UTS #46. The
+harness verifies at startup that the package's IDNA and UTS #46 data report
+exactly Unicode 15.1.0 and that the Python runtime supplies Unicode data at
+least as new as 15.1.0.
+
+The harness implements revision-31 ToASCII directly: map, normalize to NFC,
+split labels, decode and validate existing Punycode, apply the configured
+hyphen, status, ContextJ, bidi, and DNS-length criteria, then Punycode-encode
+non-ASCII labels. It deliberately does not call `idna.encode`, because that
+API adds IDNA2008 code-point eligibility beyond the merged contract. The exact
+15.1 UTS #46 status table remains authoritative when a later Python runtime
+knows newer code points. Positive NV8, normalization, Unicode-version, and
+ContextJ/bidi vectors prevent reject-all or IDNA2008-only implementations from
+passing. The harness independently applies the remaining v1 strict URI,
+configuration, environment-name, and routing rules and is not shipped in any
+launcher package.