@hypequery/protocol-conformance 0.0.0-canary-20260722115402

package/dist/adapters/reference.js

@@ -0,0 +1,172 @@
+// The TypeScript reference adapter. Maps each family/role/case to the public
+// root export of @hypequery/protocol and returns a wire result. Every operation
+// goes through the package's supported surface — this is exactly what a second
+// implementation must reproduce.
+import { decodeCanonicalValue, encodeCanonicalValue, hashCanonicalValue, parseProtocolIdentifier, parseProtocolQualifiedIdentifier, prepareProtocolDeploymentBundleManifest, prepareProtocolDeploymentContract, prepareProtocolDeploymentReleaseEnvelope, splitProtocolQualifiedIdentifier, validateCanonicalValue, validateProtocolDeploymentBundleManifest, validateProtocolDeploymentContract, validateProtocolDeploymentReleaseEnvelope, validateProtocolExpression, validateProtocolQueryDiagnostics, validateProtocolQueryEvent, validateProtocolQueryImplementation, validateProtocolSchema, validateProtocolSemanticQuery, validateProtocolSqlExpression, } from '@hypequery/protocol';
+import { materializeBundle, materializeDeployment, materializeDiagnostics, materializeEvent, materializeExpression, materializeIdentifier, materializeImplementation, materializeRelease, materializeSchema, materializeTaggedValue, } from './generators.js';
+const STABLE_CODE = /^HQ_[A-Z0-9_]+$/;
+/** Turns a thrown protocol error into a wire rejection; rethrows anything else. */
+function mapError(error) {
+    const code = error?.code;
+    if (typeof code === 'string' && STABLE_CODE.test(code))
+        return { ok: false, code };
+    throw error;
+}
+function attempt(fn) {
+    try {
+        return fn();
+    }
+    catch (error) {
+        return mapError(error);
+    }
+}
+const ACCEPT = { ok: true };
+/** The input a validation case feeds to its validator. */
+function validationInput(c, materialize) {
+    return c.generator ? materialize(c.generator) : c.value;
+}
+export const REFERENCE_FAMILIES = [
+    'tagged-values-v1',
+    'identifiers-v1',
+    'expressions-v1',
+    'query-schemas-v1',
+    'query-implementations-v1',
+    'query-events-v1',
+    'query-diagnostics-v1',
+    'deployments-v1',
+    'deployment-bundles-v1',
+    'deployment-releases-v1',
+];
+export function referenceHandle(family, role, c, section) {
+    switch (family) {
+        case 'tagged-values-v1':
+            return handleTaggedValue(role, c);
+        case 'identifiers-v1':
+            return handleIdentifier(role, c);
+        case 'expressions-v1':
+            return handleExpression(role, c, section);
+        case 'query-schemas-v1':
+            return attempt(() => {
+                validateProtocolSchema(validationInput(c, materializeSchema));
+                return ACCEPT;
+            });
+        case 'query-implementations-v1':
+            return handleImplementation(c);
+        case 'query-events-v1':
+            return attempt(() => {
+                validateProtocolQueryEvent(validationInput(c, materializeEvent));
+                return ACCEPT;
+            });
+        case 'query-diagnostics-v1':
+            return attempt(() => {
+                validateProtocolQueryDiagnostics(validationInput(c, materializeDiagnostics));
+                return ACCEPT;
+            });
+        case 'deployments-v1':
+            return handleDeployment(role, c);
+        case 'deployment-bundles-v1':
+            return handleBundle(role, c);
+        case 'deployment-releases-v1':
+            return handleRelease(role, c);
+        default:
+            throw new Error(`reference adapter does not support family ${family}`);
+    }
+}
+function handleTaggedValue(role, c) {
+    if (role === 'success') {
+        return attempt(() => ({
+            ok: true,
+            output: {
+                canonicalHex: Buffer.from(encodeCanonicalValue(c.value)).toString('hex'),
+                sha256: hashCanonicalValue(c.value),
+            },
+        }));
+    }
+    return attempt(() => {
+        if (c.sourceUtf8 !== undefined) {
+            decodeCanonicalValue(c.sourceUtf8);
+            return ACCEPT;
+        }
+        const input = c.generator ? materializeTaggedValue(c.generator) : c.value;
+        validateCanonicalValue(input, { declaredClickHouseType: c.declaredClickHouseType });
+        return ACCEPT;
+    });
+}
+function handleIdentifier(role, c) {
+    const simple = c.mode === 'simple';
+    if (role === 'success') {
+        return attempt(() => {
+            const segments = simple
+                ? [parseProtocolIdentifier(c.value)]
+                : splitProtocolQualifiedIdentifier(parseProtocolQualifiedIdentifier(c.value));
+            return { ok: true, output: { segments } };
+        });
+    }
+    return attempt(() => {
+        const input = c.generator ? materializeIdentifier(c.generator) : c.value;
+        if (simple)
+            parseProtocolIdentifier(input);
+        else
+            parseProtocolQualifiedIdentifier(input);
+        return ACCEPT;
+    });
+}
+function handleExpression(role, c, section) {
+    const isQuery = section === '/queries' || c.mode === 'query';
+    const validate = isQuery ? validateProtocolSemanticQuery : validateProtocolExpression;
+    if (role === 'success') {
+        return attempt(() => {
+            validate(c.value);
+            return ACCEPT;
+        });
+    }
+    return attempt(() => {
+        validate(validationInput(c, materializeExpression));
+        return ACCEPT;
+    });
+}
+function handleImplementation(c) {
+    const validate = c.surface === 'sql-expression'
+        ? validateProtocolSqlExpression
+        : validateProtocolQueryImplementation;
+    return attempt(() => {
+        validate(validationInput(c, materializeImplementation));
+        return ACCEPT;
+    });
+}
+function handleDeployment(role, c) {
+    if (role === 'identity') {
+        return attempt(() => {
+            const prepared = prepareProtocolDeploymentContract(c.value);
+            return { ok: true, output: { canonical: prepared.canonical, sha256: prepared.identity } };
+        });
+    }
+    return attempt(() => {
+        validateProtocolDeploymentContract(validationInput(c, materializeDeployment));
+        return ACCEPT;
+    });
+}
+function handleBundle(role, c) {
+    if (role === 'identity') {
+        return attempt(() => {
+            const prepared = prepareProtocolDeploymentBundleManifest(c.value);
+            return { ok: true, output: { canonical: prepared.canonical, sha256: prepared.identity } };
+        });
+    }
+    return attempt(() => {
+        validateProtocolDeploymentBundleManifest(validationInput(c, materializeBundle));
+        return ACCEPT;
+    });
+}
+function handleRelease(role, c) {
+    if (role === 'identity') {
+        return attempt(() => {
+            const prepared = prepareProtocolDeploymentReleaseEnvelope(c.value);
+            return { ok: true, output: { canonical: prepared.canonical, sha256: prepared.identity } };
+        });
+    }
+    return attempt(() => {
+        validateProtocolDeploymentReleaseEnvelope(validationInput(c, materializeRelease));
+        return ACCEPT;
+    });
+}

