@hypequery/protocol-conformance 0.10.1 → 0.10.3

package/README.md

@@ -35,6 +35,21 @@ hypequery-protocol-conformance run \
 hypequery-protocol-conformance list
 ```
 
+`--families` selects cases but deliberately permits partial adapters. Release
+gates should also pass `--expect-families` with the complete expected adapter
+family set. The run then fails during the handshake if a family was added or
+dropped without updating the gate. When both options are present, their family
+sets must match so the gate cannot assert a family while filtering out its
+cases. Every expected family must also retain at least one case after
+`--skip-fuzz` or `--only-fuzz` filtering:
+
+```bash
+hypequery-protocol-conformance run \
+  --families tagged-values-v1,identifiers-v1 \
+  --expect-families tagged-values-v1,identifiers-v1 \
+  -- python -m hypequery.protocol.adapter
+```
+
 Exit code `0` means every case passed, `1` means conformance failures, and `2` means the runner or adapter protocol could not be set up correctly.
 
 ## Adapter shape
@@ -51,6 +66,22 @@ The exported `createStdioAdapter` helper handles the loop. Your handler maps `(f
 
 The package includes a pinned fixture snapshot, so a pinned package version is also a pinned conformance target. Pass `--fixtures` to test local or newer specifications.
 
+## Repository gates
+
+With Node.js, pnpm, and `uv` installed, build the workspaces and run the
+TypeScript reference, SQL-portability, and Python adapters against the same
+local fixtures:
+
+```bash
+pnpm build
+pnpm conformance
+```
+
+The Python leg asserts its exact announced family set, so removing a supported
+family cannot turn cases into a green “not run” result. See the [fixture update
+runbook](../../specs/security-protocol/fixtures/README.md) when changing a
+fixture family or adding an implementation.
+
 ## License
 
 Apache-2.0.

package/dist/bin/conformance.js

@@ -57,12 +57,21 @@ async function main() {
     const families = typeof options.families === 'string'
         ? options.families.split(',').map((f) => f.trim()).filter(Boolean)
         : undefined;
+    const expectedFamiliesOption = options['expect-families'];
+    if (expectedFamiliesOption === true) {
+        process.stderr.write('error: --expect-families requires a comma-separated value\n');
+        return 2;
+    }
+    const expectedFamilies = typeof expectedFamiliesOption === 'string'
+        ? expectedFamiliesOption.split(',').map((f) => f.trim()).filter(Boolean)
+        : undefined;
     let summary;
     try {
         summary = await runConformance({
             adapterCommand,
             fixturesDir,
             families,
+            expectedFamilies,
             timeoutMs: typeof options['timeout-ms'] === 'string' ? Number(options['timeout-ms']) : undefined,
             skipFuzz: options['skip-fuzz'] === true,
             onlyFuzz: options['only-fuzz'] === true,

package/dist/family-expectations.d.ts

@@ -0,0 +1,9 @@
+/** Validates a release gate's independently maintained fixture-family list. */
+export declare function validateExpectedFamilies(expectedFamilies: readonly string[], manifestFamilies: ReadonlySet<string>): void;
+/** Fails unless an adapter announces exactly the release gate's family set. */
+export declare function assertExpectedFamilies(announcedFamilies: readonly string[], expectedFamilies: readonly string[] | undefined): void;
+/** Prevents a release gate from asserting families while filtering some out. */
+export declare function assertSelectedFamilies(selectedFamilies: readonly string[] | undefined, expectedFamilies: readonly string[]): void;
+/** Ensures filtering cannot leave an asserted family without executable cases. */
+export declare function assertExpectedFamiliesHaveCases(expectedFamilies: readonly string[], effectiveCaseFamilies: ReadonlySet<string>): void;
+//# sourceMappingURL=family-expectations.d.ts.map

package/dist/family-expectations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"family-expectations.d.ts","sourceRoot":"","sources":["../src/family-expectations.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,wBAAgB,wBAAwB,CACtC,gBAAgB,EAAE,SAAS,MAAM,EAAE,EACnC,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,GACpC,IAAI,CAWN;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CACpC,iBAAiB,EAAE,SAAS,MAAM,EAAE,EACpC,gBAAgB,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAC9C,IAAI,CAaN;AAED,gFAAgF;AAChF,wBAAgB,sBAAsB,CACpC,gBAAgB,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAC/C,gBAAgB,EAAE,SAAS,MAAM,EAAE,GAClC,IAAI,CAaN;AAED,kFAAkF;AAClF,wBAAgB,+BAA+B,CAC7C,gBAAgB,EAAE,SAAS,MAAM,EAAE,EACnC,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAAC,GACzC,IAAI,CAON"}

package/dist/family-expectations.js

@@ -0,0 +1,44 @@
+/** Validates a release gate's independently maintained fixture-family list. */
+export function validateExpectedFamilies(expectedFamilies, manifestFamilies) {
+    if (expectedFamilies.some((family) => typeof family !== 'string' || family.length === 0)
+        || new Set(expectedFamilies).size !== expectedFamilies.length) {
+        throw new Error('expected families must be unique non-empty strings');
+    }
+    const absent = expectedFamilies.filter((family) => !manifestFamilies.has(family)).sort();
+    if (absent.length > 0) {
+        throw new Error(`expected families are absent from the manifest: ${absent.join(', ')}`);
+    }
+}
+/** Fails unless an adapter announces exactly the release gate's family set. */
+export function assertExpectedFamilies(announcedFamilies, expectedFamilies) {
+    if (!expectedFamilies)
+        return;
+    const announced = [...announcedFamilies].sort();
+    const expected = [...expectedFamilies].sort();
+    if (announced.length !== expected.length
+        || announced.some((family, index) => family !== expected[index])) {
+        throw new Error(`adapter families did not match expectation: expected ${expected.join(', ') || '(none)'}; `
+            + `announced ${announced.join(', ') || '(none)'}`);
+    }
+}
+/** Prevents a release gate from asserting families while filtering some out. */
+export function assertSelectedFamilies(selectedFamilies, expectedFamilies) {
+    if (!selectedFamilies)
+        return;
+    const selected = [...selectedFamilies].sort();
+    const expected = [...expectedFamilies].sort();
+    if (selected.length !== expected.length
+        || selected.some((family, index) => family !== expected[index])) {
+        throw new Error(`selected families did not match expected families: expected `
+            + `${expected.join(', ') || '(none)'}; selected ${selected.join(', ') || '(none)'}`);
+    }
+}
+/** Ensures filtering cannot leave an asserted family without executable cases. */
+export function assertExpectedFamiliesHaveCases(expectedFamilies, effectiveCaseFamilies) {
+    const untested = expectedFamilies
+        .filter((family) => !effectiveCaseFamilies.has(family))
+        .sort();
+    if (untested.length > 0) {
+        throw new Error(`expected families have no selected cases: ${untested.join(', ')}`);
+    }
+}

package/dist/runner.d.ts

@@ -4,6 +4,8 @@ export interface RunConformanceOptions {
     readonly fixturesDir?: string;
     /** Restrict to these families (intersected with what the adapter announces). */
     readonly families?: readonly string[];
+    /** Fail setup unless the adapter announces exactly these fixture families. */
+    readonly expectedFamilies?: readonly string[];
     readonly timeoutMs?: number;
     readonly skipFuzz?: boolean;
     readonly onlyFuzz?: boolean;

package/dist/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAQA,OAAO,EAOL,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAyJD,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC,CA6GxF"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAcA,OAAO,EAOL,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,8EAA8E;IAC9E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAyJD,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC,CA6HxF"}

package/dist/runner.js

@@ -4,6 +4,7 @@
 import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
 import { compareCase } from './compare.js';
+import { assertExpectedFamilies, assertExpectedFamiliesHaveCases, assertSelectedFamilies, validateExpectedFamilies, } from './family-expectations.js';
 import { createJsonLoader, loadManifest, resolveFixturesDir } from './fs.js';
 import { enumerateAllCases } from './manifest.js';
 import { CONFORMANCE_MANIFEST_VERSION, CONFORMANCE_PROTOCOL_VERSION, } from './types.js';
@@ -145,6 +146,10 @@ export async function runConformance(options) {
     const fixturesDir = resolveFixturesDir(options.fixturesDir);
     const manifest = loadManifest(fixturesDir);
     const loadJson = createJsonLoader(fixturesDir);
+    if (options.expectedFamilies) {
+        validateExpectedFamilies(options.expectedFamilies, new Set(manifest.families.map((family) => family.name)));
+        assertSelectedFamilies(options.families, options.expectedFamilies);
+    }
     const allCases = enumerateAllCases(manifest, loadJson);
     const hostModelFamilies = new Set(allCases
         .filter((c) => {
@@ -163,6 +168,9 @@ export async function runConformance(options) {
         const requested = new Set(options.families);
         cases = cases.filter((c) => requested.has(c.family));
     }
+    if (options.expectedFamilies) {
+        assertExpectedFamiliesHaveCases(options.expectedFamilies, new Set(cases.map((conformanceCase) => conformanceCase.family)));
+    }
     // The handshake covers process spawn plus the adapter's first write, which
     // can be slow under load; it gets a generous timeout independent of the
     // per-case timeout so a busy machine never mistakes startup for a hang.
@@ -171,6 +179,7 @@ export async function runConformance(options) {
     let hello;
     try {
         hello = await connection.handshake(handshakeTimeoutMs, hostModelFamilies);
+        assertExpectedFamilies(hello.families, options.expectedFamilies);
     }
     catch (error) {
         connection.kill();
@@ -228,6 +237,7 @@ export async function runConformance(options) {
         connection = new AdapterConnection(options.adapterCommand);
         try {
             hello = await connection.handshake(handshakeTimeoutMs, hostModelFamilies);
+            assertExpectedFamilies(hello.families, options.expectedFamilies);
         }
         catch {
             // A replacement that cannot even complete a handshake ends the run

package/fixtures/README.md

@@ -0,0 +1,48 @@
+# Conformance fixture update runbook
+
+This directory is the language-neutral conformance source of truth. A fixture
+change is a protocol change, not an implementation-specific test edit.
+
+## Before editing
+
+1. Identify the RFC and extension version that owns the behavior. Accepted
+   grammar, limits, comparison rules, or canonical bytes cannot be changed in
+   place; introduce a new extension version when the RFC requires one.
+2. Decide whether the case is a success, rejection, identity, portability, or
+   deterministic fuzz case. Rejection cases must use the stable code owned by
+   their manifest family.
+3. Keep fixture IDs unique and inputs deterministic. Never put credentials,
+   customer data, nondeterministic timestamps, or host-specific paths in the
+   corpus.
+
+## Update workflow
+
+1. Edit the owning family files and its README. Add new files or fuzz targets
+   to `manifest.json`; do not bypass the manifest.
+2. Update the TypeScript reference implementation and every implementation
+   that already announces the family. A family may be implemented in a later
+   stacked PR, but no release gate may silently drop an announced family.
+3. When an adapter gains a family, update its exact `--expect-families` list in
+   the same PR. For Python, that list is owned by `conformance:python` in the
+   root `package.json`.
+4. Add a Changeset whenever the bundled `@hypequery/protocol-conformance`
+   fixture snapshot or runner behavior changes.
+5. Rebuild the conformance package after fixture edits; its build copies the
+   current corpus into the published package.
+
+## Verification
+
+From the repository root:
+
+```console
+pnpm --filter @hypequery/protocol build
+pnpm --filter @hypequery/datasets build
+pnpm --filter @hypequery/protocol-conformance build
+pnpm --filter @hypequery/protocol-conformance test
+pnpm conformance
+uv run --project python/hypequery --frozen pytest
+```
+
+Review the report's implementation, announced families, hostile-object suite,
+and not-run count—not only its exit status. CI release gates must use an exact
+family assertion for partial adapters.

package/fixtures/fuzz-seeds-v1/README.md

@@ -3,6 +3,8 @@
 These adversarial inputs replay on every conformance run under RFC 0012. An implementation may accept a seed within documented limits or reject it with a stable `HQ_*` code; it must never crash, hang, partially execute input, or allocate without bounds.
 
 - `value-sources.json` targets duplicate-aware JSON decoding and tagged values.
+- `identifiers.json` targets Unicode ambiguity, reserved names, separators,
+  validation limits, and non-string identifier inputs.
 - `structured-values.json` targets selected structural validator families.
 - `sql-expressions.json` targets the SQL portability compiler.
 

package/fixtures/fuzz-seeds-v1/identifiers.json

@@ -0,0 +1,17 @@
+[
+  { "id": "identifier-null", "mode": "simple", "value": null },
+  { "id": "identifier-control-character", "mode": "simple", "value": "order\u0000id" },
+  { "id": "identifier-sql-shaped", "mode": "simple", "value": "orders;DROP_TABLE_users" },
+  { "id": "identifier-cyrillic-confusable", "mode": "simple", "value": "аdmin" },
+  { "id": "identifier-combining-mark", "mode": "simple", "value": "café" },
+  { "id": "identifier-fullwidth-dot", "mode": "qualified", "value": "orders．customer" },
+  { "id": "identifier-lone-high-surrogate", "mode": "simple", "value": "\ud800" },
+  { "id": "identifier-lone-low-surrogate", "mode": "simple", "value": "\udc00" },
+  { "id": "identifier-surrogate-pair", "mode": "simple", "value": "\ud83d\ude00" },
+  { "id": "identifier-reserved-mixed-case", "mode": "simple", "value": "__HyPeQuErY_admin" },
+  { "id": "identifier-qualified-leading-dot", "mode": "qualified", "value": ".orders" },
+  { "id": "identifier-qualified-trailing-dot", "mode": "qualified", "value": "orders." },
+  { "id": "identifier-qualified-repeated-dot", "mode": "qualified", "value": "orders..customer" },
+  { "id": "identifier-long-segment", "mode": "simple", "generator": { "type": "repeat-string", "value": "a", "count": 10000 } },
+  { "id": "identifier-many-segments", "mode": "qualified", "generator": { "type": "qualified-segments", "segment": "a", "count": 1000 } }
+]

package/fixtures/manifest.json

@@ -228,6 +228,10 @@
       "path": "fuzz-seeds-v1/value-sources.json",
       "family": "tagged-values-v1"
     },
+    {
+      "path": "fuzz-seeds-v1/identifiers.json",
+      "family": "identifiers-v1"
+    },
     {
       "path": "fuzz-seeds-v1/structured-values.json"
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/protocol-conformance",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "description": "Cross-language conformance runner for the Hypequery analytics security protocol",
   "keywords": [
     "hypequery",