@substrat-run/model-emit 0.6.0 → 0.7.0

package/dist/emit-xstate.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The declared lifecycle, rendered as an XState v5 machine config (#844).
+ *
+ * One direction, and that is the design. XState's statechart *semantics* are the
+ * right vocabulary — nested states are K-17's substates exactly, and `setup()`
+ * splitting implementations out of the config is why a guard can be referenced
+ * by name here without it being a hack. Its *actor runtime* is not wanted: the
+ * state lives in a column in a scope DO, the transition happens inside the
+ * operation's transaction, and a second thing deciding transitions would be the
+ * duplication the declaration exists to delete.
+ *
+ * So this emits, and nothing here parses. The conversion is TOTAL — every valid
+ * lifecycle produces a valid machine — which is exactly what a narrow source
+ * format buys: it can refuse `invoke`, `context`, `after` and parallel regions,
+ * so the emitter never meets one.
+ *
+ * ## What it is for
+ *
+ * A **diagram** in an engine's docs page, and a **test oracle**: `xstate`'s own
+ * `machine.transition()` is a pure function, so it can stand beside
+ * `assertTransition` in a test and confirm the two agree on every state/event
+ * pair, with `xstate` never leaving devDependencies.
+ *
+ * ## What it must never become
+ *
+ * A round-trip. Editing the emitted machine in a visual editor and reading it
+ * back would make that editor a second authoring surface — the visual-builder
+ * tarpit arriving through the back door, without anyone deciding to open it. Any
+ * checked-in output of this belongs behind a `--check` re-emit, so an edit to it
+ * goes red rather than becoming the source.
+ */
+import type { EmittedLifecycle } from '@substrat-run/contracts';
+/** A guard wired in a manifest: `{ before, predicate }`, where `before` is an operation id. */
+export interface GuardWiring {
+    readonly before: string;
+    readonly predicate: string;
+}
+export interface XStateTransition {
+    readonly target: string;
+    readonly guard?: string;
+    readonly meta?: Record<string, unknown>;
+}
+export interface XStateNode {
+    readonly type?: 'final';
+    readonly on?: Record<string, XStateTransition | string>;
+    readonly meta?: Record<string, unknown>;
+}
+export interface XStateMachine {
+    readonly id: string;
+    readonly initial: string;
+    readonly states: Record<string, XStateNode>;
+}
+export interface EmitXStateOptions {
+    /**
+     * Manifest guard wirings, joined onto edges by operation id.
+     *
+     * Joined rather than declared: K-38 already puts guards in the manifest and has
+     * the kernel evaluate them before the guarded operation. Every edge names its
+     * operation, so the join key exists and a second declaration would only be a
+     * second thing to disagree.
+     */
+    readonly guards?: readonly GuardWiring[];
+}
+/**
+ * Event names are the operation ids verbatim — `workorder/complete`, not
+ * `COMPLETE`.
+ *
+ * XState imposes no naming convention, and SCREAMING_SNAKE would be a lossy
+ * rename: the diagram would stop naming the operation a reader can go and read.
+ */
+export declare function emitXState(entity: string, lifecycle: EmittedLifecycle, options?: EmitXStateOptions): XStateMachine;
+//# sourceMappingURL=emit-xstate.d.ts.map

package/dist/emit-xstate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit-xstate.d.ts","sourceRoot":"","sources":["../src/emit-xstate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,+FAA+F;AAC/F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAAC,CAAC;IACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,gBAAgB,EAC3B,OAAO,GAAE,iBAAsB,GAC9B,aAAa,CAgCf"}

package/dist/emit-xstate.js

@@ -0,0 +1,43 @@
+/**
+ * Event names are the operation ids verbatim — `workorder/complete`, not
+ * `COMPLETE`.
+ *
+ * XState imposes no naming convention, and SCREAMING_SNAKE would be a lossy
+ * rename: the diagram would stop naming the operation a reader can go and read.
+ */
+export function emitXState(entity, lifecycle, options = {}) {
+    const byOperation = new Map();
+    for (const g of options.guards ?? [])
+        byOperation.set(g.before, g.predicate);
+    const states = {};
+    for (const name of Object.keys(lifecycle.states).sort()) {
+        const state = lifecycle.states[name];
+        if (!state)
+            continue;
+        const on = {};
+        for (const op of Object.keys(state.on ?? {}).sort()) {
+            const target = state.on?.[op];
+            if (target === undefined)
+                continue;
+            const guard = byOperation.get(op);
+            on[op] = guard ? { target, guard } : target;
+        }
+        /**
+         * `allow` deliberately does NOT become a self-transition.
+         *
+         * A self-loop in XState re-enters the state and fires its entry actions. The
+         * declaration says the opposite — this operation is legal here and changes
+         * nothing. Drawing it as an edge would put a loop on the diagram for every
+         * note a technician can add to a work order, which is both wrong and
+         * unreadable. It rides in `meta`, where a renderer can list it as what it is.
+         */
+        const meta = state.allow?.length ? { allow: [...state.allow] } : undefined;
+        states[name] = {
+            ...(state.terminal ? { type: 'final' } : {}),
+            ...(Object.keys(on).length ? { on } : {}),
+            ...(meta ? { meta } : {}),
+        };
+    }
+    return { id: entity, initial: lifecycle.initial, states };
+}
+//# sourceMappingURL=emit-xstate.js.map

package/dist/emit-xstate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit-xstate.js","sourceRoot":"","sources":["../src/emit-xstate.ts"],"names":[],"mappings":"AAqEA;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CACxB,MAAc,EACd,SAA2B,EAC3B,OAAO,GAAsB,EAAE;IAE/B,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC9C,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,MAAM,IAAI,EAAE;QAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;IAE7E,MAAM,MAAM,GAA+B,EAAE,CAAC;IAC9C,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACxD,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,MAAM,EAAE,GAA8C,EAAE,CAAC;QACzD,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YACpD,MAAM,MAAM,GAAG,KAAK,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;YAC9B,IAAI,MAAM,KAAK,SAAS;gBAAE,SAAS;YACnC,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAClC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;QAC9C,CAAC;QACD;;;;;;;;WAQG;QACH,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3E,MAAM,CAAC,IAAI,CAAC,GAAG;YACb,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1B,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;AAC5D,CAAC"}

package/dist/index.d.ts

@@ -3,4 +3,5 @@ export { journalColumns, journalUniques, journalPrimaryKeys } from './journal.js
 export { readSchema, statements, type TableSchema } from './replay.js';
 export { planMigration, parseJournal, type Journal, type JournalEntry, type MigrationPlan, } from './plan.js';
 export { renderClient, ClientEmitError, tsTypeOf, methodName, type ClientConfig, } from './emit-client.js';
+export { emitXState, type EmitXStateOptions, type GuardWiring, type XStateMachine, type XStateNode, type XStateTransition, } from './emit-xstate.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,SAAS,EACT,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EACL,aAAa,EACb,YAAY,EACZ,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,UAAU,EACV,KAAK,YAAY,GAClB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,SAAS,EACT,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EACL,aAAa,EACb,YAAY,EACZ,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,UAAU,EACV,KAAK,YAAY,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -3,4 +3,5 @@ export { journalColumns, journalUniques, journalPrimaryKeys } from './journal.js
 export { readSchema, statements } from './replay.js';
 export { planMigration, parseJournal, } from './plan.js';
 export { renderClient, ClientEmitError, tsTypeOf, methodName, } from './emit-client.js';
+export { emitXState, } from './emit-xstate.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,SAAS,EACT,oBAAoB,EACpB,iBAAiB,GAGlB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,UAAU,EAAE,UAAU,EAAoB,MAAM,aAAa,CAAC;AACvE,OAAO,EACL,aAAa,EACb,YAAY,GAIb,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,UAAU,GAEX,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,SAAS,EACT,oBAAoB,EACpB,iBAAiB,GAGlB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,UAAU,EAAE,UAAU,EAAoB,MAAM,aAAa,CAAC;AACvE,OAAO,EACL,aAAa,EACb,YAAY,GAIb,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,UAAU,GAEX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,UAAU,GAMX,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@substrat-run/model-emit",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Build-time tooling over a Substrat model — DDL emitted from the entity registry, and the journal reader that holds it honest",
   "license": "Apache-2.0",
   "repository": {
@@ -22,7 +22,7 @@
     "dist"
   ],
   "dependencies": {
-    "@substrat-run/contracts": "0.83.0"
+    "@substrat-run/contracts": "0.84.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",