@junejuly-lockstep/reconciler 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,55 @@
+import { LockstepConfig } from '@junejuly-lockstep/model';
+import type { z } from 'zod';
+export declare const WORKFLOW_PATH = ".github/workflows/lockstep-reconcile.yml";
+export declare const API_KEY_ENV = "LOCKSTEP_API_KEY";
+/** Helper for `lockstep.config.ts`: `export default defineConfig({...})` with types. */
+export declare function defineConfig(config: z.input<typeof LockstepConfig>): z.input<typeof LockstepConfig>;
+export interface LoadedConfig {
+    config: LockstepConfig;
+    /** Absolute path of the config file. */
+    file: string;
+    /** Directory the config lives in; every relative path in it resolves from here. */
+    rootDir: string;
+}
+/** Load `lockstep.config.ts` with jiti and validate it against `LockstepConfig`. */
+export declare function loadConfig(configPath?: string, cwd?: string): Promise<LoadedConfig>;
+export interface ContractCheckOptions {
+    /** Defaults to process.env. */
+    env?: NodeJS.ProcessEnv;
+    /** Skip the API key check (used by `lockstep validate --offline`). */
+    requireApiKey?: boolean;
+    /** Skip the workflow check (local dry runs). */
+    requireWorkflow?: boolean;
+}
+export interface ContractReport {
+    violations: Array<{
+        item: string;
+        message: string;
+    }>;
+    warnings: string[];
+    journeyFiles: string[];
+}
+/**
+ * Verify everything the contract requires beyond the config schema:
+ * journey files exist for the glob, the scenarios file exists, the workflow is committed,
+ * the API key is present, and the app under test points at a mock API origin.
+ */
+export declare function checkContract(loaded: LoadedConfig, opts?: ContractCheckOptions): Promise<ContractReport>;
+/**
+ * Security rule: the reconciler never walks a real backend. When the app's API base is
+ * configured it must match `mockApiPattern`; anything else is refused before boot.
+ */
+export declare function checkMockApiBase(config: LockstepConfig): {
+    violation?: {
+        item: string;
+        message: string;
+    };
+    warning?: string;
+};
+/** Throw the first violation (with the rest attached) when the contract is not met. */
+export declare function assertContract(report: ContractReport): void;
+/** Convenience: load + check + assert in one call. */
+export declare function loadAndCheck(configPath?: string, cwd?: string, opts?: ContractCheckOptions): Promise<LoadedConfig & {
+    report: ContractReport;
+}>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAI7B,eAAO,MAAM,aAAa,6CAA6C,CAAC;AACxE,eAAO,MAAM,WAAW,qBAAqB,CAAC;AAE9C,wFAAwF;AACxF,wBAAgB,YAAY,CAC1B,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,GACrC,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAEhC;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,cAAc,CAAC;IACvB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,oFAAoF;AACpF,wBAAsB,UAAU,CAC9B,UAAU,SAAuB,EACjC,GAAG,SAAgB,GAClB,OAAO,CAAC,YAAY,CAAC,CA4BvB;AAWD,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,sEAAsE;IACtE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gDAAgD;IAChD,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,YAAY,EACpB,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,cAAc,CAAC,CAiDzB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG;IACxD,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CA2BA;AAED,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAE3D;AAED,sDAAsD;AACtD,wBAAsB,YAAY,CAChC,UAAU,CAAC,EAAE,MAAM,EACnB,GAAG,CAAC,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,oBAAoB,GAC1B,OAAO,CAAC,YAAY,GAAG;IAAE,MAAM,EAAE,cAAc,CAAA;CAAE,CAAC,CAKpD"}

package/dist/config.js

