@supawatch/verify 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omar Dulaimi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/fixture.d.ts

@@ -0,0 +1,3 @@
+import { type Snapshot } from "@supawatch/core";
+export declare const FIXTURE_SQL = "\ncreate type parcel_state as enum ('queued', 'shipped', 'lost');\ncreate type dimensions as (width_mm int4, height_mm int4);\ncreate domain tracking_code as text;\ncreate domain weight_grams as int4;\n\ncreate table parcels (\n  size dimensions,\n  tracking tracking_code not null default 'T-1',\n  weight weight_grams not null default 250,\n  id serial primary key,\n  small int2 not null default 1,\n  big int8 not null default 9007199254740993,\n  ratio float4 not null default 0.5,\n  wide float8 not null default 2.25,\n  price numeric(10,2) not null default 19.99,\n  ref uuid not null default gen_random_uuid(),\n  label text not null default 'x',\n  short_code varchar(12) not null default 'abc',\n  padded bpchar(4) not null default 'ab',\n  active bool not null default true,\n  seen_at timestamptz not null default now(),\n  local_at timestamp not null default now(),\n  blob_j json not null default '{\"a\":1}',\n  blob_jb jsonb not null default '{\"b\":2}',\n  state parcel_state not null default 'queued',\n  shipped_on date not null default '2026-02-03',\n  cutoff time not null default '13:45:10',\n  cutoff_tz timetz not null default '13:45:10+02',\n  transit interval not null default '1 day 02:00:00',\n  stamp bytea not null default '\\xdeadbeef',\n  source_ip inet not null default '192.168.0.1',\n  subnet cidr not null default '10.0.0.0/8',\n  device macaddr not null default '08:00:2b:01:02:03',\n  tags text[] not null default array['x','y'],\n  counts int4[] not null default array[1,2,3],\n  amounts numeric[] not null default array['1.50']::numeric[],\n  states parcel_state[] not null default array['queued']::parcel_state[],\n  grid int4[][] not null default array[array[1,2],array[3,4]],\n  note text\n);\n\ninsert into parcels (note, size) values\n  ('first', row(100, 40)::dimensions),\n  (null, null);\n\ncreate view lost_parcels as\n  select id, tracking, state from parcels where state = 'lost';\n";
+export declare function assertFixtureCompleteness(snapshot: Snapshot): void;

package/dist/fixture.js

@@ -0,0 +1,65 @@
+import { MAPPED_PG_TYPES } from "@supawatch/core";
+// The harness fixture exercises EVERY row of core's runtime map, plus an
+// enum and nullable variants. The completeness check below is what makes
+// "every mapping row is verified" a build property instead of a hope.
+export const FIXTURE_SQL = `
+create type parcel_state as enum ('queued', 'shipped', 'lost');
+create type dimensions as (width_mm int4, height_mm int4);
+create domain tracking_code as text;
+create domain weight_grams as int4;
+
+create table parcels (
+  size dimensions,
+  tracking tracking_code not null default 'T-1',
+  weight weight_grams not null default 250,
+  id serial primary key,
+  small int2 not null default 1,
+  big int8 not null default 9007199254740993,
+  ratio float4 not null default 0.5,
+  wide float8 not null default 2.25,
+  price numeric(10,2) not null default 19.99,
+  ref uuid not null default gen_random_uuid(),
+  label text not null default 'x',
+  short_code varchar(12) not null default 'abc',
+  padded bpchar(4) not null default 'ab',
+  active bool not null default true,
+  seen_at timestamptz not null default now(),
+  local_at timestamp not null default now(),
+  blob_j json not null default '{"a":1}',
+  blob_jb jsonb not null default '{"b":2}',
+  state parcel_state not null default 'queued',
+  shipped_on date not null default '2026-02-03',
+  cutoff time not null default '13:45:10',
+  cutoff_tz timetz not null default '13:45:10+02',
+  transit interval not null default '1 day 02:00:00',
+  stamp bytea not null default '\\xdeadbeef',
+  source_ip inet not null default '192.168.0.1',
+  subnet cidr not null default '10.0.0.0/8',
+  device macaddr not null default '08:00:2b:01:02:03',
+  tags text[] not null default array['x','y'],
+  counts int4[] not null default array[1,2,3],
+  amounts numeric[] not null default array['1.50']::numeric[],
+  states parcel_state[] not null default array['queued']::parcel_state[],
+  grid int4[][] not null default array[array[1,2],array[3,4]],
+  note text
+);
+
+insert into parcels (note, size) values
+  ('first', row(100, 40)::dimensions),
+  (null, null);
+
+create view lost_parcels as
+  select id, tracking, state from parcels where state = 'lost';
+`;
+export function assertFixtureCompleteness(snapshot) {
+    const seen = new Set();
+    for (const table of snapshot.tables) {
+        for (const col of table.columns)
+            seen.add(col.pgTypeName);
+    }
+    const missing = MAPPED_PG_TYPES.filter((t) => !seen.has(t));
+    if (missing.length > 0) {
+        throw new Error(`runtime-map rows with no fixture coverage: ${missing.join(", ")}; ` +
+            "add columns to the harness fixture before adding mapping rows");
+    }
+}

