rastack 0.0.49 → 0.0.50

package/src/compile/entities.ts

@@ -2,6 +2,7 @@ import * as path from "path";
 import * as ts from "typescript";
 import { FieldModel, RelationModel, ResourceModel, ScalarType } from "./model";
 import { resourceSourceFiles } from "./program";
+import { applyTransitions, literalToValue } from "./analyze";
 
 /**
  * Type-driven resource inference — "the entities in the app are a list of
@@ -70,9 +71,29 @@ export interface EntityDiagnostic {
   message: string;
 }
 
+/**
+ * Where one entity's TypeScript type lives — what `rastack compile` needs to
+ * emit the `rastack-env.d.ts` registry (`"app.model"` → `import("…").Name`)
+ * that lets `useData("app.model")` infer its rows with no type argument.
+ */
+export interface EntityTypeExport {
+  /** `"app.model"`. */
+  key: string;
+  /** The declared class/interface name (or DSL const name). */
+  typeName: string;
+  /** Absolute path of the declaring source file. */
+  fileName: string;
+  /** Whether the declaration is exported (unexported types can't register). */
+  exported: boolean;
+  /** DSL consts register as `RowOf<typeof X>` rather than the type itself. */
+  kind: "type" | "resourceConst";
+}
+
 export interface EntityAnalysis {
   resources: ResourceModel[];
   diagnostics: EntityDiagnostic[];
+  /** Registry entries for the class/interface entities. */
+  types: EntityTypeExport[];
 }
 
 export function analyzeEntities(
@@ -105,12 +126,39 @@ export function analyzeEntities(
       roots.push(decl);
     }
   };
