rastack 0.0.46 → 0.0.48

package/dist/rastack-import.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * `rastack import` — load external data (CSV, Excel, PDF) into the shape of a
+ * compiled resource and run every row through the resource's constraint state
+ * machine.
+ *
+ *   rastack import <file> --resource app.model
+ *       [--schema .rastack/schema.rastack.json]   the compiled manifest
+ *       [--related app.model=<file>]              ids to resolve FKs against (repeatable)
+ *       [--out cleaned.json]                      write the coerced valid records
+ *       [--report report.json]                    write the full validation report
+ *       [--max-errors 20]                         issues to print before summarising
+ *       [--allow-invalid]                         exit 0 even when rows fail
+ *
+ * The validation is the same machine the form hooks run per keystroke and the
+ * API enforces on writes: `present → typed → bounded → member → unique →
+ * resolved`. Here it runs with the full dataset context, so in-file duplicate
+ * `unique` values and dangling foreign keys are rejected with row-located
+ * errors. Exit status is non-zero when any row fails (like the seed PII gate)
+ * unless `--allow-invalid` is passed.
+ */
+export {};

package/dist/rastack-import.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * `rastack import` — load external data (CSV, Excel, PDF) into the shape of a
+ * compiled resource and run every row through the resource's constraint state
+ * machine.
+ *
+ *   rastack import <file> --resource app.model
+ *       [--schema .rastack/schema.rastack.json]   the compiled manifest
+ *       [--related app.model=<file>]              ids to resolve FKs against (repeatable)
+ *       [--out cleaned.json]                      write the coerced valid records
+ *       [--report report.json]                    write the full validation report
+ *       [--max-errors 20]                         issues to print before summarising
+ *       [--allow-invalid]                         exit 0 even when rows fail
+ *
+ * The validation is the same machine the form hooks run per keystroke and the
+ * API enforces on writes: `present → typed → bounded → member → unique →
+ * resolved`. Here it runs with the full dataset context, so in-file duplicate
+ * `unique` values and dangling foreign keys are rejected with row-located
+ * errors. Exit status is non-zero when any row fails (like the seed PII gate)
+ * unless `--allow-invalid` is passed.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const validate_1 = require("./validate");
+const import_1 = require("./import");
+// ---------------------------------------------------------------------------
+// Args
+// ---------------------------------------------------------------------------
+const args = process.argv.slice(2);
+function getArg(flag) {
+    const i = args.indexOf(flag);
+    return i !== -1 && args[i + 1] ? args[i + 1] : null;
+}
+function getArgs(flag) {
+    const values = [];
+    for (let i = 0; i < args.length - 1; i++) {
+        if (args[i] === flag)
+            values.push(args[i + 1]);
+    }
+    return values;
+}
+const USAGE = "Usage: rastack import <file.csv|.xlsx|.pdf> --resource app.model\n" +
+    "         [--schema .rastack/schema.rastack.json] [--related app.model=<file>]\n" +
+    "         [--out cleaned.json] [--report report.json] [--max-errors n] [--allow-invalid]";
+function fail(message) {
+    console.error(`✗ ${message}\n\n${USAGE}`);
+    process.exit(1);
+}
+// ---------------------------------------------------------------------------
+// Load
+// ---------------------------------------------------------------------------
+function loadFile(filePath) {
+    const format = (0, import_1.formatOf)(filePath);
+    if (!format)
+        fail(`unsupported file type: ${filePath} (use .csv, .xlsx or .pdf)`);
+    if (!fs_1.default.existsSync(filePath))
+        fail(`file not found: ${filePath}`);
+    return (0, import_1.parseTabular)(format, fs_1.default.readFileSync(filePath));
+}
+function loadManifest(schemaPath) {
+    if (!fs_1.default.existsSync(schemaPath)) {
+        fail(`manifest not found at ${schemaPath} — run \`rastack compile\` first, ` +
+            `or point --schema at a schema.rastack.json`);
+    }
+    return JSON.parse(fs_1.default.readFileSync(schemaPath, "utf-8"));
+}
+function findResource(manifest, name) {
+    const resource = manifest.resources.find((r) => `${r.app}.${r.model}` === name);
+    if (!resource) {
+        fail(`unknown resource "${name}" — available: ` +
+            manifest.resources.map((r) => `${r.app}.${r.model}`).join(", "));
+    }
+    return resource;
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+const VALUE_FLAGS = new Set([
+    "--resource",
+    "--schema",
+    "--related",
+    "--out",
+    "--report",
+    "--max-errors",
+]);
+/** The first token that is neither a flag nor a flag's value. */
+function positionalArg() {
+    for (let i = 0; i < args.length; i++) {
+        if (VALUE_FLAGS.has(args[i])) {
+            i++; // skip the flag's value
+        }
+        else if (!args[i].startsWith("--")) {
+            return args[i];
+        }
+    }
+    return null;
+}
+function main() {
+    const file = positionalArg();
+    const resourceName = getArg("--resource");
+    if (!file || !resourceName)
+        fail("a source file and --resource are required");
+    const schemaPath = getArg("--schema") ??
+        path_1.default.join(process.cwd(), ".rastack", "schema.rastack.json");
+    const manifest = loadManifest(schemaPath);
+    const resource = findResource(manifest, resourceName);
+    const specs = (0, validate_1.specsFromResource)(resource);
+    // Related id sets for FK resolution: --related airports.airport=airports.csv
+    const relatedIds = {};
+    for (const spec of getArgs("--related")) {
+        const eq = spec.indexOf("=");
+        if (eq === -1)
+            fail(`--related expects app.model=<file>, got "${spec}"`);
+        relatedIds[spec.slice(0, eq)] = (0, import_1.idsFromTabular)(loadFile(spec.slice(eq + 1)));
+    }
+    const data = loadFile(file);
+    console.log(`\nrastack import  ${path_1.default.basename(file)} → ${resourceName}  ` +
+        `[${data.headers.length} column(s), ${data.rows.length} row(s)]\n`);
+    const report = (0, import_1.validateDataset)(specs, data, { relatedIds });
+    printReport(report);
+    const outPath = getArg("--out");
+    if (outPath) {
+        fs_1.default.writeFileSync(outPath, JSON.stringify(report.records, null, 2) + "\n");
+        console.log(`✓ ${report.records.length} valid record(s) → ${outPath}`);
+    }
+    const reportPath = getArg("--report");
+    if (reportPath) {
+        // Keep the on-disk report data-shaped: drop the per-row machine runs.
+        const { rows: _rows, ...summary } = report;
+        fs_1.default.writeFileSync(reportPath, JSON.stringify(summary, null, 2) + "\n");
+        console.log(`✓ validation report → ${reportPath}`);
+    }
+    if (report.invalid > 0 && !args.includes("--allow-invalid")) {
+        process.exit(1);
+    }
+}
+function printReport(report) {
+    for (const col of report.columns) {
+        console.log(col.field
+            ? `  ${col.header} → ${col.field}`
+            : `  ${col.header} → (ignored — no matching field)`);
+    }
+    for (const missing of report.missingFields) {
+        console.log(`  (no column) → ${missing}`);
+    }
+    console.log("");
+    const maxErrors = Number(getArg("--max-errors") ?? 20);
+    for (const issue of report.issues.slice(0, maxErrors)) {
+        console.log(`  ✗ row ${issue.row + 1}  ${issue.field}: ${issue.message}` +
+            `  [failed at "${issue.gate}" — ${issue.constraint}]`);
+    }
+    if (report.issues.length > maxErrors) {
+        console.log(`  … and ${report.issues.length - maxErrors} more issue(s)`);
+    }
+    if (report.issues.length)
+        console.log("");
+    console.log(`${report.invalid === 0 ? "✓" : "✗"} ${report.valid}/${report.total} row(s) valid` +
+        (report.invalid ? `, ${report.invalid} rejected` : ""));
+}
+main();

package/dist/rastack.d.ts

@@ -12,6 +12,7 @@
  *   rastack design  [input] [--port n]          Live design-system studio (showcase + edit)
  *   rastack dev     [--port n] [--warehouse d]  Local dev: run the app + admin in-browser over WASM
  *   rastack admin   [--warehouse dir] [--port n] Full admin console — React UI (rastack/components) over the native server
+ *   rastack import <file> --resource app.model  Load CSV/XLSX/PDF data and validate it (state machine)
  *   rastack scan   [files...] [--fail-on-pii]   Scan CSVs for PII and schema info
  *   rastack seed   [--env dev] [--source gs://] Load CSVs into Iceberg namespace
  *   rastack bootstrap [--owner o] [--repo r]    Stand the tier-0 AWS account stack up (once per account+region)

package/dist/rastack.js

@@ -13,6 +13,7 @@
  *   rastack design  [input] [--port n]          Live design-system studio (showcase + edit)
  *   rastack dev     [--port n] [--warehouse d]  Local dev: run the app + admin in-browser over WASM
  *   rastack admin   [--warehouse dir] [--port n] Full admin console — React UI (rastack/components) over the native server
+ *   rastack import <file> --resource app.model  Load CSV/XLSX/PDF data and validate it (state machine)
  *   rastack scan   [files...] [--fail-on-pii]   Scan CSVs for PII and schema info
  *   rastack seed   [--env dev] [--source gs://] Load CSVs into Iceberg namespace
  *   rastack bootstrap [--owner o] [--repo r]    Stand the tier-0 AWS account stack up (once per account+region)
@@ -89,6 +90,11 @@ switch (command) {
         // Live design-system studio (showcase + inspect + edit).
         run("rastack-design.js", rest);
         break;
+    case "import":
+        // Load external data (CSV / Excel / PDF) and validate it row-by-row
+        // through the resource's constraint state machine.
+        run("rastack-import.js", rest);
+        break;
     case "scan":
         run("scan.js");
         break;
@@ -133,6 +139,7 @@ switch (command) {
             `  rastack design  [input] [--port n]             Live design-system studio (showcase + edit)\n` +
             `  rastack dev     [--port n] [--warehouse dir] [--no-open]  Run the app + admin in-browser over WASM (local dev)\n` +
             `  rastack admin   [--warehouse dir] [--port n] [--no-open]  Full admin console (React UI over the native server; needs a built rastack-server)\n` +
+            `  rastack import <file.csv|.xlsx|.pdf> --resource app.model [--related app.model=<file>] [--out cleaned.json]\n` +
             `  rastack scan   [files...] [--fail-on-pii]\n` +
             `  rastack seed   [--env dev|staging] [--source gs://bucket/ | ./myapp-dev/]\n` +
             `  rastack bootstrap [--owner o] [--repo r] [--region r] [--prefix p] [--reuse-oidc] [--print]  Stand the AWS account stack up\n` +

package/dist/validate/adapters.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The two adapters that lower a field definition into a {@link FieldSpec} —
+ * the normalised constraint set the state machine is compiled from.
+ *
+ * - {@link specFromManifestField} reads `schema.rastack.json` (the compiler's
+ *   canonical manifest) — what the data-import pipeline uses. It sees the
+ *   *full* constraint set, including `unique` and the FK relation.
+ * - {@link specFromSchemaProperty} reads a write JSON Schema property (the
+ *   dereferenced `Deref{Name}Request` the form hooks validate against) — what
+ *   `getFormField` uses in the browser. It sees whatever the OpenAPI emitter
+ *   carries: type/format/maxLength/enum/nullable/`x-rastack-relation`.
+ *
+ * Both lower to the same `FieldSpec`, so the *same* compiled machine (same
+ * states, same gate order, same messages) validates a keystroke in a form and
+ * a row in an imported spreadsheet.
+ */
+import type { FieldModel } from "../compile/model";
+import type { FieldSpec } from "./machine";
+/**
+ * Lower a manifest field (`schema.rastack.json`) to a field spec. Mirrors the
+ * OpenAPI emitter's semantics: a field is required iff it is not nullable and
+ * carries no default; primary keys are server-assigned and never validated on
+ * input.
+ */
+export declare function specFromManifestField(field: FieldModel): FieldSpec;
+/**
+ * Lower every input-validated field of a manifest resource — primary keys are
+ * skipped, matching the write schema the OpenAPI emitter produces.
+ */
+export declare function specsFromResource(resource: {
+    fields: FieldModel[];
+}): FieldSpec[];
+/**
+ * Lower one property of a write JSON Schema to a field spec. `schema` is the
+ * object schema (so requiredness can be read from its `required` list);
+ * returns `undefined` when the property does not exist.
+ */
+export declare function specFromSchemaProperty(schema: {
+    properties?: Record<string, any>;
+    required?: unknown;
+    [key: string]: unknown;
+} | undefined, fieldName: string): FieldSpec | undefined;

package/dist/validate/adapters.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * The two adapters that lower a field definition into a {@link FieldSpec} —
+ * the normalised constraint set the state machine is compiled from.
+ *
+ * - {@link specFromManifestField} reads `schema.rastack.json` (the compiler's
+ *   canonical manifest) — what the data-import pipeline uses. It sees the
+ *   *full* constraint set, including `unique` and the FK relation.
+ * - {@link specFromSchemaProperty} reads a write JSON Schema property (the
+ *   dereferenced `Deref{Name}Request` the form hooks validate against) — what
+ *   `getFormField` uses in the browser. It sees whatever the OpenAPI emitter
+ *   carries: type/format/maxLength/enum/nullable/`x-rastack-relation`.
+ *
+ * Both lower to the same `FieldSpec`, so the *same* compiled machine (same
+ * states, same gate order, same messages) validates a keystroke in a form and
+ * a row in an imported spreadsheet.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.specFromManifestField = specFromManifestField;
+exports.specsFromResource = specsFromResource;
+exports.specFromSchemaProperty = specFromSchemaProperty;
+/**
+ * Lower a manifest field (`schema.rastack.json`) to a field spec. Mirrors the
+ * OpenAPI emitter's semantics: a field is required iff it is not nullable and
+ * carries no default; primary keys are server-assigned and never validated on
+ * input.
+ */
+function specFromManifestField(field) {
+    const spec = {
+        name: field.name,
+        type: field.type ?? "string",
+        required: !field.null && field.default === undefined && !field.primaryKey,
+        nullable: field.null === true,
+    };
+    if (field.maxLength !== undefined)
+        spec.maxLength = field.maxLength;
+    if (field.unique)
+        spec.unique = true;
+    if (field.default !== undefined)
+        spec.default = field.default;
+    if (field.type === "fk" && field.relation)
+        spec.relation = field.relation;
+    return spec;
+}
+/**
+ * Lower every input-validated field of a manifest resource — primary keys are
+ * skipped, matching the write schema the OpenAPI emitter produces.
+ */
+function specsFromResource(resource) {
+    return resource.fields
+        .filter((f) => !f.primaryKey)
+        .map(specFromManifestField);
+}
+/** Map a JSON-Schema scalar (`type` + `format`) back to a manifest scalar kind. */
+function schemaScalar(typeList, format) {
+    if (typeList.includes("integer"))
+        return "int";
+    if (typeList.includes("number"))
+        return "float";
+    if (typeList.includes("boolean"))
+        return "bool";
+    if (format === "date-time")
+        return "datetime";
+    if (format === "uuid")
+        return "uuid";
+    return "string";
+}
+/**
+ * Lower one property of a write JSON Schema to a field spec. `schema` is the
+ * object schema (so requiredness can be read from its `required` list);
+ * returns `undefined` when the property does not exist.
+ */
+function specFromSchemaProperty(schema, fieldName) {
+    const property = schema?.properties?.[fieldName];
+    if (!property)
+        return undefined;
+    const rawType = property.type;
+    const typeList = typeof rawType === "string"
+        ? [rawType]
+        : Array.isArray(rawType)
+            ? rawType
+            : [];
+    const nullable = typeList.includes("null") || property.nullable === true;
+    const required = Array.isArray(schema?.required) && schema.required.includes(fieldName);
+    const relation = property["x-rastack-relation"];
+    const format = typeof property.format === "string" ? property.format : undefined;
+    const spec = {
+        name: fieldName,
+        type: relation && typeof relation === "object"
+            ? "fk"
+            : schemaScalar(typeList, format),
+        required,
+        nullable,
+    };
+    if (relation && typeof relation === "object")
+        spec.relation = relation;
+    // `format` refines strings (`email`/`url`/`date`/`date-time`/`uuid`); the
+    // scalar kinds already encode datetime/uuid, so only keep it for strings.
+    if (spec.type === "string" && format)
+        spec.format = format;
+    if (typeof property.maxLength === "number")
+        spec.maxLength = property.maxLength;
+    if (Array.isArray(property.enum) && property.enum.length > 0) {
+        spec.options = property.enum.filter((v) => v !== null && v !== undefined);
+    }
+    if (property.default !== undefined)
+        spec.default = property.default;
+    return spec;
+}

package/dist/validate/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./machine";
+export * from "./adapters";

package/dist/validate/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./machine"), exports);
+__exportStar(require("./adapters"), exports);

package/dist/validate/machine.d.ts

@@ -0,0 +1,175 @@
+/**
+ * The constraint state machine — the validation core of the database generator.
+ *
+ * A field's constraints are not a bag of ad-hoc checks: they are compiled into
+ * a **deterministic finite state machine** whose intermediate states are the
+ * constraint gates a value must pass through, in a fixed order, to reach the
+ * accepting `valid` state:
+ *
+ * ```
+ * pristine → present → typed → bounded → member → unique → resolved → valid
+ *                └────────┴───── any gate fails ─────┴────────┘
+ *                                    ↓
+ *                                 invalid
+ * ```
+ *
+ * Compiling (`compileFieldMachine`) *builds the constraints*: each constraint
+ * on the field spec becomes exactly one gate (a guarded transition), and gates
+ * whose constraint is absent are simply not emitted — an unconstrained string
+ * field's machine is just `pristine → present → typed → valid`. Running
+ * (`runFieldMachine`) walks the gates with a raw value, coercing it along the
+ * way (`typed` parses `"12"` into `12`), and halts at the first failing gate,
+ * reporting the state reached and the constraint that rejected the value.
+ *
+ * Because the machine is pure data + pure functions (no filesystem, no DOM),
+ * the *same* machine drives every surface: the form hooks derive per-field
+ * machines from the write JSON Schema (`specFromSchemaProperty`), and the data
+ * import pipeline derives them from `schema.rastack.json`
+ * (`specFromManifestField`) — one validation brain, two adapters, mirroring
+ * how `rastack-api-core` is one request brain behind two transports.
+ *
+ * The `unique` and `resolved` (foreign-key) gates are dataset-level: they only
+ * engage when the {@link ValidationContext} provides the capability (a seen-set
+ * or a relation resolver). A context-free run — a form field validating a
+ * single keystroke — passes through them untouched, exactly like the server,
+ * where uniqueness and FK existence are checked against the table, not the
+ * payload.
+ */
+/** The `{ app, model }` a foreign-key field points at. */
+export interface SpecRelation {
+    app: string;
+    model: string;
+}
+/** Scalar kinds, matching the manifest's `ScalarType` plus `fk`. */
+export type SpecType = "string" | "int" | "float" | "bool" | "datetime" | "uuid" | "fk";
+/**
+ * The normalised constraint set for one field. Both adapters (manifest field,
+ * JSON-Schema property) lower to this shape; the machine compiler only ever
+ * sees a `FieldSpec`.
+ */
+export interface FieldSpec {
+    name: string;
+    type: SpecType;
+    /** Whether a value must be present (`required` short of a default). */
+    required: boolean;
+    /** Whether `null` is an accepted value. */
+    nullable: boolean;
+    /** Max string length (the `bounded` gate). */
+    maxLength?: number;
+    /** Dataset-level uniqueness (the `unique` gate). */
+    unique?: boolean;
+    /** String format refinement: `email` | `url` | `date` | `date-time` | `uuid`. */
+    format?: string;
+    /** Enum membership (the `member` gate). */
+    options?: Array<string | number>;
+    /** FK target — present iff `type === "fk"` (the `resolved` gate). */
+    relation?: SpecRelation;
+    /** Default applied when an optional field is empty. */
+    default?: unknown;
+}
+/** Every state a field machine can be in. */
+export type FieldState = "pristine" | "present" | "typed" | "bounded" | "member" | "unique" | "resolved" | "valid" | "invalid";
+/** The intermediate (gate) states, in canonical machine order. */
+export declare const GATE_ORDER: readonly FieldState[];
+/** The outcome of one gate check: pass (with the possibly-coerced value) or fail. */
+export type GateResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * One guarded transition of the machine. Passing the guard enters state `to`
+ * and threads the (possibly coerced) value into the next gate.
+ */
+export interface Gate {
+    to: FieldState;
+    /** Human-readable constraint, e.g. `"maxLength ≤ 3"` — drives UI hints and import reports. */
+    constraint: string;
+    check: (value: unknown, ctx: ValidationContext) => GateResult;
+}
+/** A compiled field machine: the spec, its gates, and the full state chain. */
+export interface FieldMachine {
+    spec: FieldSpec;
+    gates: Gate[];
+    /** `["pristine", ...gate states..., "valid"]` — the happy path. */
+    states: FieldState[];
+}
+/**
+ * Dataset-level capabilities. Absent capabilities leave the corresponding
+ * gates inert (they pass), so a machine runs identically in a browser form
+ * (no context) and in the import pipeline (full context) minus the
+ * dataset-level checks.
+ */
+export interface ValidationContext {
+    /** Per-field sets of already-seen values, keyed by field name (the `unique` gate). */
+    seen?: Map<string, Set<string>>;
+    /** Resolve whether a FK value exists on the target resource (the `resolved` gate). */
+    resolveRelation?: (relation: SpecRelation, value: unknown) => boolean;
+}
+/** The result of running a value through a field machine. */
+export interface FieldRun {
+    /** Terminal state: `valid` or `invalid`. */
+    state: "valid" | "invalid";
+    /** Every state entered, `pristine` first. Ends in `valid` or `invalid`. */
+    path: FieldState[];
+    /** The coerced value (e.g. `"12"` → `12`; empty optional → default/null). */
+    value: unknown;
+    /** Present iff `state === "invalid"`: the gate that rejected the value. */
+    failed?: {
+        gate: FieldState;
+        constraint: string;
+        message: string;
+    };
+}
+/**
+ * Compile a field spec into its constraint state machine. Every present
+ * constraint becomes one gate; absent constraints emit no gate, so the state
+ * chain is exactly the field's constraint set.
+ */
+export declare function compileFieldMachine(spec: FieldSpec): FieldMachine;
+/** The human-readable constraint chain — what the machine enforces, in order. */
+export declare function describeMachine(machine: FieldMachine): string[];
+/**
+ * Run a raw value through a field machine. Walks the gates in order, coercing
+ * the value as it goes; the first failing guard sends the machine to
+ * `invalid` with the offending constraint attached.
+ *
+ * An empty value on an optional field short-circuits from `present` straight
+ * to `valid` (yielding the default, else `null`) — there is nothing further
+ * to constrain, exactly like a nullable column.
+ */
+export declare function runFieldMachine(machine: FieldMachine, rawValue: unknown, ctx?: ValidationContext): FieldRun;
+/** A record machine is the composition of its fields' machines. */
+export interface RecordMachine {
+    fields: FieldMachine[];
+}
+/** One field's failure inside a record run. */
+export interface RecordError {
+    field: string;
+    gate: FieldState;
+    constraint: string;
+    message: string;
+}
+/** The result of running one record through a record machine. */
+export interface RecordRun {
+    state: "valid" | "invalid";
+    /** The coerced record — only meaningful when `state === "valid"`. */
+    values: Record<string, unknown>;
+    /** Per-field machine runs, keyed by field name. */
+    fields: Record<string, FieldRun>;
+    errors: RecordError[];
+}
+export declare function compileRecordMachine(specs: FieldSpec[]): RecordMachine;
+export declare function runRecordMachine(machine: RecordMachine, record: Record<string, unknown>, ctx?: ValidationContext): RecordRun;
+/**
+ * Build the dataset-level context for a record machine: a seen-set per
+ * `unique` field (so the `unique` gate engages), and — when related ids are
+ * supplied — a resolver for the `resolved` gate. `relatedIds` is keyed by
+ * `"app.model"`.
+ */
+export declare function createDatasetContext(machine: RecordMachine, opts?: {
+    relatedIds?: Record<string, Set<string>>;
+    resolveRelation?: (relation: SpecRelation, value: unknown) => boolean;
+}): ValidationContext;