package/dist/harness.d.ts

@@ -0,0 +1,46 @@
+import { type Target, type TargetOptions } from "@supawatch/core";
+export interface HarnessTarget {
+    target: Target;
+    options: TargetOptions;
+}
+export interface AllowedDivergence {
+    id: string;
+    target: string;
+    caseName: string;
+    reason: string;
+}
+export interface ParityCase {
+    table: string;
+    caseName: string;
+    verdicts: Record<string, boolean>;
+    agreed: boolean;
+    allowedId?: string;
+}
+export interface GroundTruthRow {
+    target: string;
+    table: string;
+    rows: number;
+    passed: number;
+    failures: string[];
+}
+export interface NegativeResult {
+    target: string;
+    caseName: string;
+    fired: boolean;
+}
+export interface HarnessResult {
+    groundTruth: GroundTruthRow[];
+    negatives: NegativeResult[];
+    parity: ParityCase[];
+    unfiredAllowed: string[];
+    problems: string[];
+}
+export declare const DRIVER_DELTAS: readonly [{
+    readonly id: "int8-bigint-vs-string";
+    readonly detail: "PGlite parses int8 to a JS BigInt; postgres.js returns its decimal string. Normalized: BigInt -> String(value).";
+}];
+export declare function runHarness(opts: {
+    targets: HarnessTarget[];
+    workDir: string;
+    allowed?: AllowedDivergence[];
+}): Promise<HarnessResult>;

package/dist/harness.js

