@dynamicalsystems/idl-conformance 0.6.1

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@dynamicalsystems/idl-conformance",
+  "version": "0.6.1",
+  "description": "Conformance vectors and runner for the DSG wire profiles. A consumer implements the adapter over its real boundary parser and replays every vector; a counterpart fake is built from accept vectors, never written by hand.",
+  "homepage": "https://github.com/DynamicalSystemsGroup/dsg-idl#readme",
+  "bugs": "https://github.com/DynamicalSystemsGroup/dsg-idl/issues",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DynamicalSystemsGroup/dsg-idl.git",
+    "directory": "packages/idl-conformance"
+  },
+  "files": [
+    "dist",
+    "src",
+    "assets",
+    "checklist.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dynamicalsystems/orn-schemas": "0.1.0",
+    "@dynamicalsystems/idl": "0.6.1"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "oxfmt": "0.64.0",
+    "oxlint": "1.79.0",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check-types": "tsc --noEmit",
+    "lint": "oxlint --config ../../.oxlintrc.json --type-aware .",
+    "format:check": "oxfmt --check .",
+    "test": "vitest run"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,32 @@
+// The interface a consumer implements over its real boundary parser: the
+// function that reads bytes off the wire, not the schema object. One parse
+// function per shape position, addressed "<profile literal>#<shape>", so a
+// vector exercises the exact code path that runs in production.
+export type ParseResult =
+  | { readonly ok: true; readonly digest?: string }
+  | { readonly ok: false; readonly reason: string };
+
+export type Adapter = Readonly<Record<string, (bytes: Uint8Array) => ParseResult>>;
+
+/** One vector file on disk. `bytes` is base64 of the exact wire bytes:
+ * re-serialization would normalize away the malformations reject vectors
+ * exist to carry. A reject names the one rule it breaks. */
+export type Vector = {
+  readonly profile: string;
+  readonly shape: string;
+  readonly name: string;
+  readonly verdict: "accept" | "reject";
+  readonly rule?: string;
+  readonly bytes: string;
+  /** Digest vectors only: the expected sha256 of the canonical form of the
+   * document in `bytes`. The vector bytes are deliberately NON-canonical
+   * (different key order, whitespace), so agreement proves the consumer's
+   * own canonicalize-and-digest path, not a byte copy. */
+  readonly sha256?: string;
+  /** What agreeing on this vector obliges. "shape" (default): the boundary
+   * parser's structural verdict. "semantic": a validator beyond shape
+   * (law_contract.py, Rego decisions) must agree; shape-only adapters skip
+   * these. Passing a finite corpus establishes agreement on those cases,
+   * never equivalence. */
+  readonly obligation?: "shape" | "semantic";
+};

package/src/cli.ts

@@ -0,0 +1,19 @@
+// Runs every committed vector through the reference adapter. Exit 0 only
+// when every vector agrees with the schemas. CI for this repo; consumers
+// run the same runner with their own adapter instead.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { referenceAdapter } from "./reference-adapter.js";
+import { runVectors } from "./runner.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = join(here, "..");
+const checklist = JSON.parse(readFileSync(join(root, "checklist.json"), "utf8"));
+const report = runVectors(referenceAdapter(), join(root, "assets", "vectors"), checklist);
+
+for (const verdict of report.verdicts) {
+  if (verdict.outcome === "fail") console.error(`FAIL ${verdict.id}: ${verdict.detail}`);
+}
+console.log(JSON.stringify({ passed: report.passed, failed: report.failed }));
+process.exit(report.failed === 0 ? 0 : 1);

package/src/index.ts

@@ -0,0 +1,4 @@
+export type { Adapter, ParseResult, Vector } from "./adapter.js";
+export { runVectors } from "./runner.js";
+export type { RunReport, VectorVerdict } from "./runner.js";
+export { referenceAdapter } from "./reference-adapter.js";

package/src/reference-adapter.ts

@@ -0,0 +1,42 @@
+// The adapter the package itself is judged by: TypeBox Value.Check over
+// the registered schemas. Consumers implement their own adapter over their
+// real parser; this one exists so a profile PR proves its vectors against
+// the schemas before any consumer sees them.
+import { createHash } from "node:crypto";
+import { Value } from "@sinclair/typebox/value";
+import { jcsStringify } from "@dynamicalsystems/orn-schemas";
+import { PROFILES } from "@dynamicalsystems/idl";
+import type { Adapter, ParseResult } from "./adapter.js";
+
+export function referenceAdapter(): Adapter {
+  const adapter: Record<string, (bytes: Uint8Array) => ParseResult> = {};
+  for (const entry of Object.values(PROFILES)) {
+    adapter[`${entry.literal}#digest.envelope`] = (bytes) => {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+      } catch (error) {
+        return { ok: false, reason: `not UTF-8 JSON: ${String(error)}` };
+      }
+      const digest = createHash("sha256").update(jcsStringify(parsed)).digest("hex");
+      return { ok: true, digest };
+    };
+    for (const [shapeName, shape] of Object.entries(entry.shapes)) {
+      adapter[`${entry.literal}#${shapeName}`] = (bytes) => {
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        } catch (error) {
+          return { ok: false, reason: `not UTF-8 JSON: ${String(error)}` };
+        }
+        if (Value.Check(shape, parsed)) return { ok: true };
+        const first = Value.Errors(shape, parsed).First();
+        return {
+          ok: false,
+          reason: `${first?.path ?? ""}: ${first?.message ?? "schema mismatch"}`,
+        };
+      };
+    }
+  }
+  return adapter;
+}

