rastack 0.0.49 → 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-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[];

package/dist/validate/transitions.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeTransitions = normalizeTransitions;
+exports.transitionProblems = transitionProblems;
+exports.currentState = currentState;
+exports.allowedTransitions = allowedTransitions;
+exports.findTransition = findTransition;
+exports.transitionGuard = transitionGuard;
+exports.applyTransition = applyTransition;
+exports.describeTransitions = describeTransitions;
+/**
+ * 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).
+ */
+function normalizeTransitions(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const block = raw;
+    if (typeof block.field !== "string" || !block.field)
+        return undefined;
+    if (!Array.isArray(block.states))
+        return undefined;
+    const states = block.states.filter((s) => typeof s === "string");
+    if (!states.length)
+        return undefined;
+    if (!block.on || typeof block.on !== "object")
+        return undefined;
+    const on = {};
+    for (const [name, rawEdge] of Object.entries(block.on)) {
+        if (!rawEdge || typeof rawEdge !== "object")
+            continue;
+        const edge = rawEdge;
+        const from = (Array.isArray(edge.from) ? edge.from : [edge.from]).filter((s) => typeof s === "string");
+        if (!from.length || typeof edge.to !== "string")
+            continue;
+        const model = { from, to: edge.to };
+        if (edge.set && typeof edge.set === "object" && !Array.isArray(edge.set)) {
+            model.set = edge.set;
+        }
+        on[name] = model;
+    }
+    const model = { field: block.field, states, on };
+    if (typeof block.initial === "string")
+        model.initial = block.initial;
+    return model;
+}
+/**
+ * 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.
+ */
+function transitionProblems(transitions, fields) {
+    const problems = [];
+    const fieldNames = new Set(fields.map((f) => f.name));
+    const states = new Set(transitions.states);
+    if (!fieldNames.has(transitions.field)) {
+        problems.push(`transitions.field "${transitions.field}" is not a field`);
+    }
+    if (transitions.initial !== undefined && !states.has(transitions.initial)) {
+        problems.push(`initial state "${transitions.initial}" is not in states`);
+    }
+    for (const [name, edge] of Object.entries(transitions.on)) {
+        for (const from of edge.from) {
+            if (!states.has(from)) {
+                problems.push(`transition "${name}": from-state "${from}" is not in states`);
+            }
+        }
+        if (!states.has(edge.to)) {
+            problems.push(`transition "${name}": to-state "${edge.to}" is not in states`);
+        }
+        for (const key of Object.keys(edge.set ?? {})) {
+            if (key === transitions.field) {
+                problems.push(`transition "${name}": set must not patch the state field itself`);
+            }
+            else if (!fieldNames.has(key)) {
+                problems.push(`transition "${name}": set targets unknown field "${key}"`);
+            }
+        }
+    }
+    return problems;
+}
+/** The state a record is in — its state-field value, else the initial state. */
+function currentState(transitions, record) {
+    const value = record?.[transitions.field];
+    if (value !== undefined && value !== null && value !== "")
+        return String(value);
+    return transitions.initial;
+}
+/** Every transition that may fire from `state` — the form's action list. */
+function allowedTransitions(transitions, state) {
+    const from = state === undefined || state === null ? transitions.initial : String(state);
+    if (from === undefined)
+        return [];
+    return Object.entries(transitions.on)
+        .filter(([, edge]) => edge.from.includes(from))
+        .map(([name, edge]) => ({ name, to: edge.to, set: edge.set }));
+}
+/** The declared edge covering `from → to`, if any. */
+function findTransition(transitions, from, to) {
+    for (const [name, edge] of Object.entries(transitions.on)) {
+        if (edge.to === to && edge.from.includes(from))
+            return { name, edge };
+    }
+    return 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.
+ */
+function transitionGuard(transitions, previous, next) {
+    const value = next[transitions.field];
+    if (previous === undefined) {
+        // Create: absent state falls back to the initial default; a supplied state
+        // must *be* the initial state — records cannot be born mid-machine.
+        if (value === undefined || value === null || value === "") {
+            return { ok: true, patch: {} };
+        }
+        if (transitions.initial !== undefined && String(value) !== transitions.initial) {
+            return {
+                ok: false,
+                message: `${transitions.field}: new records start at "${transitions.initial}", not "${String(value)}"`,
+            };
+        }
+        return { ok: true, patch: {} };
+    }
+    // Update: an untouched (or unchanged) state field is not a transition.
+    if (value === undefined)
+        return { ok: true, patch: {} };
+    const from = currentState(transitions, previous);
+    const to = String(value);
+    if (from === to)
+        return { ok: true, patch: {} };
+    const match = from !== undefined && findTransition(transitions, from, to);
+    if (!match) {
+        return {
+            ok: false,
+            message: `${transitions.field}: no transition from "${String(from)}" to "${to}"`,
+        };
+    }
+    return { ok: true, patch: { ...match.edge.set } };
+}
+/**
+ * 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.
+ */
+function applyTransition(transitions, name, record) {
+    const edge = transitions.on[name];
+    if (!edge) {
+        return { ok: false, message: `unknown transition "${name}"` };
+    }
+    const state = currentState(transitions, record);
+    if (state === undefined || !edge.from.includes(state)) {
+        return {
+            ok: false,
+            message: `"${name}" is not available from "${String(state)}" (needs ${edge.from.join(" | ")})`,
+        };
+    }
+    return { ok: true, patch: { [transitions.field]: edge.to, ...edge.set } };
+}
+/** Human-readable edge list — `"board: scheduled → boarding"` — for UI hints. */
+function describeTransitions(transitions) {
+    return Object.entries(transitions.on).map(([name, edge]) => `${name}: ${edge.from.join(" | ")} → ${edge.to}`);
+}

package/dist/wasm/rastack_wasm.js

@@ -375,7 +375,7 @@ function __wbg_get_imports() {
             return ret;
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 80, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 85, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen_1a7aa9db5392c486___convert__closures_____invoke___wasm_bindgen_1a7aa9db5392c486___JsValue__core_7d5f0a2ba6a62c33___result__Result_____wasm_bindgen_1a7aa9db5392c486___JsError___true_);
             return ret;
         },