@@ -0,0 +1,212 @@
+import path from "node:path";
+import { PGlite } from "@electric-sql/pglite";
+import { assemble, atomicSink, introspect, } from "@supawatch/core";
+import { FIXTURE_SQL, assertFixtureCompleteness } from "./fixture.js";
+// Where PGlite's client and postgres.js disagree about a type's JS value,
+// the harness normalizes to the postgres.js profile, because that is what
+// consumers run. Each delta is named here; a new one must be added
+// consciously, not absorbed silently.
+export const DRIVER_DELTAS = [
+    {
+        id: "int8-bigint-vs-string",
+        detail: "PGlite parses int8 to a JS BigInt; postgres.js returns its decimal string. Normalized: BigInt -> String(value).",
+    },
+];
+function normalize(value) {
+    if (typeof value === "bigint")
+        return value.toString();
+    return value;
+}
+function querierFromPglite(db) {
+    return async (text, params) => {
+        const result = await db.query(text, params);
+        return result.rows.map((row) => {
+            const out = {};
+            for (const [k, v] of Object.entries(row))
+                out[k] = normalize(v);
+            return out;
+        });
+    };
+}
+// Build per-column wrong values from the runtime kind. Each one is a value
+// the driver can never produce for that column, so every target must
+// reject it. json and unknown accept anything and produce no negatives;
+// so does an array of unknown, which is the honest multidim mapping.
+function negativeValueFor(table, colName) {
+    const col = table.columns.find((c) => c.name === colName);
+    return wrongValueFor(col.runtime);
+}
+function wrongValueFor(runtime) {
+    switch (runtime.kind) {
+        case "number":
+            return "42";
+        case "string":
+            return 42;
+        case "boolean":
+            return "true";
+        case "date":
+            return "2026-01-01T00:00:00Z";
+        case "bytes":
+            return "deadbeef";
+        case "enum":
+            return "not_a_label";
+        case "array": {
+            // Two failure modes: not an array at all, or a wrong element.
+            // The scalar case here is the not-an-array one; the element-level
+            // negative is added separately below.
+            return "not-an-array";
+        }
+        case "json":
+        case "unknown":
+            return undefined;
+    }
+}
+function wrongElementFor(runtime) {
+    if (runtime.kind !== "array")
+        return undefined;
+    const el = wrongValueFor(runtime.element);
+    if (el === undefined)
+        return undefined;
+    return [el];
+}
+export async function runHarness(opts) {
+    const allowed = opts.allowed ?? [];
+    const db = new PGlite();
+    const problems = [];
+    try {
+        await db.exec(FIXTURE_SQL);
+        const query = querierFromPglite(db);
+        const snapshot = await introspect(query);
+        assertFixtureCompleteness(snapshot);
+        // Emit every target's schemas once, into workDir/<target>/.
+        const loaded = new Map();
+        for (const { target, options } of opts.targets) {
+            if (!target.verifier) {
+                throw new Error(`harness target ${target.name} has no verifier; type-only targets do not belong in the harness`);
+            }
+            const dir = path.join(opts.workDir, target.name);
+            const verifier = target.verifier();
+            const schemaByTable = new Map();
+            for (const table of snapshot.tables) {
+                const rendered = target.renderTable(table, snapshot, options);
+                const file = path.join(dir, `${table.name}${target.fileExtension}`);
+                await atomicSink.write(file, assemble(rendered));
+                schemaByTable.set(table.name, await verifier.load(file, rendered.exportName));
+            }
+            loaded.set(target.name, { schemaByTable, verifier });
+        }
+        // Case pool: real rows (positive) plus synthetic negatives.
+        const groundTruth = [];
+        const negatives = [];
+        const parity = [];
+        for (const table of snapshot.tables) {
+            const rows = await query(`select * from "${table.name}" limit 10`);
+            // Ground truth: every real row must be accepted by every target.
+            for (const [name, { schemaByTable, verifier }] of loaded) {
+                const schema = schemaByTable.get(table.name);
+                let passed = 0;
+                const failures = [];
+                for (const row of rows) {
+                    const verdict = verifier.check(schema, row);
+                    if (verdict.ok)
+                        passed++;
+                    else
+                        failures.push(`${table.name}: ${verdict.reason ?? "no reason"}`);
+                }
+                groundTruth.push({
+                    target: name,
+                    table: table.name,
+                    rows: rows.length,
+                    passed,
+                    failures,
+                });
+                if (passed !== rows.length) {
+                    problems.push(`ground truth: ${name} rejected a real ${table.name} row (${failures[0]})`);
+                }
+            }
+            if (rows.length === 0)
+                continue;
+            const base = rows[0];
+            // Negatives and parity, one case per column plus one extra-key case.
+            const cases = [];
+            for (const col of table.columns) {
+                const wrong = negativeValueFor(table, col.name);
+                if (wrong === undefined)
+                    continue;
+                cases.push({
+                    caseName: `${table.name}.${col.name}:wrong-${col.runtime.kind}`,
+                    value: { ...base, [col.name]: wrong },
+                    expectReject: true,
+                });
+                const wrongElement = wrongElementFor(col.runtime);
+                if (wrongElement !== undefined) {
+                    cases.push({
+                        caseName: `${table.name}.${col.name}:wrong-element`,
+                        value: { ...base, [col.name]: wrongElement },
+                        expectReject: true,
+                    });
+                }
+                if (!col.nullable && col.runtime.kind !== "unknown" && col.runtime.kind !== "json") {
+                    cases.push({
+                        caseName: `${table.name}.${col.name}:null-in-not-null`,
+                        value: { ...base, [col.name]: null },
+                        expectReject: true,
+                    });
+                }
+            }
+            cases.push({
+                caseName: `${table.name}:extra-key`,
+                value: { ...base, __supawatch_extra: 1 },
+                expectReject: true,
+            });
+            for (const c of cases) {
+                const verdicts = {};
+                for (const [name, { schemaByTable, verifier }] of loaded) {
+                    const schema = schemaByTable.get(table.name);
+                    const verdict = verifier.check(schema, c.value);
+                    verdicts[name] = verdict.ok;
+                    if (c.expectReject) {
+                        const fired = !verdict.ok;
+                        negatives.push({ target: name, caseName: c.caseName, fired });
+                        if (!fired) {
+                            const entry = allowed.find((a) => a.target === name && a.caseName === c.caseName);
+                            if (!entry) {
+                                problems.push(`negative did not fire: ${name} accepted ${c.caseName}`);
+                            }
+                        }
+                    }
+                }
+                const values = Object.values(verdicts);
+                const agreed = values.every((x) => x === values[0]);
+                let allowedId;
+                if (!agreed) {
+                    const entry = allowed.find((a) => a.caseName === c.caseName);
+                    allowedId = entry?.id;
+                    if (!entry) {
+                        problems.push(`parity: targets disagree on ${c.caseName} (${JSON.stringify(verdicts)}) with no ALLOWED entry`);
+                    }
+                }
+                parity.push({ table: table.name, caseName: c.caseName, verdicts, agreed, allowedId });
+            }
+        }
+        // Ledger hygiene: every ALLOWED entry must have fired.
+        const firedIds = new Set(parity.filter((p) => p.allowedId).map((p) => p.allowedId));
+        for (const n of negatives) {
+            if (!n.fired) {
+                const entry = allowed.find((a) => a.target === n.target && a.caseName === n.caseName);
+                if (entry)
+                    firedIds.add(entry.id);
+            }
+        }
+        const unfiredAllowed = allowed
+            .filter((a) => !firedIds.has(a.id))
+            .map((a) => a.id);
+        for (const id of unfiredAllowed) {
+            problems.push(`ALLOWED entry ${id} never fired; the divergence it excuses is gone, remove it`);
+        }
+        return { groundTruth, negatives, parity, unfiredAllowed, problems };
+    }
+    finally {
+        await db.close();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { runHarness, DRIVER_DELTAS, type AllowedDivergence, type GroundTruthRow, type HarnessResult, type HarnessTarget, type NegativeResult, type ParityCase, } from "./harness.js";
+export { FIXTURE_SQL, assertFixtureCompleteness } from "./fixture.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { runHarness, DRIVER_DELTAS, } from "./harness.js";
+export { FIXTURE_SQL, assertFixtureCompleteness } from "./fixture.js";

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@supawatch/verify",
+  "version": "0.1.1",
+  "license": "MIT",
+  "author": "Omar Dulaimi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/omar-dulaimi/supawatch.git",
+    "directory": "packages/verify"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@electric-sql/pglite": "^0.3.0",
+    "@supawatch/core": "0.1.1"
+  },
+  "devDependencies": {
+    "@sinclair/typebox": "^0.34.52",
+    "@types/node": "^22.20.1",
+    "arktype": "^2.2.3",
+    "typescript": "^5.9.0",
+    "valibot": "^1.1.0",
+    "zod": "^4.0.0",
+    "@supawatch/target-typebox": "0.1.1",
+    "@supawatch/target-valibot": "0.1.1",
+    "@supawatch/target-zod": "0.1.1",
+    "@supawatch/target-arktype": "0.1.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}