package/dist/adapters/stdio.d.ts

@@ -0,0 +1,17 @@
+import type { FixtureRole, HandlerResult } from '../types.js';
+export interface StdioAdapterOptions {
+    readonly implementation?: string;
+    readonly version?: string;
+    readonly language?: string;
+    readonly families: readonly string[];
+    readonly handle: (family: string, role: FixtureRole, fixtureCase: Record<string, unknown>, section: string | undefined) => HandlerResult | Promise<HandlerResult>;
+    /** Streams default to the process stdio; overridable for tests. */
+    readonly input?: NodeJS.ReadableStream;
+    readonly output?: NodeJS.WritableStream;
+}
+/**
+ * Runs the adapter loop until the runner sends `end` or the input closes.
+ * Resolves with the process exit code the caller should use.
+ */
+export declare function createStdioAdapter(options: StdioAdapterOptions): Promise<number>;
+//# sourceMappingURL=stdio.d.ts.map

package/dist/adapters/stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../../src/adapters/stdio.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE9D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,CACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,WAAW,EACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,OAAO,EAAE,MAAM,GAAG,SAAS,KACxB,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5C,mEAAmE;IACnE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6EhF"}

package/dist/adapters/stdio.js

@@ -0,0 +1,80 @@
+// Reusable NDJSON adapter loop. An adapter wraps an implementation under test:
+// it announces the families it supports, then answers one result line per case
+// the runner sends. Used by the reference adapter and the datasets adapter.
+import { createInterface } from 'node:readline';
+import { CONFORMANCE_PROTOCOL_VERSION } from '../types.js';
+/**
+ * Runs the adapter loop until the runner sends `end` or the input closes.
+ * Resolves with the process exit code the caller should use.
+ */
+export function createStdioAdapter(options) {
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stdout;
+    const families = [...options.families];
+    const write = (message) => {
+        output.write(`${JSON.stringify(message)}\n`);
+    };
+    return new Promise((resolve) => {
+        const rl = createInterface({ input, crlfDelay: Infinity });
+        // Serializes async handlers so results are emitted in the order received.
+        let chain = Promise.resolve();
+        let exitCode = 0;
+        const finish = () => {
+            rl.close();
+            resolve(exitCode);
+        };
+        rl.on('line', (line) => {
+            const trimmed = line.trim();
+            if (trimmed === '')
+                return;
+            let message;
+            try {
+                message = JSON.parse(trimmed);
+            }
+            catch {
+                process.stderr.write(`adapter: unparseable line\n`);
+                exitCode = 2;
+                finish();
+                return;
+            }
+            if (message.type === 'hello') {
+                if (message.protocol !== CONFORMANCE_PROTOCOL_VERSION) {
+                    process.stderr.write(`adapter: unsupported protocol ${String(message.protocol)}\n`);
+                    exitCode = 2;
+                    finish();
+                    return;
+                }
+                write({
+                    type: 'hello',
+                    protocol: CONFORMANCE_PROTOCOL_VERSION,
+                    implementation: options.implementation,
+                    version: options.version,
+                    language: options.language,
+                    families,
+                });
+                return;
+            }
+            if (message.type === 'end') {
+                chain = chain.then(finish);
+                return;
+            }
+            if (message.type === 'case') {
+                const seq = message.seq;
+                const family = message.family;
+                const role = message.role;
+                const fixtureCase = message.case;
+                const section = message.section;
+                chain = chain.then(async () => {
+                    const result = await options.handle(family, role, fixtureCase, section);
+                    write({ type: 'result', seq, ...result });
+                });
+                return;
+            }
+            process.stderr.write(`adapter: unknown message type ${String(message.type)}\n`);
+        });
+        input.on('error', () => {
+            exitCode = 2;
+            finish();
+        });
+    });
+}