package/src/runner.ts

@@ -0,0 +1,89 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { Adapter, Vector } from "./adapter.js";
+
+export type VectorVerdict = {
+  readonly id: string;
+  readonly expected: "accept" | "reject";
+  readonly outcome: "pass" | "fail";
+  readonly detail: string;
+};
+
+export type RunReport = {
+  readonly passed: number;
+  readonly failed: number;
+  readonly verdicts: readonly VectorVerdict[];
+};
+
+type Checklist = { readonly profiles: Readonly<Record<string, number>> };
+
+/** Runs every vector under `assetsDir` through the adapter. The checklist
+ * is the coverage floor: a profile listed there with fewer vectors on disk
+ * than promised fails the run, so a silently deleted directory cannot pass. */
+export function runVectors(adapter: Adapter, assetsDir: string, checklist: Checklist): RunReport {
+  const verdicts: VectorVerdict[] = [];
+
+  for (const [profile, expectedCount] of Object.entries(checklist.profiles)) {
+    const dir = join(assetsDir, profile.replaceAll("/", "_"));
+    let files: string[] = [];
+    for (const verdict of ["accept", "reject", "digest"] as const) {
+      let names: string[] = [];
+      try {
+        names = readdirSync(join(dir, verdict)).filter((f) => f.endsWith(".json"));
+      } catch {
+        names = [];
+      }
+      files = files.concat(names.map((n) => join(dir, verdict, n)));
+    }
+
+    if (files.length < expectedCount) {
+      verdicts.push({
+        id: profile,
+        expected: "accept",
+        outcome: "fail",
+        detail: `checklist promises ${expectedCount} vectors, found ${files.length}`,
+      });
+      continue;
+    }
+
+    for (const file of files) {
+      const vector = JSON.parse(readFileSync(file, "utf8")) as Vector;
+      const isDigest = file.includes("/digest/");
+      const key = isDigest
+        ? `${vector.profile}#digest.${vector.shape}`
+        : `${vector.profile}#${vector.shape}`;
+      const parse = adapter[key];
+      if (parse === undefined && vector.obligation === "semantic") continue;
+      if (parse === undefined) {
+        verdicts.push({
+          id: `${key}/${vector.name}`,
+          expected: vector.verdict,
+          outcome: "fail",
+          detail: "adapter has no parser for this shape",
+        });
+        continue;
+      }
+      const result = parse(Buffer.from(vector.bytes, "base64"));
+      const agreed = isDigest
+        ? result.ok && result.digest === vector.sha256
+        : result.ok === (vector.verdict === "accept");
+      verdicts.push({
+        id: `${vector.profile}#${vector.shape}/${vector.name}`,
+        expected: vector.verdict,
+        outcome: agreed ? "pass" : "fail",
+        detail: agreed
+          ? (vector.rule ?? "")
+          : isDigest
+            ? result.ok
+              ? `digest mismatch: computed ${result.digest ?? "nothing"}, vector pins ${vector.sha256 ?? "nothing"}`
+              : `could not digest: ${result.reason}`
+            : result.ok
+              ? `accepted but must reject: ${vector.rule ?? "unnamed rule"}`
+              : `rejected but must accept: ${result.reason}`,
+      });
+    }
+  }
+
+  const failed = verdicts.filter((v) => v.outcome === "fail").length;
+  return { passed: verdicts.length - failed, failed, verdicts };
+}