+  // Names of every candidate, for string-argument rooting.
+  const candidateNaming = new Map<EntityDecl, EntityNaming>();
+  const namingOf = (decl: EntityDecl): EntityNaming => {
+    let naming = candidateNaming.get(decl);
+    if (!naming) {
+      naming = entityNaming(decl);
+      candidateNaming.set(decl, naming);
+    }
+    return naming;
+  };
+
   for (const sf of sourceFiles) {
     ts.forEachChild(sf, function walk(node) {
-      if (ts.isCallExpression(node) && isHookCall(node)) {
-        for (const typeArg of node.typeArguments ?? []) {
-          const decl = entityBehindTypeNode(typeArg, checker, scanned);
-          if (decl && candidates.has(decl)) addRoot(decl);
+      if (ts.isCallExpression(node)) {
+        if (isHookCall(node)) {
+          for (const typeArg of node.typeArguments ?? []) {
+            const decl = entityBehindTypeNode(typeArg, checker, scanned);
+            if (decl && candidates.has(decl)) addRoot(decl);
+          }
+        }
+        // `useData("airports.terminal")` — the manifest-key string names the
+        // entity, so it roots the declaration exactly like a type argument
+        // would: the compiler resolves the dotted key against the same naming
+        // it compiles. (Only the dotted form roots — a bare string argument to
+        // some `use*` hook is far too often not an entity key.)
+        const key = hookEntityKeyArg(node);
+        if (key) {
+          for (const decl of candidates) {
+            const naming = namingOf(decl);
+            if (naming.app === key.app && naming.model === key.model) {
+              addRoot(decl);
+            }
+          }
         }
       }
       ts.forEachChild(node, walk);
@@ -153,9 +201,17 @@ export function analyzeEntities(
     included.map((decl) => [decl, entityNaming(decl)] as const),
   );
   const resources: ResourceModel[] = [];
+  const types: EntityTypeExport[] = [];
   for (const decl of included) {
     const naming = namingByDecl.get(decl)!;
     const key = `${naming.app}.${naming.model}`;
+    types.push({
+      key,
+      typeName: decl.name!.text,
+      fileName: path.resolve(decl.getSourceFile().fileName),
+      exported: !!(ts.getCombinedModifierFlags(decl) & ts.ModifierFlags.Export),
+      kind: "type",
+    });
     const fields: FieldModel[] = [];
     const relations: RelationModel[] = [];
 
@@ -185,34 +241,78 @@ export function analyzeEntities(
       }
     }
 
-    resources.push({
+    const resource: ResourceModel = {
       app: naming.app,
       model: naming.model,
       fields,
       relations,
       search: naming.search,
       permission: naming.permission,
-    });
+    };
+    // A class may declare its state machine inline: `static transitions =
+    // {...}`. Statics are never columns, so the block rides alongside the
+    // data properties — the class-authored twin of the DSL option.
+    applyTransitions(resource, staticTransitions(decl));
+    resources.push(resource);
   }
 
   resources.sort((a, b) =>
     a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app),
   );
-  return { resources, diagnostics };
+  return { resources, diagnostics, types };
+}
+
+/**
+ * The literal value of a class's `static transitions = {...}` block, when
+ * declared. Only static object literals qualify — the block is data, exactly
+ * like the DSL option, and is evaluated with the same literal evaluator.
+ */
+function staticTransitions(decl: EntityDecl): unknown {
+  if (!ts.isClassDeclaration(decl)) return undefined;
+  for (const member of decl.members) {
+    if (
+      ts.isPropertyDeclaration(member) &&
+      ts.getCombinedModifierFlags(member) & ts.ModifierFlags.Static &&
+      (ts.isIdentifier(member.name) || ts.isStringLiteralLike(member.name)) &&
+      member.name.text === "transitions" &&
+      member.initializer
+    ) {
+      return literalToValue(member.initializer);
+    }
+  }
+  return undefined;
 }
 
 // -- hooks -------------------------------------------------------------------
 
-/** A React-style hook call: `useX(...)` or `obj.useX(...)` with type args. */
-function isHookCall(call: ts.CallExpression): boolean {
-  if (!call.typeArguments?.length) return false;
+/** The `useX` name of a call's callee, if it is hook-shaped. */
+function hookCalleeName(call: ts.CallExpression): string | undefined {
   const callee = call.expression;
   const name = ts.isIdentifier(callee)
     ? callee.text
     : ts.isPropertyAccessExpression(callee)
       ? callee.name.text
       : undefined;
-  return !!name && /^use[A-Z0-9_]/.test(name);
+  return name && /^use[A-Z0-9_]/.test(name) ? name : undefined;
+}
+
+/** A React-style hook call: `useX(...)` or `obj.useX(...)` with type args. */
+function isHookCall(call: ts.CallExpression): boolean {
+  if (!call.typeArguments?.length) return false;
+  return hookCalleeName(call) !== undefined;
+}
+
+const ENTITY_KEY_RE = /^([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)$/;
+
+/** The `{ app, model }` of a hook call's first-argument entity-key string. */
+function hookEntityKeyArg(
+  call: ts.CallExpression,
+): { app: string; model: string } | undefined {
+  if (!hookCalleeName(call)) return undefined;
+  const first = call.arguments[0];
+  if (!first || !ts.isStringLiteralLike(first)) return undefined;
+  const match = ENTITY_KEY_RE.exec(first.text);
+  return match ? { app: match[1], model: match[2] } : undefined;
 }
 
 /** Resolve a type node to a class/interface declared in a scanned file. */

package/src/compile/index.ts

@@ -1,17 +1,27 @@
 import * as fs from "fs";
 import * as path from "path";
-import { analyze } from "./analyze";
-import { analyzeEntities, detectCycles, EntityDiagnostic } from "./entities";
+import { analyze, analyzeDsl } from "./analyze";
+import {
+  analyzeEntities,
+  detectCycles,
+  EntityDiagnostic,
+  EntityTypeExport,
+} from "./entities";
 import { buildManifest, manifestToJson } from "./manifest";
 import { Manifest, ResourceModel } from "./model";
 import { buildOpenApi, openApiToJson } from "./openapi";
 import { createProgram } from "./program";
+import { transitionProblems } from "../validate/transitions";
 
-export { analyze } from "./analyze";
+export { analyze, analyzeDsl } from "./analyze";
 export { analyzeEntities, detectCycles } from "./entities";
-export type { EntityAnalysis, EntityDiagnostic } from "./entities";
+export type {
+  EntityAnalysis,
+  EntityDiagnostic,
+  EntityTypeExport,
+} from "./entities";
 export { buildManifest } from "./manifest";
-export { buildOpenApi } from "./openapi";
+export { buildOpenApi, writeSchema } from "./openapi";
 export * from "./model";
 
 export interface CompileResult {
@@ -64,6 +74,8 @@ export function resolveResourceFiles(input: string): string[] {
 export interface ProjectAnalysis {
   resources: ResourceModel[];
   diagnostics: EntityDiagnostic[];
+  /** Where each entity's TS type lives — the `rastack-env.d.ts` registry input. */
+  types: EntityTypeExport[];
 }
 
 /**
@@ -78,24 +90,58 @@ export function analyzeProject(input: string): ProjectAnalysis {
   const files = resolveResourceFiles(input);
   const program = createProgram(files);
 
-  const fromDsl = analyze(program, files);
+  const fromDsl = analyzeDsl(program, files);
   const fromInterfaces = analyzeEntities(program, files);
 
-  const defined = new Set(fromDsl.map((r) => `${r.app}.${r.model}`));
+  const defined = new Set(fromDsl.resources.map((r) => `${r.app}.${r.model}`));
   const resources = [
-    ...fromDsl,
+    ...fromDsl.resources,
     ...fromInterfaces.resources.filter((r) => !defined.has(`${r.app}.${r.model}`)),
   ];
   resources.sort((a, b) =>
     a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app),
   );
 
+  // Registry entries follow the same merge rule as the resources: the DSL
+  // definition wins an `app.model` collision.
+  const types = [
+    ...fromDsl.types,
+    ...fromInterfaces.types.filter((t) => !defined.has(t.key)),
+  ].sort((a, b) => a.key.localeCompare(b.key));
+
   return {
     resources,
-    diagnostics: [...fromInterfaces.diagnostics, ...detectCycles(resources)],
+    types,
+    diagnostics: [
+      ...fromInterfaces.diagnostics,
+      ...detectCycles(resources),
+      ...detectTransitionProblems(resources),
+    ],
   };
 }
 
+/**
+ * Validate every resource's `transitions` block against its own fields and
+ * state set — an edge to an undeclared state, an unknown state field, or a
+ * `set` patch targeting a non-field are authoring errors, caught at compile
+ * time like a circular FK.
+ */
+export function detectTransitionProblems(
+  resources: ResourceModel[],
+): EntityDiagnostic[] {
+  const diagnostics: EntityDiagnostic[] = [];
+  for (const r of resources) {
+    if (!r.transitions) continue;
+    for (const problem of transitionProblems(r.transitions, r.fields)) {
+      diagnostics.push({
+        severity: "error",
+        message: `${r.app}.${r.model}: ${problem}`,
+      });
+    }
+  }
+  return diagnostics;
+}
+
 /** Analyse resource definitions into the canonical model (no file output). */
 export function analyzeResources(input: string): ResourceModel[] {
   return analyzeProject(input).resources;
@@ -103,7 +149,7 @@ export function analyzeResources(input: string): ResourceModel[] {
 
 /** Compile resource definitions to a manifest + OpenAPI, writing both to disk. */
 export function compile(input: string, outDir: string): CompileResult {
-  const { resources, diagnostics } = analyzeProject(input);
+  const { resources, diagnostics, types } = analyzeProject(input);
   const errors = diagnostics.filter((d) => d.severity === "error");
   if (errors.length) {
     throw new Error(errors.map((e) => e.message).join("\n"));
@@ -116,8 +162,59 @@ export function compile(input: string, outDir: string): CompileResult {
   const openapiPath = path.join(outDir, "openapi.json");
   fs.writeFileSync(manifestPath, manifestToJson(manifest), { flag: "w" });
   fs.writeFileSync(openapiPath, openApiToJson(openapi), { flag: "w" });
+  const files = [manifestPath, openapiPath];
 
-  return { manifest, openapi, files: [manifestPath, openapiPath], diagnostics };
+  const registryDts = buildEntityRegistryDts(types, outDir);
+  if (registryDts) {
+    const registryPath = path.join(outDir, "rastack-env.d.ts");
+    fs.writeFileSync(registryPath, registryDts, { flag: "w" });
+    files.push(registryPath);
+  }
+
+  return { manifest, openapi, files, diagnostics };
+}
+
+/**
+ * The `rastack-env.d.ts` the compiler emits beside the manifest: a types-only
+ * declaration-merge of `rastack/hooks/registry`'s `EntityTypes`, mapping every
+ * exported entity's `"app.model"` key to *your own* type — classes and
+ * interfaces directly, `resource()` consts through `RowOf<typeof X>`. With
+ * this file in the program, `useData("airports.terminal")` infers its rows
+ * with no type argument. Unexported declarations can't be imported and are
+ * skipped. Returns `undefined` when there is nothing to register.
+ */
+export function buildEntityRegistryDts(
+  types: EntityTypeExport[],
+  outDir: string,
+): string | undefined {
+  const entries = types.filter((t) => t.exported);
+  if (!entries.length) return undefined;
+
+  const lines = entries.map((t) => {
+    let rel = path
+      .relative(path.resolve(outDir), t.fileName)
+      .replace(/\\/g, "/")
+      .replace(/\.(tsx|ts)$/, "");
+    if (!rel.startsWith(".")) rel = `./${rel}`;
+    const type =
+      t.kind === "resourceConst"
+        ? `import("rastack/define").RowOf<typeof import("${rel}").${t.typeName}>`
+        : `import("${rel}").${t.typeName}`;
+    return `    "${t.key}": ${type};`;
+  });
+
+  return (
+    "// Generated by `rastack compile` — do not edit.\n" +
+    '// Maps manifest keys to your own entity types so `useData("app.model")` /\n' +
+    '// `useForm("app.model")` infer their rows with no type argument.\n' +
+    "// Types only: nothing to import, no runtime code.\n" +
+    'declare module "rastack/hooks/registry" {\n' +
+    "  interface EntityTypes {\n" +
+    `${lines.join("\n")}\n` +
+    "  }\n" +
+    "}\n" +
+    "export {};\n"
+  );
 }
 
 // -- introspection (replaces `manage.py rastack check|list|urls`) -----------

package/src/compile/model.ts

@@ -27,6 +27,12 @@ export interface FieldModel {
   primaryKey?: boolean;
   null?: boolean;
   default?: unknown;
+  /**
+   * The closed set of allowed values (the `member` gate / a `select` control).
+   * Stamped by the compiler — today from a `transitions` block, whose `states`
+   * become the state field's value set.
+   */
+  options?: Array<string | number>;
   /** Present iff `type === "fk"` — the resource this field points at. */
   relation?: RelationTarget;
 }
@@ -63,6 +69,39 @@ export interface AccessModel {
   adminGroups?: string[];
 }
 
+/**
+ * One edge of a resource's state machine: a named transition from one (or
+ * several) states to exactly one target state. `set` is the transition's
+ * *effect* — field patches the engine applies when the edge fires — which is
+ * what makes a transition a declarative backend function: declared once in
+ * TypeScript, compiled here, executed by `rastack-api-core` on every surface.
+ */
+export interface TransitionEdgeModel {
+  /** Source states this transition may fire from (normalised to a list). */
+  from: string[];
+  /** The state entered when the transition fires. */
+  to: string;
+  /** Field patches applied by the engine alongside the state change. */
+  set?: Record<string, unknown>;
+}
+
+/**
+ * A resource's declarative state machine, keyed off one state field. Compiled
+ * into the manifest and enforced on every write surface: the TS record machine
+ * (forms, `rastack import`) and `rastack-api-core` (server, Lambda, WASM) all
+ * reject a write that jumps between states without a declared edge.
+ */
+export interface TransitionsModel {
+  /** The field that carries the machine state. */
+  field: string;
+  /** Every state the field may hold (becomes the field's `options`). */
+  states: string[];
+  /** The state new records start in (becomes the field's default). */
+  initial?: string;
+  /** Named transitions — `on.board = { from: ["scheduled"], to: "boarding" }`. */
+  on: Record<string, TransitionEdgeModel>;
+}
+
 export interface ResourceModel {
   app: string;
   model: string;
@@ -74,6 +113,7 @@ export interface ResourceModel {
   ordering?: string[];
   permission?: string;
   access?: AccessModel;
+  transitions?: TransitionsModel;
 }
 
 export interface Manifest {

package/src/compile/openapi.ts

@@ -116,7 +116,15 @@ function readSchema(resource: ResourceModel): any {
   return { type: "object", properties, required };
 }
 
-function writeSchema(resource: ResourceModel, patched: boolean): any {
+/**
+ * The write JSON Schema for a resource — what the API accepts on
+ * create/update. Exported because the generic `useForm(Entity)` hook derives
+ * the *same* schema at runtime straight from the manifest, so a form
+ * validates against exactly the contract the emitted OpenAPI documents.
+ * Resources with a state machine carry it as `x-rastack-transitions`, the
+ * write-side twin of `x-rastack-relation`.
+ */
+export function writeSchema(resource: ResourceModel, patched: boolean): any {
   const properties: Record<string, any> = {};
   const required: string[] = [];
   for (const field of resource.fields) {
@@ -128,6 +136,9 @@ function writeSchema(resource: ResourceModel, patched: boolean): any {
   }
   const schema: any = { type: "object", properties };
   if (required.length) schema.required = required;
+  if (resource.transitions) {
+    schema["x-rastack-transitions"] = resource.transitions;
+  }
   return schema;
 }
 
@@ -156,6 +167,7 @@ function fieldProperty(field: FieldModel): any {
   }
   const base = scalarProperty(field.type);
   if (field.maxLength !== undefined) base.maxLength = field.maxLength;
+  if (field.options && field.options.length > 0) base.enum = [...field.options];
   if (field.null) base.nullable = true;
   return base;
 }

package/src/define/index.ts

@@ -23,11 +23,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.
@@ -71,23 +79,35 @@ export interface DateOptions {
  * runtime if a consumer wants it.
  */
 export const s = {
-  string(_opts?: StringOptions): Scalar<"string"> {
-    return { __rastackScalar: "string" } as Scalar<"string">;
+  string<const O extends StringOptions = StringOptions>(
+    _opts?: O,
+  ): Scalar<"string", NullOf<O>> {
+    return { __rastackScalar: "string" } as Scalar<"string", NullOf<O>>;
   },
-  int(_opts?: NumberOptions): Scalar<"int"> {
-    return { __rastackScalar: "int" } as Scalar<"int">;
+  int<const O extends NumberOptions = NumberOptions>(
+    _opts?: O,
+  ): Scalar<"int", NullOf<O>> {
+    return { __rastackScalar: "int" } as Scalar<"int", NullOf<O>>;
   },
-  float(_opts?: NumberOptions): Scalar<"float"> {
-    return { __rastackScalar: "float" } as Scalar<"float">;
+  float<const O extends NumberOptions = NumberOptions>(
+    _opts?: O,
+  ): Scalar<"float", NullOf<O>> {
+    return { __rastackScalar: "float" } as Scalar<"float", NullOf<O>>;
   },
-  bool(_opts?: BoolOptions): Scalar<"bool"> {
-    return { __rastackScalar: "bool" } as Scalar<"bool">;
+  bool<const O extends BoolOptions = BoolOptions>(
+    _opts?: O,
+  ): Scalar<"bool", NullOf<O>> {
+    return { __rastackScalar: "bool" } as Scalar<"bool", NullOf<O>>;
   },
-  datetime(_opts?: DateOptions): Scalar<"datetime"> {
-    return { __rastackScalar: "datetime" } as Scalar<"datetime">;
+  datetime<const O extends DateOptions = DateOptions>(
+    _opts?: O,
+  ): Scalar<"datetime", NullOf<O>> {
+    return { __rastackScalar: "datetime" } as Scalar<"datetime", NullOf<O>>;
   },
-  uuid(_opts?: StringOptions): Scalar<"uuid"> {
-    return { __rastackScalar: "uuid" } as Scalar<"uuid">;
+  uuid<const O extends StringOptions = StringOptions>(
+    _opts?: O,
+  ): Scalar<"uuid", NullOf<O>> {
+    return { __rastackScalar: "uuid" } as Scalar<"uuid", NullOf<O>>;
   },
   /**
    * A foreign key. The target is `() => SomeResource`; the compiler resolves
@@ -132,6 +152,54 @@ export interface AccessOptions {
   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[];
@@ -145,33 +213,44 @@ 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. */
+/** Define a resource. Capture app/model (and options) as literal types. */
 export 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: ResourceOptions = {},
-): ResourceType<App, Model, F> {
+  options: O = {} as O,
+): ResourceType<App, Model, F, O> {
   return {
     __rastack: "resource",
     __app: app,
@@ -182,3 +261,52 @@ export function resource<
     options,
   };
 }
+
+/**
+ * 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 // an `"app.model"` ref carries no type-level transition info
+      : never;
+
+// ---------------------------------------------------------------------------
+// Row inference — `useData(Flight)` knows its rows from the definition itself
+// ---------------------------------------------------------------------------
+
+type ScalarTsType<T extends string> = T extends "int" | "float"
+  ? number
+  : T extends "bool"
+    ? boolean
+    : string; // string / datetime / uuid all travel as strings
+
+/** 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 // FK values are opaque ids
+      : 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;