package/dist/bin/conformance.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=conformance.d.ts.map

package/dist/bin/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../src/bin/conformance.ts"],"names":[],"mappings":""}

package/dist/bin/conformance.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// Conformance runner CLI.
+//
+//   hypequery-protocol-conformance run [options] -- <adapter command...>
+//   hypequery-protocol-conformance list [--fixtures <dir>]
+//
+// Everything after `--` is the adapter argv, spawned without a shell.
+import { createJsonLoader, loadManifest, resolveFixturesDir } from '../fs.js';
+import { enumerateAllCases } from '../manifest.js';
+import { formatJsonReport, formatPrettyReport } from '../report.js';
+import { runConformance } from '../runner.js';
+function parseArgs(argv) {
+    const separator = argv.indexOf('--');
+    const head = separator === -1 ? argv : argv.slice(0, separator);
+    const adapterCommand = separator === -1 ? [] : argv.slice(separator + 1);
+    const command = head[0] && !head[0].startsWith('--') ? head[0] : undefined;
+    const options = {};
+    for (let i = command ? 1 : 0; i < head.length; i += 1) {
+        const token = head[i];
+        if (!token.startsWith('--'))
+            continue;
+        const key = token.slice(2);
+        const next = head[i + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+            options[key] = next;
+            i += 1;
+        }
+        else {
+            options[key] = true;
+        }
+    }
+    return { command, options, adapterCommand };
+}
+async function main() {
+    const { command, options, adapterCommand } = parseArgs(process.argv.slice(2));
+    const fixturesDir = typeof options.fixtures === 'string' ? options.fixtures : undefined;
+    if (command === 'list') {
+        const dir = resolveFixturesDir(fixturesDir);
+        const manifest = loadManifest(dir);
+        const cases = enumerateAllCases(manifest, createJsonLoader(dir));
+        const counts = new Map();
+        for (const c of cases)
+            counts.set(c.family, (counts.get(c.family) ?? 0) + 1);
+        for (const [family, count] of counts)
+            process.stdout.write(`${family}\t${count}\n`);
+        process.stdout.write(`total\t${cases.length}\n`);
+        return 0;
+    }
+    if (command !== 'run') {
+        process.stderr.write('usage: hypequery-protocol-conformance run [options] -- <adapter command...>\n');
+        return 2;
+    }
+    if (adapterCommand.length === 0) {
+        process.stderr.write('error: no adapter command given after `--`\n');
+        return 2;
+    }
+    const families = typeof options.families === 'string'
+        ? options.families.split(',').map((f) => f.trim()).filter(Boolean)
+        : undefined;
+    let summary;
+    try {
+        summary = await runConformance({
+            adapterCommand,
+            fixturesDir,
+            families,
+            timeoutMs: typeof options['timeout-ms'] === 'string' ? Number(options['timeout-ms']) : undefined,
+            skipFuzz: options['skip-fuzz'] === true,
+            onlyFuzz: options['only-fuzz'] === true,
+        });
+    }
+    catch (error) {
+        process.stderr.write(`conformance run failed: ${String(error)}\n`);
+        return 2;
+    }
+    const report = options.report === 'json' ? formatJsonReport(summary) : formatPrettyReport(summary);
+    process.stdout.write(`${report}\n`);
+    return summary.failed > 0 ? 1 : 0;
+}
+main()
+    .then((code) => process.exit(code))
+    .catch((error) => {
+    process.stderr.write(`${String(error)}\n`);
+    process.exit(2);
+});

