rastack 0.0.49 → 0.0.51

package/dist/compile/analyze.d.ts

@@ -1,5 +1,7 @@
 import * as ts from "typescript";
 import { ResourceModel } from "./model";
+import type { EntityTypeExport } from "./entities";
+export { applyTransitions } from "../define/manifest";
 /**
  * Statically analyse resource definitions and produce the canonical model.
  *
@@ -10,3 +12,21 @@ import { ResourceModel } from "./model";
  * the value — the relation is read straight out of the type system.
  */
 export declare function analyze(program: ts.Program, fileNames: string[]): ResourceModel[];
+/**
+ * Analyse the DSL surface, also collecting where each `resource()` const
+ * lives — `export const Flight = resource(…)` registers in the emitted
+ * `rastack-env.d.ts` as `RowOf<typeof Flight>`, so string references
+ * (`useData("airports.flight")`) infer rows for DSL resources too.
+ */
+export declare function analyzeDsl(program: ts.Program, fileNames: string[]): {
+    resources: ResourceModel[];
+    types: EntityTypeExport[];
+};
+/**
+ * Evaluate a *static literal* AST node (string/number/bool/null/array/object)
+ * into a JS value. Anything non-literal (a function, an identifier) yields
+ * `undefined` — the options and constraint blocks are always literals.
+ * Exported for the class-entity analyser, which reads `static transitions`
+ * blocks with the same evaluator.
+ */
+export declare function literalToValue(node: ts.Expression | undefined): any;

package/dist/compile/analyze.js

@@ -33,9 +33,20 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyTransitions = void 0;
 exports.analyze = analyze;
+exports.analyzeDsl = analyzeDsl;
+exports.literalToValue = literalToValue;
+const path = __importStar(require("path"));
 const ts = __importStar(require("typescript"));
 const program_1 = require("./program");
+const manifest_1 = require("../define/manifest");
+// The option normalisers live beside the runtime manifest builder
+// (`define/manifest.ts`) and are shared with it, so a manifest built from
+// runtime `resource()` values and one compiled from the same source can
+// never disagree. Re-exported here for existing importers.
+var manifest_2 = require("../define/manifest");
+Object.defineProperty(exports, "applyTransitions", { enumerable: true, get: function () { return manifest_2.applyTransitions; } });
 /**
  * Statically analyse resource definitions and produce the canonical model.
  *
@@ -46,21 +57,54 @@ const program_1 = require("./program");
  * the value — the relation is read straight out of the type system.
  */
 function analyze(program, fileNames) {
+    return analyzeDsl(program, fileNames).resources;
+}
+/**
+ * Analyse the DSL surface, also collecting where each `resource()` const
+ * lives — `export const Flight = resource(…)` registers in the emitted
+ * `rastack-env.d.ts` as `RowOf<typeof Flight>`, so string references
+ * (`useData("airports.flight")`) infer rows for DSL resources too.
+ */
+function analyzeDsl(program, fileNames) {
     const checker = program.getTypeChecker();
     const resources = [];
+    const types = [];
     for (const sourceFile of (0, program_1.resourceSourceFiles)(program, fileNames)) {
         ts.forEachChild(sourceFile, function walk(node) {
             if (isResourceCall(node)) {
                 const model = analyzeResourceCall(node, checker);
-                if (model)
+                if (model) {
                     resources.push(model);
+                    const constExport = resourceConstExport(node);
+                    if (constExport) {
+                        types.push({ key: `${model.app}.${model.model}`, ...constExport });
+                    }
+                }
             }
             ts.forEachChild(node, walk);
         });
     }
     // Deterministic order: app, then model.
     resources.sort((a, b) => a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app));