@@ -0,0 +1,140 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import fg from 'fast-glob';
+import { LockstepConfig } from '@junejuly-lockstep/model';
+import { ContractViolation } from './errors.js';
+import { importTs, toPosix } from './util.js';
+export const WORKFLOW_PATH = '.github/workflows/lockstep-reconcile.yml';
+export const API_KEY_ENV = 'LOCKSTEP_API_KEY';
+/** Helper for `lockstep.config.ts`: `export default defineConfig({...})` with types. */
+export function defineConfig(config) {
+    return config;
+}
+/** Load `lockstep.config.ts` with jiti and validate it against `LockstepConfig`. */
+export async function loadConfig(configPath = 'lockstep.config.ts', cwd = process.cwd()) {
+    const file = path.resolve(cwd, configPath);
+    if (!existsSync(file)) {
+        throw new ContractViolation('lockstep.config.ts', `no config file at ${toPosix(path.relative(cwd, file)) || configPath}; run \`lockstep init\` to create one`);
+    }
+    let mod;
+    try {
+        mod = await importTs(file);
+    }
+    catch (err) {
+        throw new ContractViolation('lockstep.config.ts', `failed to load: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const raw = unwrapDefault(mod);
+    const parsed = LockstepConfig.safeParse(raw);
+    if (!parsed.success) {
+        throw ContractViolation.fromList(parsed.error.issues.map((issue) => ({
+            item: `lockstep.config.ts:${issue.path.join('.') || '<root>'}`,
+            message: issue.message,
+        })));
+    }
+    return { config: parsed.data, file, rootDir: path.dirname(file) };
+}
+function unwrapDefault(mod) {
+    if (mod && typeof mod === 'object') {
+        const m = mod;
+        if ('default' in m && m['default'] && typeof m['default'] === 'object')
+            return m['default'];
+        if ('config' in m && m['config'] && typeof m['config'] === 'object')
+            return m['config'];
+    }
+    return mod;
+}
+/**
+ * Verify everything the contract requires beyond the config schema:
+ * journey files exist for the glob, the scenarios file exists, the workflow is committed,
+ * the API key is present, and the app under test points at a mock API origin.
+ */
+export async function checkContract(loaded, opts = {}) {
+    const env = opts.env ?? process.env;
+    const { config, rootDir } = loaded;
+    const violations = [];
+    const warnings = [];
+    const journeyFiles = (await fg(config.journeysGlob, { cwd: rootDir, onlyFiles: true, dot: false }))
+        .map(toPosix)
+        .sort();
+    if (journeyFiles.length === 0) {
+        violations.push({
+            item: 'journeys',
+            message: `no journey files match "${config.journeysGlob}"; each journey is a *.journey.ts exporting machine and meta`,
+        });
+    }
+    if (!existsSync(path.resolve(rootDir, config.scenariosPath))) {
+        violations.push({
+            item: 'scenarios',
+            message: `scenarios file "${config.scenariosPath}" does not exist; it must export named personas (seed plus overrides)`,
+        });
+    }
+    if (opts.requireWorkflow !== false && !existsSync(path.resolve(rootDir, WORKFLOW_PATH))) {
+        violations.push({
+            item: 'workflow',
+            message: `${WORKFLOW_PATH} is missing; run \`lockstep init\` and commit the shipped workflow`,
+        });
+    }
+    if (opts.requireApiKey !== false && !env[API_KEY_ENV]) {
+        violations.push({
+            item: 'apiKey',
+            message: `${API_KEY_ENV} is not set; add the project API key to repo secrets and pass it to the workflow`,
+        });
+    }
+    else if (opts.requireApiKey !== false && !env[API_KEY_ENV].startsWith('lsk_')) {
+        violations.push({
+            item: 'apiKey',
+            message: `${API_KEY_ENV} does not look like a project key (expected lsk_ prefix)`,
+        });
+    }
+    const mock = checkMockApiBase(config);
+    if (mock.violation)
+        violations.push(mock.violation);
+    if (mock.warning)
+        warnings.push(mock.warning);
+    return { violations, warnings, journeyFiles };
+}
+/**
+ * Security rule: the reconciler never walks a real backend. When the app's API base is
+ * configured it must match `mockApiPattern`; anything else is refused before boot.
+ */
+export function checkMockApiBase(config) {
+    let pattern;
+    try {
+        pattern = new RegExp(config.mockApiPattern, 'i');
+    }
+    catch (err) {
+        return {
+            violation: {
+                item: 'mockApiPattern',
+                message: `mockApiPattern is not a valid regular expression: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
+    }
+    if (config.appApiBase === undefined) {
+        return {
+            warning: 'appApiBase is not set; the reconciler cannot verify the app under test talks to a mock origin. Set it so the walk is refused against a real backend.',
+        };
+    }
+    if (!pattern.test(config.appApiBase)) {
+        return {
+            violation: {
+                item: 'appApiBase',
+                message: `refusing to walk: appApiBase "${config.appApiBase}" does not match mockApiPattern /${config.mockApiPattern}/. Walks run against schema-seeded mocks only; point the app at MSW or a localhost mock.`,
+            },
+        };
+    }
+    return {};
+}
+/** Throw the first violation (with the rest attached) when the contract is not met. */
+export function assertContract(report) {
+    if (report.violations.length > 0)
+        throw ContractViolation.fromList(report.violations);
+}
+/** Convenience: load + check + assert in one call. */
+export async function loadAndCheck(configPath, cwd, opts) {
+    const loaded = await loadConfig(configPath, cwd);
+    const report = await checkContract(loaded, opts);
+    assertContract(report);
+    return { ...loaded, report };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/contract.d.ts

@@ -0,0 +1,61 @@
+import { type GraphQLSchema } from 'graphql';
+import type { ContractSnapshot, LockstepConfig } from '@junejuly-lockstep/model';
+export declare const NO_HASH = "none";
+export declare const LOCKFILES: readonly ["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lockb"];
+/** Parse SDL into a schema, raising a contract violation on syntax errors. */
+export declare function parseSdl(sdl: string, label?: string): GraphQLSchema;
+/** Canonical SDL: parsed, lexicographically sorted, re-printed. Formatting and ordering changes vanish. */
+export declare function canonicalSdl(sdl: string): string;
+/** sha256 of the canonical SDL. */
+export declare function hashSdl(sdl: string): string;
+/**
+ * `AvailableSlotsQuery` -> `AvailableSlots`: codegen names the result type alias after the
+ * operation plus its kind; the key the snapshot stores is the operation name itself, which is
+ * also the `operationName` the app sends on the wire and the walker records per step. Reach
+ * (API, `domain/reach.ts`) intersects those two sets, so they must share a vocabulary.
+ */
+export declare function operationNameOfAlias(aliasName: string): string;
+/**
+ * Per-operation response shape hashes from graphql-codegen output. Every exported
+ * `type FooQuery = {...}` / `type BarMutation = {...}` alias (not `*Variables`, not the
+ * schema root types) is hashed on its structural text with whitespace normalised and keyed by
+ * the operation name (`Foo`, `Bar`), never the alias.
+ */
+export declare function hashOperationShapes(codegenSource: string): Record<string, string>;
+/** Whitespace-insensitive, trailing-separator-insensitive text of a type literal. */
+export declare function normalizeShape(text: string): string;
+export declare function findLockfile(rootDir: string): string | null;
+/** sha256 of the lockfile with line endings normalised; `none` when the repo has no lockfile. */
+export declare function hashLockfile(rootDir: string): {
+    hash: string;
+    file: string | null;
+};
+export interface SdlChange {
+    type: string;
+    criticality: string;
+    message: string;
+    path: string | null;
+}
+/** Human-readable change list between two SDL documents (graphql-inspector). */
+export declare function diffSdl(oldSdl: string, newSdl: string): Promise<SdlChange[]>;
+export declare function formatSdlChanges(changes: SdlChange[]): string;
+export interface SnapshotOptions {
+    rootDir: string;
+    schema: LockstepConfig['schema'];
+    /** Where to write the human-readable change list and the current canonical SDL. */
+    outDir?: string;
+    /** Previous SDL text to diff against, when the caller has one. */
+    previousSdl?: string | null;
+}
+export interface SnapshotResult {
+    snapshot: ContractSnapshot;
+    lockfile: string | null;
+    changes: SdlChange[] | null;
+    /** Operation names whose shape hash differs from `previousOperations`, when provided. */
+    changedOperations: string[];
+}
+/** Build the `ContractSnapshot` for the payload and write the side files to `outDir`. */
+export declare function snapshotContract(opts: SnapshotOptions & {
+    previousOperations?: Record<string, string> | null;
+}): Promise<SnapshotResult>;
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqD,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAGhG,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAIjF,eAAO,MAAM,OAAO,SAAS,CAAC;AAC9B,eAAO,MAAM,SAAS,4EAA6E,CAAC;AAEpG,8EAA8E;AAC9E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,SAAW,GAAG,aAAa,CASrE;AAED,2GAA2G;AAC3G,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,mCAAmC;AACnC,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3C;AAKD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAYjF;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMnD;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAED,iGAAiG;AACjG,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAMnF;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,gFAAgF;AAChF,wBAAsB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAgBlF;AAQD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,CAW7D;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IACjC,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAC5B,yFAAyF;IACzF,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,yFAAyF;AACzF,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,eAAe,GAAG;IAAE,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;CAAE,GAC7E,OAAO,CAAC,cAAc,CAAC,CA4CzB"}

package/dist/contract.js

@@ -0,0 +1,154 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { buildSchema, lexicographicSortSchema, printSchema } from 'graphql';
+import { diff as inspectorDiff, CriticalityLevel } from '@graphql-inspector/core';
+import { Project, SyntaxKind } from 'ts-morph';
+import { ContractViolation } from './errors.js';
+import { ensureDir, normalizeNewlines, sha256 } from './util.js';
+export const NO_HASH = 'none';
+export const LOCKFILES = ['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock', 'bun.lockb'];
+/** Parse SDL into a schema, raising a contract violation on syntax errors. */
+export function parseSdl(sdl, label = 'schema') {
+    try {
+        return buildSchema(sdl, { assumeValidSDL: true });
+    }
+    catch (err) {
+        throw new ContractViolation(`schema:${label}`, `SDL does not parse: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Canonical SDL: parsed, lexicographically sorted, re-printed. Formatting and ordering changes vanish. */
+export function canonicalSdl(sdl) {
+    return printSchema(lexicographicSortSchema(parseSdl(sdl)));
+}
+/** sha256 of the canonical SDL. */
+export function hashSdl(sdl) {
+    return sha256(canonicalSdl(sdl));
+}
+const OPERATION_SUFFIX = /(Query|Mutation|Subscription)$/;
+const ROOT_TYPES = new Set(['Query', 'Mutation', 'Subscription']);
+/**
+ * `AvailableSlotsQuery` -> `AvailableSlots`: codegen names the result type alias after the
+ * operation plus its kind; the key the snapshot stores is the operation name itself, which is
+ * also the `operationName` the app sends on the wire and the walker records per step. Reach
+ * (API, `domain/reach.ts`) intersects those two sets, so they must share a vocabulary.
+ */
+export function operationNameOfAlias(aliasName) {
+    return aliasName.replace(OPERATION_SUFFIX, '');
+}
+/**
+ * Per-operation response shape hashes from graphql-codegen output. Every exported
+ * `type FooQuery = {...}` / `type BarMutation = {...}` alias (not `*Variables`, not the
+ * schema root types) is hashed on its structural text with whitespace normalised and keyed by
+ * the operation name (`Foo`, `Bar`), never the alias.
+ */
+export function hashOperationShapes(codegenSource) {
+    const project = new Project({ useInMemoryFileSystem: true, skipLoadingLibFiles: true });
+    const sf = project.createSourceFile('codegen.ts', codegenSource);
+    const out = {};
+    for (const alias of sf.getDescendantsOfKind(SyntaxKind.TypeAliasDeclaration)) {
+        const name = alias.getName();
+        if (!OPERATION_SUFFIX.test(name) || ROOT_TYPES.has(name) || name.endsWith('Variables'))
+            continue;
+        const shape = alias.getTypeNode()?.getText() ?? '';
+        out[operationNameOfAlias(name)] = sha256(normalizeShape(shape));
+    }
+    return Object.fromEntries(Object.entries(out).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+/** Whitespace-insensitive, trailing-separator-insensitive text of a type literal. */
+export function normalizeShape(text) {
+    return text
+        .replace(/\s+/g, ' ')
+        .replace(/\s*([{}:;,|<>()[\]?=])\s*/g, '$1')
+        .replace(/[;,]}/g, '}')
+        .trim();
+}
+export function findLockfile(rootDir) {
+    for (const name of LOCKFILES) {
+        const p = path.join(rootDir, name);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+/** sha256 of the lockfile with line endings normalised; `none` when the repo has no lockfile. */
+export function hashLockfile(rootDir) {
+    const file = findLockfile(rootDir);
+    if (!file)
+        return { hash: NO_HASH, file: null };
+    const content = readFileSync(file);
+    const text = file.endsWith('.lockb') ? content : normalizeNewlines(content.toString('utf8'));
+    return { hash: sha256(text), file: path.basename(file) };
+}
+/** Human-readable change list between two SDL documents (graphql-inspector). */
+export async function diffSdl(oldSdl, newSdl) {
+    const changes = await inspectorDiff(parseSdl(oldSdl, 'previous'), parseSdl(newSdl, 'current'));
+    return changes
+        .map((c) => ({
+        type: String(c.type),
+        criticality: c.criticality.level,
+        message: c.message,
+        path: c.path ?? null,
+    }))
+        .sort((a, b) => rank(b.criticality) - rank(a.criticality) || (a.path ?? '').localeCompare(b.path ?? ''));
+}
+function rank(level) {
+    if (level === CriticalityLevel.Breaking)
+        return 2;
+    if (level === CriticalityLevel.Dangerous)
+        return 1;
+    return 0;
+}
+export function formatSdlChanges(changes) {
+    if (changes.length === 0)
+        return '# GraphQL contract changes\n\nNo changes.\n';
+    const lines = ['# GraphQL contract changes', ''];
+    for (const level of ['BREAKING', 'DANGEROUS', 'NON_BREAKING']) {
+        const group = changes.filter((c) => c.criticality === level);
+        if (!group.length)
+            continue;
+        lines.push(`## ${level.toLowerCase().replace('_', '-')} (${group.length})`, '');
+        for (const c of group)
+            lines.push(`- ${c.message}${c.path ? ` (\`${c.path}\`)` : ''}`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/** Build the `ContractSnapshot` for the payload and write the side files to `outDir`. */
+export async function snapshotContract(opts) {
+    const lock = hashLockfile(opts.rootDir);
+    let sdlHash = NO_HASH;
+    let operations = {};
+    let changes = null;
+    if (opts.schema) {
+        const sdlPath = path.resolve(opts.rootDir, opts.schema.sdlPath);
+        if (!existsSync(sdlPath))
+            throw new ContractViolation('schema.sdlPath', `${opts.schema.sdlPath} does not exist`);
+        const sdl = readFileSync(sdlPath, 'utf8');
+        sdlHash = hashSdl(sdl);
+        const codegenPath = path.resolve(opts.rootDir, opts.schema.codegenOutput);
+        if (!existsSync(codegenPath)) {
+            throw new ContractViolation('schema.codegenOutput', `${opts.schema.codegenOutput} does not exist; run graphql-codegen`);
+        }
+        operations = hashOperationShapes(readFileSync(codegenPath, 'utf8'));
+        if (opts.outDir) {
+            ensureDir(opts.outDir);
+            writeFileSync(path.join(opts.outDir, 'schema.canonical.graphql'), canonicalSdl(sdl));
+            if (opts.previousSdl) {
+                changes = await diffSdl(opts.previousSdl, sdl);
+                writeFileSync(path.join(opts.outDir, 'contract-changes.md'), formatSdlChanges(changes));
+            }
+        }
+    }
+    const changedOperations = opts.previousOperations
+        ? Object.keys({ ...opts.previousOperations, ...operations })
+            .filter((k) => opts.previousOperations[k] !== operations[k])
+            .sort()
+        : [];
+    return {
+        snapshot: { sdlHash, operations, lockfileHash: lock.hash },
+        lockfile: lock.file,
+        changes,
+        changedOperations,
+    };
+}
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,uBAAuB,EAAE,WAAW,EAAsB,MAAM,SAAS,CAAC;AAChG,OAAO,EAAE,IAAI,IAAI,aAAa,EAAE,gBAAgB,EAAe,MAAM,yBAAyB,CAAC;AAC/F,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEjE,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC;AAC9B,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,gBAAgB,EAAE,mBAAmB,EAAE,WAAW,EAAE,WAAW,CAAU,CAAC;AAEpG,8EAA8E;AAC9E,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,KAAK,GAAG,QAAQ;IACpD,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,iBAAiB,CACzB,UAAU,KAAK,EAAE,EACjB,uBAAuB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAC1E,CAAC;IACJ,CAAC;AACH,CAAC;AAED,2GAA2G;AAC3G,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,WAAW,CAAC,uBAAuB,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,OAAO,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,gBAAgB,GAAG,gCAAgC,CAAC;AAC1D,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC;AAElE;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,OAAO,SAAS,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,aAAqB;IACvD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,EAAE,qBAAqB,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,CAAC,CAAC;IACxF,MAAM,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;IACjE,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,oBAAoB,CAAC,UAAU,CAAC,oBAAoB,CAAC,EAAE,CAAC;QAC7E,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;YACpF,SAAS;QACX,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACnD,GAAG,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClG,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI;SACR,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,OAAO,CAAC,4BAA4B,EAAE,IAAI,CAAC;SAC3C,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;SACtB,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACnC,IAAI,UAAU,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAChD,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7F,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;AAC3D,CAAC;AASD,gFAAgF;AAChF,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,MAAc,EAAE,MAAc;IAC1D,MAAM,OAAO,GAAa,MAAM,aAAa,CAC3C,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,EAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,CAC5B,CAAC;IACF,OAAO,OAAO;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACX,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;QACpB,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC,KAAK;QAChC,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,IAAI;KACrB,CAAC,CAAC;SACF,IAAI,CACH,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAC1F,CAAC;AACN,CAAC;AAED,SAAS,IAAI,CAAC,KAAa;IACzB,IAAI,KAAK,KAAK,gBAAgB,CAAC,QAAQ;QAAE,OAAO,CAAC,CAAC;IAClD,IAAI,KAAK,KAAK,gBAAgB,CAAC,SAAS;QAAE,OAAO,CAAC,CAAC;IACnD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAoB;IACnD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,6CAA6C,CAAC;IAC/E,MAAM,KAAK,GAAG,CAAC,4BAA4B,EAAE,EAAE,CAAC,CAAC;IACjD,KAAK,MAAM,KAAK,IAAI,CAAC,UAAU,EAAE,WAAW,EAAE,cAAc,CAAC,EAAE,CAAC;QAC9D,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,KAAK,CAAC,CAAC;QAC7D,IAAI,CAAC,KAAK,CAAC,MAAM;YAAE,SAAS;QAC5B,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,KAAK,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC,CAAC;QAChF,KAAK,MAAM,CAAC,IAAI,KAAK;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACvF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAmBD,yFAAyF;AACzF,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAA8E;IAE9E,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,OAAO,GAAG,OAAO,CAAC;IACtB,IAAI,UAAU,GAA2B,EAAE,CAAC;IAC5C,IAAI,OAAO,GAAuB,IAAI,CAAC;IAEvC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAChE,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;YACtB,MAAM,IAAI,iBAAiB,CAAC,gBAAgB,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;QACzF,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC1C,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAEvB,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;QAC1E,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,iBAAiB,CACzB,sBAAsB,EACtB,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,sCAAsC,CACnE,CAAC;QACJ,CAAC;QACD,UAAU,GAAG,mBAAmB,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;QAEpE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACvB,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,0BAA0B,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;YACrF,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;gBACrB,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;gBAC/C,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,qBAAqB,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC;YAC1F,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,iBAAiB,GAAG,IAAI,CAAC,kBAAkB;QAC/C,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,kBAAkB,EAAE,GAAG,UAAU,EAAE,CAAC;aACvD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,kBAAmB,CAAC,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC;aAC5D,IAAI,EAAE;QACX,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO;QACL,QAAQ,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,IAAI,CAAC,IAAI,EAAE;QAC1D,QAAQ,EAAE,IAAI,CAAC,IAAI;QACnB,OAAO;QACP,iBAAiB;KAClB,CAAC;AACJ,CAAC"}

package/dist/determinism.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The determinism contract. Every rule here is enforced in `walk.ts`; the list is exported so
+ * `lockstep validate` and the README print the same words.
+ */
+export declare const DETERMINISM_RULES: ReadonlyArray<{
+    rule: string;
+    how: string;
+}>;
+export interface HashMap {
+    [relPath: string]: string;
+}
+/** sha256 of every PNG under `dir`, keyed by posix relative path. */
+export declare function hashPngs(dir: string): Promise<HashMap>;
+export interface HashComparison {
+    identical: string[];
+    different: string[];
+    onlyInFirst: string[];
+    onlyInSecond: string[];
+    deterministic: boolean;
+}
+export declare function compareHashMaps(a: HashMap, b: HashMap): HashComparison;
+export declare function formatDeterminismReport(c: HashComparison): string;
+//# sourceMappingURL=determinism.d.ts.map

package/dist/determinism.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"determinism.d.ts","sourceRoot":"","sources":["../src/determinism.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CA0C1E,CAAC;AAEF,MAAM,WAAW,OAAO;IACtB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3B;AAED,qEAAqE;AACrE,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK5D;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,cAAc,CAkBtE;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAqBjE"}

package/dist/determinism.js

@@ -0,0 +1,102 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import fg from 'fast-glob';
+import { sha256, toPosix } from './util.js';
+/**
+ * The determinism contract. Every rule here is enforced in `walk.ts`; the list is exported so
+ * `lockstep validate` and the README print the same words.
+ */
+export const DETERMINISM_RULES = [
+    {
+        rule: 'Frozen clock',
+        how: 'page.clock.install + setFixedTime at FROZEN_EPOCH_MS (2026-01-15T09:30:00Z); Date.now() never moves',
+    },
+    { rule: 'Fixed viewport', how: '1280x800, deviceScaleFactor 1, not mobile, no touch' },
+    {
+        rule: 'No motion',
+        how: 'reducedMotion: reduce, CSS injected before first paint disabling animations, transitions, caret, smooth scroll; screenshots taken with animations: disabled',
+    },
+    {
+        rule: 'Fonts awaited',
+        how: 'document.fonts.ready plus two animation frames before every screenshot; Chromium font hinting and subpixel positioning disabled',
+    },
+    {
+        rule: 'Full tile raster',
+        how: '--disable-partial-raster: a tile whose content changed after first paint (an app that renders its root once its data arrived) is rastered whole, never only inside the damage rect, whose edges would otherwise differ by a unit of anti-aliasing from walk to walk',
+    },
+    {
+        rule: 'Settled after the root appears',
+        how: 'network idle, fonts and four animation frames again once the state root is visible (an app that renders after fetching through a mock worker shows its root after the first settle); the pointer is parked at (0,0) after every click so no hover depends on where it landed',
+    },
+    {
+        rule: 'Fixed locale and zone',
+        how: 'locale en-US, timezoneId UTC, TZ=UTC in the app process, colorScheme light, sRGB colour profile',
+    },
+    {
+        rule: 'Seeded mocks only',
+        how: 'LOCKSTEP_SCENARIO/LOCKSTEP_SEED env plus ?lockstep_scenario= query; appApiBase must match mockApiPattern or the run is refused',
+    },
+    {
+        rule: 'Deterministic ordering',
+        how: 'scenarios by name, journeys by key, paths by target state then event sequence, files by path',
+    },
+    {
+        rule: 'Fresh context per path',
+        how: 'a new browser context per path: no storage, cookies or cache leak between paths',
+    },
+    {
+        rule: 'Full-page CSS-pixel shots',
+        how: 'fullPage: true, scale: css, caret hidden, scrollbars hidden',
+    },
+];
+/** sha256 of every PNG under `dir`, keyed by posix relative path. */
+export async function hashPngs(dir) {
+    const files = (await fg(['**/*.png'], { cwd: dir, onlyFiles: true })).map(toPosix).sort();
+    const out = {};
+    for (const f of files)
+        out[f] = sha256(readFileSync(path.join(dir, f)));
+    return out;
+}
+export function compareHashMaps(a, b) {
+    const identical = [];
+    const different = [];
+    const onlyInFirst = [];
+    const onlyInSecond = [];
+    for (const k of Object.keys(a).sort()) {
+        if (!(k in b))
+            onlyInFirst.push(k);
+        else if (a[k] === b[k])
+            identical.push(k);
+        else
+            different.push(k);
+    }
+    for (const k of Object.keys(b).sort())
+        if (!(k in a))
+            onlyInSecond.push(k);
+    return {
+        identical,
+        different,
+        onlyInFirst,
+        onlyInSecond,
+        deterministic: different.length === 0 && onlyInFirst.length === 0 && onlyInSecond.length === 0,
+    };
+}
+export function formatDeterminismReport(c) {
+    const lines = [
+        `Determinism check: ${c.deterministic ? 'PASS' : 'FAIL'}`,
+        `  identical ${c.identical.length}, different ${c.different.length}, missing in second walk ${c.onlyInFirst.length}, extra in second walk ${c.onlyInSecond.length}`,
+    ];
+    for (const f of c.different)
+        lines.push(`  differs:  ${f}`);
+    for (const f of c.onlyInFirst)
+        lines.push(`  missing:  ${f}`);
+    for (const f of c.onlyInSecond)
+        lines.push(`  extra:    ${f}`);
+    if (!c.deterministic) {
+        lines.push('', '  Byte-identical screenshots are a hard requirement. Usual causes: unseeded data, Date.now() read');
+        lines.push('  outside the page (server components), animations started after first paint, lazy-loaded fonts or');
+        lines.push('  images without fixed dimensions, randomised ids rendered into the DOM. See README "Determinism rules".');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=determinism.js.map

package/dist/determinism.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"determinism.js","sourceRoot":"","sources":["../src/determinism.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A named violation of the client codebase contract (SPEC.md "Client codebase contract").
+ * `item` names the missing or invalid piece so CI output says exactly what to fix.
+ */
+export declare class ContractViolation extends Error {
+    readonly item: string;
+    readonly items: Array<{
+        item: string;
+        message: string;
+    }>;
+    constructor(item: string, message: string, more?: Array<{
+        item: string;
+        message: string;
+    }>);
+    static fromList(items: Array<{
+        item: string;
+        message: string;
+    }>): ContractViolation;
+}
+/** Something outside the client's contract failed: network, browser, filesystem, the platform API. */
+export declare class InfrastructureError extends Error {
+    readonly cause_: unknown;
+    constructor(message: string, cause?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;gBAE7C,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAM;IAY9F,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,iBAAiB;CAKpF;AAED,sGAAsG;AACtG,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAS7C"}

package/dist/errors.js

@@ -0,0 +1,35 @@
+/**
+ * A named violation of the client codebase contract (SPEC.md "Client codebase contract").
+ * `item` names the missing or invalid piece so CI output says exactly what to fix.
+ */
+export class ContractViolation extends Error {
+    item;
+    items;
+    constructor(item, message, more = []) {
+        const items = [{ item, message }, ...more];
+        super(items.length === 1
+            ? `Contract violation [${item}]: ${message}`
+            : `${items.length} contract violations:\n${items.map((i) => `  - [${i.item}] ${i.message}`).join('\n')}`);
+        this.name = 'ContractViolation';
+        this.item = item;
+        this.items = items;
+    }
+    static fromList(items) {
+        const [first, ...rest] = items;
+        if (!first)
+            throw new Error('ContractViolation.fromList needs at least one item');
+        return new ContractViolation(first.item, first.message, rest);
+    }
+}
+/** Something outside the client's contract failed: network, browser, filesystem, the platform API. */
+export class InfrastructureError extends Error {
+    cause_;
+    constructor(message, cause) {
+        super(cause instanceof Error && !message.includes(cause.message)
+            ? `${message}: ${cause.message}`
+            : message);
+        this.name = 'InfrastructureError';
+        this.cause_ = cause;
+    }
+}
+//# sourceMappingURL=errors.js.map