package/dist/bin/reference-adapter.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=reference-adapter.d.ts.map

package/dist/bin/reference-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-adapter.d.ts","sourceRoot":"","sources":["../../src/bin/reference-adapter.ts"],"names":[],"mappings":""}

package/dist/bin/reference-adapter.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Reference adapter executable. Wraps @hypequery/protocol behind the RFC 0012
+// stdio protocol so the runner can drive it like any other implementation.
+import { createStdioAdapter } from '../adapters/stdio.js';
+import { REFERENCE_FAMILIES, referenceHandle } from '../adapters/reference.js';
+createStdioAdapter({
+    implementation: '@hypequery/protocol',
+    language: 'typescript',
+    families: [...REFERENCE_FAMILIES],
+    handle: referenceHandle,
+})
+    .then((code) => process.exit(code))
+    .catch((error) => {
+    process.stderr.write(`${String(error)}\n`);
+    process.exit(1);
+});

package/dist/compare.d.ts

@@ -0,0 +1,3 @@
+import type { CaseOutcome, EnumeratedCase, HandlerResult } from './types.js';
+export declare function compareCase(ec: EnumeratedCase, result: HandlerResult): CaseOutcome;
+//# sourceMappingURL=compare.d.ts.map

package/dist/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../src/compare.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAwC7E,wBAAgB,WAAW,CAAC,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,aAAa,GAAG,WAAW,CA2ElF"}

package/dist/compare.js