-    return resources;
+    types.sort((a, b) => a.key.localeCompare(b.key));
+    return { resources, types };
+}
+/** The `const X = resource(…)` binding a resource call is assigned to. */
+function resourceConstExport(call) {
+    const decl = call.parent;
+    if (!ts.isVariableDeclaration(decl) || !ts.isIdentifier(decl.name)) {
+        return undefined;
+    }
+    const statement = decl.parent?.parent;
+    const exported = !!statement &&
+        ts.isVariableStatement(statement) &&
+        !!ts.getModifiers(statement)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+    return {
+        typeName: decl.name.text,
+        fileName: path.resolve(call.getSourceFile().fileName),
+        exported,
+        kind: "resourceConst",
+    };
 }
 function isResourceCall(node) {
     return (ts.isCallExpression(node) &&
@@ -96,18 +140,20 @@ function analyzeResourceCall(call, checker) {
         }
     }
     const options = literalToValue(call.arguments[3]) ?? {};
-    return {
+    const resource = {
         app,
         model,
         fields,
         relations,
-        sync: normaliseSync(options.sync),
-        admin: normaliseAdmin(options.admin),
+        sync: (0, manifest_1.normaliseSync)(options.sync),
+        admin: (0, manifest_1.normaliseAdmin)(options.admin),
         search: options.search,
         ordering: options.ordering,
         permission: options.permission,
-        access: normaliseAccess(options.access),
+        access: (0, manifest_1.normaliseAccess)(options.access),
     };
+    (0, manifest_1.applyTransitions)(resource, options.transitions);
+    return resource;
 }
 /**
  * Resolve a single field from its initializer. FK detection is type-driven:
@@ -176,10 +222,18 @@ function propertyName(name) {
  * Evaluate a *static literal* AST node (string/number/bool/null/array/object)
  * into a JS value. Anything non-literal (a function, an identifier) yields
  * `undefined` — the options and constraint blocks are always literals.
+ * Exported for the class-entity analyser, which reads `static transitions`
+ * blocks with the same evaluator.
  */
 function literalToValue(node) {
     if (!node)
         return undefined;
+    // Look through `as const` / `satisfies` / parens — the value is unchanged.
+    if (ts.isAsExpression(node) ||
+        ts.isSatisfiesExpression(node) ||
+        ts.isParenthesizedExpression(node)) {
+        return literalToValue(node.expression);
+    }
     if (ts.isStringLiteralLike(node))
         return node.text;
     if (ts.isNumericLiteral(node))
@@ -211,46 +265,3 @@ function literalToValue(node) {
     }
     return undefined;
 }
-function normaliseSync(sync) {
-    if (!sync || typeof sync !== "object")
-        return undefined;
-    const mode = sync.mode === "local" ? "local" : "server";
-    if (mode === "server" && !sync.confirmed) {
-        // A bare server resource carries no sync semantics.
-        return undefined;
-    }
-    const model = { mode };
-    if (typeof sync.scope === "string")
-        model.scope = sync.scope;
-    if (Array.isArray(sync.confirmed))
-        model.confirmed = sync.confirmed;
-    if (sync.load === "lazy")
-        model.load = "lazy";
-    if (sync.clientIds === true)
-        model.clientIds = true;
-    return model;
-}
-function normaliseAccess(access) {
-    if (!access || typeof access !== "object")
-        return undefined;
-    const model = {};
-    if (typeof access.ownerField === "string")
-        model.ownerField = access.ownerField;
-    if (access.scope === "owner" || access.scope === "shared") {
-        model.scope = access.scope;
-    }
-    if (Array.isArray(access.adminGroups)) {
-        model.adminGroups = access.adminGroups.filter((g) => typeof g === "string");
-    }
-    return Object.keys(model).length ? model : undefined;
-}
-function normaliseAdmin(admin) {
-    if (admin === false)
-        return false;
-    if (!admin || typeof admin !== "object")
-        return undefined;
-    const model = {};
-    if (Array.isArray(admin.listDisplay))
-        model.listDisplay = admin.listDisplay;
-    return model;
-}

package/dist/compile/entities.d.ts

@@ -4,9 +4,28 @@ export interface EntityDiagnostic {
     severity: "error" | "warning";
     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 declare function analyzeEntities(program: ts.Program, fileNames: string[]): EntityAnalysis;
 /**

package/dist/compile/entities.js

@@ -38,6 +38,7 @@ exports.detectCycles = detectCycles;
 const path = __importStar(require("path"));
 const ts = __importStar(require("typescript"));
 const program_1 = require("./program");
+const analyze_1 = require("./analyze");
 function analyzeEntities(program, fileNames) {
     const checker = program.getTypeChecker();
     const diagnostics = [];
@@ -65,13 +66,39 @@ function analyzeEntities(program, fileNames) {
             roots.push(decl);
         }
     };
+    // Names of every candidate, for string-argument rooting.
+    const candidateNaming = new Map();
+    const namingOf = (decl) => {
+        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);
@@ -112,9 +139,17 @@ function analyzeEntities(program, fileNames) {
     // 3. Build the canonical models.
     const namingByDecl = new Map(included.map((decl) => [decl, entityNaming(decl)]));
     const resources = [];
+    const types = [];
     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 = [];
         const relations = [];
         for (const prop of analyzed(decl)) {
@@ -146,30 +181,69 @@ function analyzeEntities(program, fileNames) {
                 fields.push(prop.field);
             }
         }
-        resources.push({
+        const resource = {
             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.
+        (0, analyze_1.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) {
+    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 (0, analyze_1.literalToValue)(member.initializer);
+        }
+    }
+    return undefined;
 }
 // -- hooks -------------------------------------------------------------------
-/** A React-style hook call: `useX(...)` or `obj.useX(...)` with type args. */
-function isHookCall(call) {
-    if (!call.typeArguments?.length)
-        return false;
+/** The `useX` name of a call's callee, if it is hook-shaped. */
+function hookCalleeName(call) {
     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) {
+    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) {
+    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. */
 function entityBehindTypeNode(node, checker, scanned) {

package/dist/compile/index.d.ts

@@ -1,10 +1,10 @@
-import { EntityDiagnostic } from "./entities";
+import { EntityDiagnostic, EntityTypeExport } from "./entities";
 import { Manifest, ResourceModel } from "./model";
-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 {
     manifest: Manifest;
@@ -25,6 +25,8 @@ export declare 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[];
 }
 /**
  * Analyse a project into the canonical model: explicit `resource()` DSL
@@ -35,10 +37,27 @@ export interface ProjectAnalysis {
  * the merged FK graph.
  */
 export declare function analyzeProject(input: string): ProjectAnalysis;
+/**
+ * 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 declare function detectTransitionProblems(resources: ResourceModel[]): EntityDiagnostic[];
 /** Analyse resource definitions into the canonical model (no file output). */
 export declare function analyzeResources(input: string): ResourceModel[];
 /** Compile resource definitions to a manifest + OpenAPI, writing both to disk. */
 export declare function compile(input: string, outDir: string): CompileResult;
+/**
+ * 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 declare function buildEntityRegistryDts(types: EntityTypeExport[], outDir: string): string | undefined;
 /** Detect duplicate `app.model` definitions and dangling FK targets. */
 export declare function collisions(resources: ResourceModel[]): string[];
 export declare function urlsFor(resources: ResourceModel[]): string[];

package/dist/compile/index.js

@@ -36,11 +36,13 @@ 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 });
-exports.buildOpenApi = exports.buildManifest = exports.detectCycles = exports.analyzeEntities = exports.analyze = void 0;
+exports.writeSchema = exports.buildOpenApi = exports.buildManifest = exports.detectCycles = exports.analyzeEntities = exports.analyzeDsl = exports.analyze = void 0;
 exports.resolveResourceFiles = resolveResourceFiles;
 exports.analyzeProject = analyzeProject;
+exports.detectTransitionProblems = detectTransitionProblems;
 exports.analyzeResources = analyzeResources;
 exports.compile = compile;
+exports.buildEntityRegistryDts = buildEntityRegistryDts;
 exports.collisions = collisions;
 exports.urlsFor = urlsFor;
 const fs = __importStar(require("fs"));
@@ -50,8 +52,10 @@ const entities_1 = require("./entities");
 const manifest_1 = require("./manifest");
 const openapi_1 = require("./openapi");
 const program_1 = require("./program");
+const transitions_1 = require("../validate/transitions");
 var analyze_2 = require("./analyze");
 Object.defineProperty(exports, "analyze", { enumerable: true, get: function () { return analyze_2.analyze; } });
+Object.defineProperty(exports, "analyzeDsl", { enumerable: true, get: function () { return analyze_2.analyzeDsl; } });
 var entities_2 = require("./entities");
 Object.defineProperty(exports, "analyzeEntities", { enumerable: true, get: function () { return entities_2.analyzeEntities; } });
 Object.defineProperty(exports, "detectCycles", { enumerable: true, get: function () { return entities_2.detectCycles; } });
@@ -59,6 +63,7 @@ var manifest_2 = require("./manifest");
 Object.defineProperty(exports, "buildManifest", { enumerable: true, get: function () { return manifest_2.buildManifest; } });
 var openapi_2 = require("./openapi");
 Object.defineProperty(exports, "buildOpenApi", { enumerable: true, get: function () { return openapi_2.buildOpenApi; } });
+Object.defineProperty(exports, "writeSchema", { enumerable: true, get: function () { return openapi_2.writeSchema; } });
 __exportStar(require("./model"), exports);
 /** Directories never worth walking for resource definitions. */
 const IGNORE_DIRS = new Set([
@@ -112,26 +117,57 @@ function resolveResourceFiles(input) {
 function analyzeProject(input) {
     const files = resolveResourceFiles(input);
     const program = (0, program_1.createProgram)(files);
-    const fromDsl = (0, analyze_1.analyze)(program, files);
+    const fromDsl = (0, analyze_1.analyzeDsl)(program, files);
     const fromInterfaces = (0, entities_1.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, ...(0, entities_1.detectCycles)(resources)],
+        types,
+        diagnostics: [
+            ...fromInterfaces.diagnostics,
+            ...(0, entities_1.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.
+ */
+function detectTransitionProblems(resources) {
+    const diagnostics = [];
+    for (const r of resources) {
+        if (!r.transitions)
+            continue;
+        for (const problem of (0, transitions_1.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). */
 function analyzeResources(input) {
     return analyzeProject(input).resources;
 }
 /** Compile resource definitions to a manifest + OpenAPI, writing both to disk. */
 function compile(input, outDir) {
-    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"));
@@ -143,7 +179,50 @@ function compile(input, outDir) {
     const openapiPath = path.join(outDir, "openapi.json");
     fs.writeFileSync(manifestPath, (0, manifest_1.manifestToJson)(manifest), { flag: "w" });
     fs.writeFileSync(openapiPath, (0, openapi_1.openApiToJson)(openapi), { flag: "w" });
-    return { manifest, openapi, files: [manifestPath, openapiPath], diagnostics };
+    const files = [manifestPath, openapiPath];
+    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.
+ */
+function buildEntityRegistryDts(types, outDir) {
+    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`) -----------
 /** Detect duplicate `app.model` definitions and dangling FK targets. */

package/dist/compile/model.d.ts

@@ -17,6 +17,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;
 }
@@ -48,6 +54,37 @@ export interface AccessModel {
     scope?: "owner" | "shared";
     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;
@@ -59,6 +96,7 @@ export interface ResourceModel {
     ordering?: string[];
     permission?: string;
     access?: AccessModel;
+    transitions?: TransitionsModel;
 }
 export interface Manifest {
     version: 1;

package/dist/compile/openapi.d.ts

@@ -10,3 +10,12 @@ import { ResourceModel } from "./model";
  */
 export declare function buildOpenApi(resources: ResourceModel[]): any;
 export declare function openApiToJson(doc: any): string;
+/**
+ * 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 declare function writeSchema(resource: ResourceModel, patched: boolean): any;