rastack 0.0.48 → 0.0.50

package/dist/define/index.d.ts

@@ -22,10 +22,19 @@
  * });
  * ```
  */
-/** A scalar field. The literal `__rastackScalar` type is what the compiler reads. */
-export interface Scalar<T extends string> {
+/**
+ * A scalar field. The literal `__rastackScalar` type is what the compiler
+ * reads; `Nullable` phantom-carries the `null: true` option so {@link RowOf}
+ * can add `| null` to the inferred row type.
+ */
+export interface Scalar<T extends string, Nullable extends boolean = boolean> {
     readonly __rastackScalar: T;
+    readonly __rastackNullable?: Nullable;
 }
+/** Whether an options literal declares `null: true` (as a type). */
+type NullOf<O> = O extends {
+    null: true;
+} ? true : false;
 /**
  * A foreign-key field. `App`/`Model` are carried as string-literal type
  * arguments so the compiler can recover the relation target purely from types.
@@ -64,12 +73,12 @@ export interface DateOptions {
  * runtime if a consumer wants it.
  */
 export declare const s: {
-    string(_opts?: StringOptions): Scalar<"string">;
-    int(_opts?: NumberOptions): Scalar<"int">;
-    float(_opts?: NumberOptions): Scalar<"float">;
-    bool(_opts?: BoolOptions): Scalar<"bool">;
-    datetime(_opts?: DateOptions): Scalar<"datetime">;
-    uuid(_opts?: StringOptions): Scalar<"uuid">;
+    string<const O extends StringOptions = StringOptions>(_opts?: O): Scalar<"string", NullOf<O>>;
+    int<const O extends NumberOptions = NumberOptions>(_opts?: O): Scalar<"int", NullOf<O>>;
+    float<const O extends NumberOptions = NumberOptions>(_opts?: O): Scalar<"float", NullOf<O>>;
+    bool<const O extends BoolOptions = BoolOptions>(_opts?: O): Scalar<"bool", NullOf<O>>;
+    datetime<const O extends DateOptions = DateOptions>(_opts?: O): Scalar<"datetime", NullOf<O>>;
+    uuid<const O extends StringOptions = StringOptions>(_opts?: O): Scalar<"uuid", NullOf<O>>;
     /**
      * A foreign key. The target is `() => SomeResource`; the compiler resolves
      * the relation from the *type* `Ref<App, Model>` this returns — it does not
@@ -105,6 +114,52 @@ export interface AccessOptions {
     scope?: "owner" | "shared";
     adminGroups?: string[];
 }
+/**
+ * One edge of a resource's state machine. `from` is the state (or states) the
+ * transition may fire from, `to` the state it enters, and `set` the effect —
+ * field patches the engine applies alongside the state change. The block is
+ * static data: it compiles into the manifest and is enforced by
+ * `rastack-api-core` on every surface (server, Lambda, in-browser WASM), so a
+ * transition behaves as a declarative, typesafe backend function with no
+ * per-resource server code.
+ */
+export interface TransitionEdge {
+    from: string | readonly string[];
+    to: string;
+    set?: Record<string, string | number | boolean | null>;
+}
+/**
+ * A resource's declarative state machine, keyed off one state field:
+ *
+ * ```ts
+ * transitions: {
+ *   field: "status",
+ *   states: ["scheduled", "boarding", "departed", "cancelled"],
+ *   initial: "scheduled",
+ *   on: {
+ *     board:  { from: "scheduled", to: "boarding" },
+ *     depart: { from: "boarding",  to: "departed" },
+ *     cancel: { from: ["scheduled", "boarding"], to: "cancelled" },
+ *   },
+ * }
+ * ```
+ *
+ * `states` becomes the field's allowed-value set (`enum` in OpenAPI, the
+ * `member` gate in the validation machine) and `initial` its default. A write
+ * that moves the field between states without a declared edge is rejected on
+ * every surface, and `useForm(Flight).transition("board")` exposes the edges
+ * as typed form actions.
+ */
+export interface TransitionsOptions {
+    /** The field carrying the machine state. */
+    field: string;
+    /** Every state the field may hold. */
+    states: readonly string[];
+    /** The state new records start in. */
+    initial?: string;
+    /** Named transitions. */
+    on: Record<string, TransitionEdge>;
+}
 export interface ResourceOptions {
     /** DRF-style search fields. */
     search?: string[];
@@ -120,19 +175,58 @@ export interface ResourceOptions {
     permission?: "authenticatedOrReadOnly" | "authenticated" | "public";
     /** Row-level security + physical tenant partitioning. */
     access?: AccessOptions;
+    /** Declarative state machine over one field, enforced on every write surface. */
+    transitions?: TransitionsOptions;
 }
 /**
  * A resource definition. `App`/`Model` are preserved as string-literal type
- * arguments so a {@link Ref} to this resource carries a recoverable target.
+ * arguments so a {@link Ref} to this resource carries a recoverable target,
+ * and the options object's literal type is preserved so downstream types can
+ * read the declared transition names (`useForm(Flight).transition("board")`
+ * only accepts names the resource actually declares).
  */
-export interface ResourceType<App extends string, Model extends string, F> {
+export interface ResourceType<App extends string, Model extends string, F, O extends ResourceOptions = ResourceOptions> {
     readonly __rastack: "resource";
     readonly __app: App;
     readonly __model: Model;
     readonly app: App;
     readonly model: Model;
     readonly fields: F;
-    readonly options: ResourceOptions;
+    readonly options: O;
 }
-/** Define a resource. Capture app/model as literal types for FK inference. */
-export declare function resource<App extends string, Model extends string, F extends Record<string, AnyField>>(app: App, model: Model, fields: F, options?: ResourceOptions): ResourceType<App, Model, F>;
+/** Define a resource. Capture app/model (and options) as literal types. */
+export declare function resource<App extends string, Model extends string, F extends Record<string, AnyField>, const O extends ResourceOptions = ResourceOptions>(app: App, model: Model, fields: F, options?: O): ResourceType<App, Model, F, O>;
+/**
+ * The transition names an entity declares — from a `resource()` value's
+ * options, or from a class's `static transitions` block. Entities with no
+ * transitions resolve to `never`, so `form.transition(...)` is uncallable on
+ * them at the type level.
+ */
+export type TransitionNamesOf<E> = E extends {
+    options: {
+        transitions: {
+            on: infer On;
+        };
+    };
+} ? Extract<keyof On, string> : E extends {
+    transitions: {
+        on: infer On;
+    };
+} ? Extract<keyof On, string> : E extends string ? string : never;
+type ScalarTsType<T extends string> = T extends "int" | "float" ? number : T extends "bool" ? boolean : string;
+/** The TypeScript value type one field of a `resource()` definition holds. */
+export type FieldValueOf<F> = F extends Scalar<infer T, infer N> ? N extends true ? ScalarTsType<T> | null : ScalarTsType<T> : F extends Ref<string, string> ? number | string : unknown;
+/**
+ * The row type a `resource()` definition implies — what `useData(Flight)`
+ * infers with **no type argument**: each field's scalar kind maps to its TS
+ * type (`null: true` adds `| null`), FKs are ids, plus the server-assigned
+ * `id`. Classes carry their own row type, and interfaces resolve through the
+ * `EntityTypes` registry (`rastack/hooks/registry`), so every reference form
+ * infers.
+ */
+export type RowOf<R> = R extends ResourceType<string, string, infer F, ResourceOptions> ? {
+    id: number | string;
+} & {
+    [K in keyof F]: FieldValueOf<F[K]>;
+} : never;
+export {};

package/dist/define/index.js

@@ -60,7 +60,7 @@ exports.s = {
         return { __rastackRef: true };
     },
 };
-/** Define a resource. Capture app/model as literal types for FK inference. */
+/** Define a resource. Capture app/model (and options) as literal types. */
 function resource(app, model, fields, options = {}) {
     return {
         __rastack: "resource",

package/dist/import/tabular.d.ts

@@ -9,7 +9,7 @@
  * Everything here is data-in/data-out (no filesystem), tested in
  * `tools/test/import.spec.ts`; the parsers and the CLI are the IO shell.
  */
-import { type FieldSpec, type FieldState, type RecordRun, type SpecRelation } from "../validate";
+import { type FieldSpec, type FieldState, type RecordRun, type SpecRelation, type TransitionsModel } from "../validate";
 /** A parsed tabular source: one header row + string cell rows. */
 export interface TabularData {
     headers: string[];
@@ -24,7 +24,7 @@ export interface ColumnMapping {
 export interface ImportIssue {
     row: number;
     field: string;
-    gate: FieldState;
+    gate: FieldState | "transition";
     constraint: string;
     message: string;
 }
@@ -60,6 +60,12 @@ export interface ValidateDatasetOptions {
     relatedIds?: Record<string, Set<string>>;
     /** Custom FK resolver (wins over `relatedIds`). */
     resolveRelation?: (relation: SpecRelation, value: unknown) => boolean;
+    /**
+     * The resource's state machine (`schema.rastack.json` `transitions`).
+     * Imported rows are creates, so the record-level `transition` gate rejects
+     * rows born mid-machine (a state other than the initial one).
+     */
+    transitions?: TransitionsModel;
 }
 /**
  * Run a whole tabular source through a resource's record machine. Each row is

package/dist/import/tabular.js

@@ -47,7 +47,7 @@ function mapHeaders(headers, specs) {
  */
 function validateDataset(specs, data, options = {}) {
     const { columns, missingFields } = mapHeaders(data.headers, specs);
-    const machine = (0, validate_1.compileRecordMachine)(specs);
+    const machine = (0, validate_1.compileRecordMachine)(specs, options.transitions);
     const ctx = (0, validate_1.createDatasetContext)(machine, options);
     const rows = [];
     const issues = [];

package/dist/rastack-admin.d.ts

@@ -1,14 +1,21 @@
 #!/usr/bin/env node
 /**
- * `rastack admin` — the full, Django-admin-style console, served by the native
- * `rastack-server` against the real Iceberg warehouse.
+ * `rastack admin` — the full, Django-admin-style console, served **in the
+ * browser over the prebuilt WebAssembly engine** (exactly like `rastack dev`).
  *
  *   rastack admin [resourcesDir] [--warehouse <dir>] [--port <n>] [--out <dir>] [--no-open]
  *
- * Unlike the old server-rendered `/admin`, the console is React API Stack's own
- * React admin (`tools/admin`, built from `rastack/components` + `rastack/theme`)
- * — this command compiles the resources, points the server at the prebuilt
- * bundle (`RASTACK_ADMIN_ASSETS`), and boots it. The bundle talks back to the
- * same server's `/api` over HTTP, so edits persist to the real warehouse.
+ * The console is React API Stack's own React admin (`tools/admin`, built from
+ * `rastack/components` + `rastack/theme`). This command compiles the resources,
+ * then boots a dependency-free static server that hands the browser everything
+ * it needs to run the admin locally over WASM — no native server, no cargo:
+ *   • the bundled React admin (`/dev/admin.js`), which defaults to `mode:"local"`,
+ *   • the prebuilt WASM engine (`/wasm/…`) shipped in the package,
+ *   • the compiled `schema.rastack.json` / `openapi.json`,
+ *   • the committed Iceberg warehouse (`/data/warehouse/…`) to seed from.
+ *
+ * The engine is the single prebuilt `.wasm` bundle shipped in the npm package;
+ * if it is missing the command errors and points at `rastack update` — it never
+ * falls back to a from-source cargo build.
  */
 export {};

package/dist/rastack-admin.js

@@ -1,16 +1,23 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * `rastack admin` — the full, Django-admin-style console, served by the native
- * `rastack-server` against the real Iceberg warehouse.
+ * `rastack admin` — the full, Django-admin-style console, served **in the
+ * browser over the prebuilt WebAssembly engine** (exactly like `rastack dev`).
  *
  *   rastack admin [resourcesDir] [--warehouse <dir>] [--port <n>] [--out <dir>] [--no-open]
  *
- * Unlike the old server-rendered `/admin`, the console is React API Stack's own
- * React admin (`tools/admin`, built from `rastack/components` + `rastack/theme`)
- * — this command compiles the resources, points the server at the prebuilt
- * bundle (`RASTACK_ADMIN_ASSETS`), and boots it. The bundle talks back to the
- * same server's `/api` over HTTP, so edits persist to the real warehouse.
+ * The console is React API Stack's own React admin (`tools/admin`, built from
+ * `rastack/components` + `rastack/theme`). This command compiles the resources,
+ * then boots a dependency-free static server that hands the browser everything
+ * it needs to run the admin locally over WASM — no native server, no cargo:
+ *   • the bundled React admin (`/dev/admin.js`), which defaults to `mode:"local"`,
+ *   • the prebuilt WASM engine (`/wasm/…`) shipped in the package,
+ *   • the compiled `schema.rastack.json` / `openapi.json`,
+ *   • the committed Iceberg warehouse (`/data/warehouse/…`) to seed from.
+ *
+ * The engine is the single prebuilt `.wasm` bundle shipped in the npm package;
+ * if it is missing the command errors and points at `rastack update` — it never
+ * falls back to a from-source cargo build.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -48,6 +55,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
+const http = __importStar(require("http"));
 const path = __importStar(require("path"));
 const harness_1 = require("./dev/harness");
 const HERE = __dirname; // dist/ when installed — the bundle lives beside us.
@@ -59,6 +67,42 @@ function compile(resourcesDir, outDir) {
         return false;
     return fs.existsSync(path.join(outDir, "schema.rastack.json"));
 }
+/** Locate the prebuilt wasm bundle dir shipped in the package (no cargo fallback). */
+function resolveWasmDir() {
+    for (const dir of (0, harness_1.wasmBundleCandidates)(HERE)) {
+        if (fs.existsSync(path.join(dir, harness_1.WASM_ENTRY)))
+            return dir;
+    }
+    return null;
+}
+/** Serve one file if it exists and stays within `root`; else 404/403. */
+function serveUnder(res, root, relPath) {
+    const safeRoot = path.resolve(root);
+    const rel = decodeURIComponent(relPath).replace(/^\/+/, "");
+    const target = path.resolve(safeRoot, rel);
+    // Path-traversal guard: the resolved target must stay inside the root.
+    if (target !== safeRoot && !target.startsWith(safeRoot + path.sep)) {
+        res.writeHead(403).end("Forbidden");
+        return;
+    }
+    fs.readFile(target, (err, data) => {
+        if (err) {
+            res.writeHead(404).end("Not found");
+            return;
+        }
+        res.writeHead(200, { "Content-Type": (0, harness_1.contentType)(target) }).end(data);
+    });
+}
+/** Serve an exact file (no traversal concern — a fixed internal artifact). */
+function serveFile(res, file) {
+    fs.readFile(file, (err, data) => {
+        if (err) {
+            res.writeHead(404).end("Not found");
+            return;
+        }
+        res.writeHead(200, { "Content-Type": (0, harness_1.contentType)(file) }).end(data);
+    });
+}
 /** Best-effort open the default browser at `url`. */
 function openBrowser(url) {
     const cmd = process.platform === "darwin"
@@ -81,47 +125,48 @@ function main(argv) {
         console.error("  ✗ compile failed — fix the resource graph and re-run.");
         process.exit(1);
     }
-    const bundle = path.join(HERE, "admin.js");
-    if (!fs.existsSync(bundle)) {
-        console.error("  ✗ admin bundle (dist/admin.js) not found — reinstall rastack.");
+    const wasmDir = resolveWasmDir();
+    if (!wasmDir) {
+        console.error("\n  ✗ No prebuilt WASM engine found in this rastack install.\n" +
+            "    Update rastack to pull the prebuilt bundle:\n" +
+            "      rastack update\n");
         process.exit(1);
     }
-    const repoRoot = path.resolve(HERE, "..", "..");
-    const binary = process.env.RASTACK_SERVER_BIN ||
-        path.join(repoRoot, "rust", "target", "release", "rastack-server");
-    const manifest = path.join(args.outDir, "schema.rastack.json");
-    const serverArgs = [
-        "admin",
-        "--manifest",
-        manifest,
-        "--warehouse",
-        args.warehouseDir,
-        "--addr",
-        `127.0.0.1:${args.port}`,
-        // Local dev context: the admin runs unauthenticated, exactly like the old
-        // native admin. Production admins run the server with --jwks/--admin-group.
-        "--insecure-dev-auth",
-    ];
-    const url = `http://127.0.0.1:${args.port}/admin/`;
-    // The server serves the React bundle from here; hand the path via env so the
-    // Rust side stays free of JS-toolchain knowledge.
-    const child = (0, child_process_1.spawn)(binary, serverArgs, {
-        stdio: "inherit",
-        env: { ...process.env, RASTACK_ADMIN_ASSETS: HERE },
-    });
-    child.on("error", () => {
-        console.error(`  ✗ Could not run the Rust server (${binary}). Build it first:\n` +
-            `      cd rust && cargo build --release\n`);
+    const adminBundle = path.join(HERE, "admin.js");
+    if (!fs.existsSync(adminBundle)) {
+        console.error("  ✗ admin bundle (dist/admin.js) not found — reinstall rastack.");
         process.exit(1);
+    }
+    const server = http.createServer((req, res) => {
+        const url = (req.url || "/").split("?")[0];
+        if (req.method !== "GET") {
+            res.writeHead(405).end("Method not allowed");
+            return;
+        }
+        if (url === "/" || url === "/index.html") {
+            res
+                .writeHead(200, { "Content-Type": "text/html; charset=utf-8" })
+                .end((0, harness_1.renderShell)("React API Stack — admin"));
+            return;
+        }
+        if (url === "/dev/admin.js")
+            return serveFile(res, adminBundle);
+        if (url.startsWith("/wasm/"))
+            return serveUnder(res, wasmDir, url.slice("/wasm/".length));
+        if (url === "/schema.rastack.json" || url === "/openapi.json")
+            return serveUnder(res, args.outDir, path.basename(url));
+        if (url.startsWith("/data/warehouse/"))
+            return serveUnder(res, args.warehouseDir, url.slice("/data/warehouse/".length));
+        res.writeHead(404).end("Not found");
     });
-    child.on("exit", (code) => process.exit(code ?? 0));
-    // Give the server a moment to bind, then print + open.
-    setTimeout(() => {
+    server.listen(args.port, () => {
+        const url = `http://localhost:${args.port}`;
+        console.log(`  ✓ WASM engine: ${path.relative(process.cwd(), wasmDir)}`);
         console.log(`\n  ▸ ${url}\n`);
         console.log("  Press Ctrl+C to stop.\n");
         if (args.open)
             openBrowser(url);
-    }, 700);
+    });
 }
 if (require.main === module) {
     main(process.argv.slice(2));

package/dist/rastack-import.js

@@ -121,7 +121,10 @@ function main() {
     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 });
+    const report = (0, import_1.validateDataset)(specs, data, {
+        relatedIds,
+        transitions: resource.transitions,
+    });
     printReport(report);
     const outPath = getArg("--out");
     if (outPath) {

package/dist/validate/adapters.js

@@ -36,6 +36,8 @@ function specFromManifestField(field) {
         spec.maxLength = field.maxLength;
     if (field.unique)
         spec.unique = true;
+    if (field.options && field.options.length > 0)
+        spec.options = field.options;
     if (field.default !== undefined)
         spec.default = field.default;
     if (field.type === "fk" && field.relation)

package/dist/validate/index.d.ts

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

package/dist/validate/index.js

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./machine"), exports);
 __exportStar(require("./adapters"), exports);
+__exportStar(require("./transitions"), exports);

package/dist/validate/machine.d.ts

@@ -34,7 +34,15 @@
  * single keystroke — passes through them untouched, exactly like the server,
  * where uniqueness and FK existence are checked against the table, not the
  * payload.
+ *
+ * Record machines add one **record-level** gate on top of the per-field
+ * chains: `transition`. A resource that declares a `transitions` block gets
+ * its state-field writes guarded against the declared edges (with the
+ * persisted row supplied via `ctx.previous`), so an illegal state jump fails
+ * a form, an import row, and a server write with the same message — see
+ * `./transitions.ts`.
  */
+import type { TransitionsModel } from "../compile/model";
 /** The `{ app, model }` a foreign-key field points at. */
 export interface SpecRelation {
     app: string;
@@ -107,6 +115,12 @@ export interface ValidationContext {
     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 persisted row this record updates (the record-level `transition`
+     * guard). Absent = create semantics: the state field must hold the initial
+     * state. Only consulted by record machines compiled with a transitions block.
+     */
+    previous?: Record<string, unknown>;
 }
 /** The result of running a value through a field machine. */
 export interface FieldRun {
@@ -144,11 +158,18 @@ export declare function runFieldMachine(machine: FieldMachine, rawValue: unknown
 /** A record machine is the composition of its fields' machines. */
 export interface RecordMachine {
     fields: FieldMachine[];
+    /**
+     * The resource's declarative state machine, when it declares one. Runs as a
+     * record-level gate after the per-field gates: a write that moves the state
+     * field without a declared edge fails at the `transition` gate.
+     */
+    transitions?: TransitionsModel;
 }
 /** One field's failure inside a record run. */
 export interface RecordError {
     field: string;
-    gate: FieldState;
+    /** The gate that rejected the value — a field gate, or the record-level `transition` gate. */
+    gate: FieldState | "transition";
     constraint: string;
     message: string;
 }
@@ -161,7 +182,7 @@ export interface RecordRun {
     fields: Record<string, FieldRun>;
     errors: RecordError[];
 }
-export declare function compileRecordMachine(specs: FieldSpec[]): RecordMachine;
+export declare function compileRecordMachine(specs: FieldSpec[], transitions?: TransitionsModel): 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

package/dist/validate/machine.js

@@ -35,6 +35,13 @@
  * single keystroke — passes through them untouched, exactly like the server,
  * where uniqueness and FK existence are checked against the table, not the
  * payload.
+ *
+ * Record machines add one **record-level** gate on top of the per-field
+ * chains: `transition`. A resource that declares a `transitions` block gets
+ * its state-field writes guarded against the declared edges (with the
+ * persisted row supplied via `ctx.previous`), so an illegal state jump fails
+ * a form, an import row, and a server write with the same message — see
+ * `./transitions.ts`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GATE_ORDER = void 0;
@@ -44,6 +51,7 @@ exports.runFieldMachine = runFieldMachine;
 exports.compileRecordMachine = compileRecordMachine;
 exports.runRecordMachine = runRecordMachine;
 exports.createDatasetContext = createDatasetContext;
+const transitions_1 = require("./transitions");
 /** The intermediate (gate) states, in canonical machine order. */
 exports.GATE_ORDER = [
     "present",
@@ -300,8 +308,11 @@ function runFieldMachine(machine, rawValue, ctx = EMPTY_CTX) {
     path.push("valid");
     return { state: "valid", path, value };
 }
-function compileRecordMachine(specs) {
-    return { fields: specs.map(compileFieldMachine) };
+function compileRecordMachine(specs, transitions) {
+    const machine = { fields: specs.map(compileFieldMachine) };
+    if (transitions)
+        machine.transitions = transitions;
+    return machine;
 }
 function runRecordMachine(machine, record, ctx = EMPTY_CTX) {
     const fields = {};
@@ -316,6 +327,28 @@ function runRecordMachine(machine, record, ctx = EMPTY_CTX) {
             errors.push({ field: name, ...run.failed });
         }
     }
+    // The record-level `transition` gate: with the per-field gates passed, a
+    // state-field change must follow a declared edge (against `ctx.previous`;
+    // no previous row = create semantics). A field-level failure on the state
+    // field already explains itself, so the gate only runs when that field is
+    // clean — one error per cause, like every other gate.
+    const transitions = machine.transitions;
+    if (transitions && !fields[transitions.field]?.failed) {
+        // Guard against what was actually submitted: an absent state field is not
+        // a transition, but the field machine defaults it in `values`.
+        const submitted = record[transitions.field] === undefined
+            ? {}
+            : { [transitions.field]: values[transitions.field] };
+        const guard = (0, transitions_1.transitionGuard)(transitions, ctx.previous, submitted);
+        if (!guard.ok) {
+            errors.push({
+                field: transitions.field,
+                gate: "transition",
+                constraint: `transitions: ${(0, transitions_1.describeTransitions)(transitions).join("; ")}`,
+                message: guard.message,
+            });
+        }
+    }
     return {
         state: errors.length === 0 ? "valid" : "invalid",
         values,

package/dist/validate/transitions.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Declarative state transitions — the record-level layer of the constraint
+ * state machine.
+ *
+ * A resource opts in with a `transitions` block (on `resource()` options, or a
+ * `static transitions` on an entity class):
+ *
+ * ```ts
+ * transitions: {
+ *   field: "status",
+ *   states: ["scheduled", "boarding", "departed", "cancelled"],
+ *   initial: "scheduled",
+ *   on: {
+ *     board:  { from: "scheduled", to: "boarding" },
+ *     depart: { from: "boarding",  to: "departed" },
+ *     cancel: { from: ["scheduled", "boarding"], to: "cancelled",
+ *               set: { gate: null } },
+ *   },
+ * }
+ * ```
+ *
+ * The block compiles into the manifest verbatim (with `from` normalised to a
+ * list), and this module is the *shared executable form* of it: the same pure
+ * functions guard a form submit (`useForm(...).transition("board")`), the
+ * record machine (`runRecordMachine` with a `previous` row in context), and —
+ * re-implemented 1:1 in `rastack-api-core` — every server/WASM write. A write
+ * that jumps between states without a declared edge is rejected on every
+ * surface, which is what makes a transition "a backend function that is
+ * state-machine safe": the only way to move a record between states is a
+ * named edge, and the edge's `set` patches are applied by the engine.
+ */
+import type { TransitionEdgeModel, TransitionsModel } from "../compile/model";
+export type { TransitionEdgeModel, TransitionsModel } from "../compile/model";
+/** A transition available from a given state, ready for a UI action list. */
+export interface AvailableTransition {
+    name: string;
+    to: string;
+    set?: Record<string, unknown>;
+}
+/** The outcome of a transition guard or application. */
+export type TransitionResult = {
+    ok: true;
+    patch: Record<string, unknown>;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Normalise a raw (authored) transitions block into the canonical model shape:
+ * `from` becomes a string list, non-string states are dropped, and anything
+ * structurally broken yields `undefined` (the compiler then reports it).
+ */
+export declare function normalizeTransitions(raw: unknown): TransitionsModel | undefined;
+/**
+ * Sanity-check a transitions block against its resource's fields. Returns
+ * human-readable problems (empty = valid); the compiler surfaces each as an
+ * error diagnostic, mirroring the circular-dependency check.
+ */
+export declare function transitionProblems(transitions: TransitionsModel, fields: Array<{
+    name: string;
+}>): string[];
+/** The state a record is in — its state-field value, else the initial state. */
+export declare function currentState(transitions: TransitionsModel, record: Record<string, unknown> | undefined): string | undefined;
+/** Every transition that may fire from `state` — the form's action list. */
+export declare function allowedTransitions(transitions: TransitionsModel, state: unknown): AvailableTransition[];
+/** The declared edge covering `from → to`, if any. */
+export declare function findTransition(transitions: TransitionsModel, from: string, to: string): {
+    name: string;
+    edge: TransitionEdgeModel;
+} | undefined;
+/**
+ * Guard one write. `previous` is the persisted row (`undefined` = create).
+ * A create must start at the initial state; an update that changes the state
+ * field must follow a declared edge. Anything else passes untouched — the
+ * guard constrains only the state field.
+ */
+export declare function transitionGuard(transitions: TransitionsModel, previous: Record<string, unknown> | undefined, next: Record<string, unknown>): TransitionResult;
+/**
+ * Fire a *named* transition from a record's current state: validates the edge
+ * is available and returns the full patch to write — the state change plus the
+ * edge's `set` effects. This is the client half of the backend function; the
+ * server re-derives the same patch from the same manifest.
+ */
+export declare function applyTransition(transitions: TransitionsModel, name: string, record: Record<string, unknown> | undefined): TransitionResult;
+/** Human-readable edge list — `"board: scheduled → boarding"` — for UI hints. */
+export declare function describeTransitions(transitions: TransitionsModel): string[];