@@ -0,0 +1,125 @@
+const STABLE_CODE = /^HQ_[A-Z0-9_]+$/;
+/** Order-insensitive structural equality via canonical JSON. */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value) ?? 'null';
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    const object = value;
+    return `{${Object.keys(object)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableStringify(object[key])}`)
+        .join(',')}}`;
+}
+function deepEqual(a, b) {
+    return stableStringify(a) === stableStringify(b);
+}
+function outcome(ec, status, extra = {}) {
+    return { family: ec.family, role: ec.role, id: ec.id, status, ...extra };
+}
+function isUnsafeAccessorCase(ec) {
+    const generator = ec.case.generator;
+    return generator?.type === 'unsafe-accessor';
+}
+function output(result) {
+    return ('output' in result && result.output ? result.output : {});
+}
+export function compareCase(ec, result) {
+    if ('skipped' in result) {
+        // A skip is only legitimate for the host-model-conditional accessor case.
+        if (ec.role === 'rejection' && isUnsafeAccessorCase(ec)) {
+            return outcome(ec, 'skip', { message: result.reason });
+        }
+        return outcome(ec, 'fail', {
+            expected: 'a result',
+            actual: 'skipped',
+            message: result.reason ?? 'case may not be skipped',
+        });
+    }
+    const ok = result.ok === true;
+    const code = result.ok === false ? result.code : undefined;
+    switch (ec.role) {
+        case 'success': {
+            if (!ok)
+                return outcome(ec, 'fail', { expected: 'accepted', actual: code });
+            return compareSuccessOutput(ec, output(result));
+        }
+        case 'identity': {
+            if (!ok)
+                return outcome(ec, 'fail', { expected: 'accepted', actual: code });
+            const o = output(result);
+            if (o.canonical !== ec.case.canonical) {
+                return outcome(ec, 'fail', { expected: 'canonical bytes', actual: 'mismatch' });
+            }
+            if (o.sha256 !== ec.case.sha256) {
+                return outcome(ec, 'fail', { expected: String(ec.case.sha256), actual: String(o.sha256) });
+            }
+            return outcome(ec, 'pass');
+        }
+        case 'portable': {
+            if (!ok)
+                return outcome(ec, 'fail', { expected: 'portable', actual: code });
+            const o = output(result);
+            if (!deepEqual(o.expression, ec.case.expression)) {
+                return outcome(ec, 'fail', { expected: 'expression AST', actual: 'mismatch' });
+            }
+            if (!deepEqual(o.dependencies, ec.case.dependencies)) {
+                return outcome(ec, 'fail', { expected: 'dependencies', actual: 'mismatch' });
+            }
+            return outcome(ec, 'pass');
+        }
+        case 'rejection': {
+            if (ok)
+                return outcome(ec, 'fail', { expected: String(ec.case.error), actual: 'accepted' });
+            if (code !== ec.case.error) {
+                return outcome(ec, 'fail', { expected: String(ec.case.error), actual: String(code) });
+            }
+            return outcome(ec, 'pass');
+        }
+        case 'non-portable': {
+            if (ok)
+                return outcome(ec, 'fail', { expected: String(ec.case.code), actual: 'accepted' });
+            if (code !== ec.case.code) {
+                return outcome(ec, 'fail', { expected: String(ec.case.code), actual: String(code) });
+            }
+            const o = output(result);
+            if (o.start !== ec.case.start) {
+                return outcome(ec, 'fail', {
+                    expected: `start ${String(ec.case.start)}`,
+                    actual: `start ${String(o.start)}`,
+                });
+            }
+            return outcome(ec, 'pass');
+        }
+        case 'fuzz': {
+            if (ok)
+                return outcome(ec, 'pass');
+            if (code !== undefined && STABLE_CODE.test(code))
+                return outcome(ec, 'pass');
+            return outcome(ec, 'fail', {
+                expected: 'accept or HQ_ code',
+                actual: code ?? 'malformed result',
+            });
+        }
+        default:
+            return outcome(ec, 'fail', { message: `unknown role ${ec.role}` });
+    }
+}
+function compareSuccessOutput(ec, o) {
+    if (ec.family === 'tagged-values-v1') {
+        if (o.canonicalHex !== ec.case.canonicalHex) {
+            return outcome(ec, 'fail', { expected: 'canonicalHex', actual: 'mismatch' });
+        }
+        if (o.sha256 !== ec.case.sha256) {
+            return outcome(ec, 'fail', { expected: String(ec.case.sha256), actual: String(o.sha256) });
+        }
+    }
+    if (ec.family === 'identifiers-v1') {
+        if (!deepEqual(o.segments, ec.case.segments)) {
+            return outcome(ec, 'fail', { expected: 'segments', actual: 'mismatch' });
+        }
+    }
+    return outcome(ec, 'pass');
+}

package/dist/fs.d.ts

@@ -0,0 +1,11 @@
+import type { ConformanceManifest } from './types.js';
+import type { JsonLoader } from './manifest.js';
+/**
+ * Resolves the fixtures directory. When no explicit directory is given, prefer
+ * the snapshot bundled with a published build (`../fixtures`), then fall back
+ * to the in-repo source of truth so tests and local runs work without a build.
+ */
+export declare function resolveFixturesDir(explicit?: string): string;
+export declare function createJsonLoader(fixturesDir: string): JsonLoader;
+export declare function loadManifest(fixturesDir: string): ConformanceManifest;
+//# sourceMappingURL=fs.d.ts.map

package/dist/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAU5D;AAOD,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,CAKhE;AAED,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,mBAAmB,CAQrE"}

package/dist/fs.js

@@ -0,0 +1,36 @@
+// The only module that touches the filesystem. Everything else operates on
+// values injected from here, per Decision 0001's separation of pure contract
+// logic from I/O.
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+/**
+ * Resolves the fixtures directory. When no explicit directory is given, prefer
+ * the snapshot bundled with a published build (`../fixtures`), then fall back
+ * to the in-repo source of truth so tests and local runs work without a build.
+ */
+export function resolveFixturesDir(explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    const bundled = fileURLToPath(new URL('../fixtures/', import.meta.url));
+    if (existsSync(new URL('../fixtures/manifest.json', import.meta.url))) {
+        return bundled;
+    }
+    return fileURLToPath(new URL('../../../specs/security-protocol/fixtures/', import.meta.url));
+}
+function joinFixturePath(fixturesDir, relativePath) {
+    const base = fixturesDir.endsWith('/') ? fixturesDir : `${fixturesDir}/`;
+    return `${base}${relativePath}`;
+}
+export function createJsonLoader(fixturesDir) {
+    return (relativePath) => {
+        const path = joinFixturePath(fixturesDir, relativePath);
+        return JSON.parse(readFileSync(path, 'utf8'));
+    };
+}
+export function loadManifest(fixturesDir) {
+    const manifest = JSON.parse(readFileSync(joinFixturePath(fixturesDir, 'manifest.json'), 'utf8'));
+    if (manifest.kind !== 'hypequery-conformance-manifest') {
+        throw new Error('manifest.json is not a hypequery conformance manifest');
+    }
+    return manifest;
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { runConformance } from './runner.js';
+export type { RunConformanceOptions } from './runner.js';
+export { loadManifest, resolveFixturesDir, createJsonLoader } from './fs.js';
+export { enumerateAllCases, enumerateFamilyCases, enumerateFuzzCases, resolveJsonPointer, } from './manifest.js';
+export type { JsonLoader } from './manifest.js';
+export { compareCase } from './compare.js';
+export { formatPrettyReport, formatJsonReport } from './report.js';
+export { createStdioAdapter } from './adapters/stdio.js';
+export { referenceHandle, REFERENCE_FAMILIES } from './adapters/reference.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC9E,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+// Public API for the conformance runner and TypeScript reference adapter.
+export { runConformance } from './runner.js';
+export { loadManifest, resolveFixturesDir, createJsonLoader } from './fs.js';
+export { enumerateAllCases, enumerateFamilyCases, enumerateFuzzCases, resolveJsonPointer, } from './manifest.js';
+export { compareCase } from './compare.js';
+export { formatPrettyReport, formatJsonReport } from './report.js';
+export { createStdioAdapter } from './adapters/stdio.js';
+export { referenceHandle, REFERENCE_FAMILIES } from './adapters/reference.js';
+export * from './types.js';

package/dist/manifest.d.ts

@@ -0,0 +1,13 @@
+import type { ConformanceManifest, EnumeratedCase } from './types.js';
+export type JsonLoader = (relativePath: string) => unknown;
+/** Minimal RFC 6901 JSON pointer resolution for the section selectors. */
+export declare function resolveJsonPointer(root: unknown, pointer: string): unknown;
+/** Cases derived from the family fixture files, in manifest order. */
+export declare function enumerateFamilyCases(manifest: ConformanceManifest, loadJson: JsonLoader): EnumeratedCase[];
+/**
+ * Cases derived from the fuzz corpus. A seed with its own `targets` fans out
+ * to one case per target family; otherwise it uses the manifest entry family.
+ */
+export declare function enumerateFuzzCases(manifest: ConformanceManifest, loadJson: JsonLoader): EnumeratedCase[];
+export declare function enumerateAllCases(manifest: ConformanceManifest, loadJson: JsonLoader): EnumeratedCase[];
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EAGf,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,UAAU,GAAG,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC;AAM3D,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAiB1E;AAgDD,sEAAsE;AACtE,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,mBAAmB,EAC7B,QAAQ,EAAE,UAAU,GACnB,cAAc,EAAE,CAmBlB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,mBAAmB,EAC7B,QAAQ,EAAE,UAAU,GACnB,cAAc,EAAE,CA0BlB;AAED,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,mBAAmB,EAC7B,QAAQ,EAAE,UAAU,GACnB,cAAc,EAAE,CAElB"}