@zmdb/app 1.0.0-beta.1

package/src/modules/lifecycle-instances.ts

@@ -0,0 +1,23 @@
+import type { Container } from '../di/index.js';
+
+const ledgers = new WeakMap<Container, object[]>();
+
+export function createLifecycleRecorder(container: Container): (value: unknown) => void {
+  const instances: object[] = [];
+  const seen = new Set<object>();
+  ledgers.set(container, instances);
+
+  return value => {
+    if (!isObject(value) || seen.has(value)) return;
+    seen.add(value);
+    instances.push(value);
+  };
+}
+
+export function lifecycleInstances(container: Container): readonly object[] {
+  return ledgers.get(container) ?? [];
+}
+
+function isObject(value: unknown): value is object {
+  return (typeof value === 'object' && value !== null) || typeof value === 'function';
+}

package/src/modules/runtime.ts

@@ -0,0 +1,26 @@
+import type { Constructor } from '../di/index.js';
+import type { CompiledModule } from './index.js';
+
+export type CompiledController =
+  | { readonly kind: 'eager'; readonly controller: object }
+  | {
+      readonly kind: 'deferred';
+      readonly controller: Constructor<object>;
+      readonly instance: () => Promise<object>;
+    };
+
+export interface CompiledModuleRuntime {
+  readonly controllers: readonly CompiledController[];
+  beginShutdown(): void;
+  waitForLoads(): Promise<void>;
+}
+
+const runtimes = new WeakMap<CompiledModule, CompiledModuleRuntime>();
+
+export function rememberRuntime(compiled: CompiledModule, runtime: CompiledModuleRuntime): void {
+  runtimes.set(compiled, runtime);
+}
+
+export function runtimeOf(compiled: CompiledModule): CompiledModuleRuntime | undefined {
+  return runtimes.get(compiled);
+}

package/src/observability/index.ts

@@ -0,0 +1,204 @@
+import { type ExecuteOptions } from '@zmdb/orm';
+import { appendComment, type CommentKey, type CommentPairs, type CompiledQuery, type SqlDialect } from '@zmdb/sql';
+
+import { fromTraceContext, toTraceparent } from './propagation.js';
+import { SpanKind, type Attributes, type Observability, type Span, type TraceCarrier, type Tracer } from './types.js';
+
+export { fromTraceContext, fromTraceparent, toTraceHeaders, toTraceparent } from './propagation.js';
+export { SpanKind } from './types.js';
+export type {
+  Attributes,
+  CommentKey,
+  CommentKeys,
+  CommentPairs,
+  Meter,
+  Observability,
+  QueryTelemetry,
+  Span,
+  SpanContext,
+  SpanOptions,
+  TraceCarrier,
+  Tracer,
+} from './types.js';
+
+/** Structural driver surface instrumented without importing a concrete driver. */
+export interface ExecutingDriver {
+  readonly dialect?: SqlDialect;
+  readonly queryTelemetry?: true;
+  execute(query: CompiledQuery, options?: ExecuteOptions): Promise<readonly Record<string, unknown>[]>;
+  stream?(query: CompiledQuery, options?: ExecuteOptions): AsyncIterable<Record<string, unknown>>;
+}
+
+/**
+ * Add database spans, metrics and optional sqlcommenter tags at execution.
+ *
+ * `commentValues` is request-scoped and supplies the low-cardinality values.
+ * When selected, `traceparent` comes from the query span (or the supplied
+ * parent when no tracer is configured), not from the callback.
+ *
+ * With no port configured, return the original object: no wrapper, marker,
+ * closure or per-query branch is added to the off path.
+ */
+export function tracedDriver(
+  driver: ExecutingDriver,
+  observability: Observability,
+  parent?: Span,
+  commentValues?: () => CommentPairs,
+): ExecutingDriver {
+  const { tracer, meter, comments } = observability;
+  if (tracer === undefined && meter === undefined && comments === undefined) {
+    return driver;
+  }
+
+  const duration = meter?.histogram('db.client.operation.duration', 's');
+  const execute = async (
+    query: CompiledQuery,
+    options?: ExecuteOptions,
+  ): Promise<readonly Record<string, unknown>[]> => {
+    const telemetry = query.telemetry;
+    const span = startQuerySpan(tracer, telemetry, parent);
+    if (span !== undefined) {
+      if (telemetry !== undefined) {
+        span.setAttribute('db.system.name', telemetry.system);
+        span.setAttribute('db.operation.name', telemetry.operation);
+        span.setAttribute('db.collection.name', telemetry.collection);
+      }
+      // Compiled SQL contains placeholders; parameter values are deliberately
+      // absent from every telemetry surface.
+      span.setAttribute('db.query.text', query.text);
+      span.setAttribute('zmdb.db.parameter_count', query.parameters.length);
+    }
+
+    const started = Date.now();
+    try {
+      const executed =
+        comments === undefined ? query : queryWithComments(query, comments.keys, commentValues?.(), span ?? parent);
+      return await driver.execute(executed, options);
+    } catch (error) {
+      if (span !== undefined) {
+        const recorded = errorValue(error);
+        span.recordException(recorded);
+        span.setStatus({ error: true });
+        const code = errorCode(error);
+        if (code !== undefined) {
+          span.setAttribute('db.response.status_code', code);
+        }
+      }
+      throw error;
+    } finally {
+      if (duration !== undefined && telemetry !== undefined) {
+        const attributes: Attributes = {
+          'db.system.name': telemetry.system,
+          'db.operation.name': telemetry.operation,
+          'db.collection.name': telemetry.collection,
+        };
+        duration.record((Date.now() - started) / 1000, attributes);
+      }
+      span?.end();
+    }
+  };
+
+  const wrapped = { ...driver, execute };
+  return tracer === undefined && meter === undefined ? wrapped : { ...wrapped, queryTelemetry: true };
+}
+
+/** Start the consumer side of one propagated message delivery. */
+export function consumerSpan(
+  observability: Observability,
+  envelope: TraceCarrier,
+  delivery: 'queued' | 'request-reply',
+): Span {
+  const tracer = observability.tracer;
+  if (tracer === undefined) {
+    throw new Error('@zmdb/app: consumerSpan requires a configured tracer');
+  }
+  const remote = fromTraceContext(envelope.traceparent, envelope.tracestate);
+  if (remote === undefined) {
+    return tracer.startSpan('zmdb.message', { kind: SpanKind.CONSUMER });
+  }
+  return delivery === 'queued'
+    ? tracer.startSpan('zmdb.message', { kind: SpanKind.CONSUMER, link: remote })
+    : tracer.startSpan('zmdb.message', { kind: SpanKind.CONSUMER, parent: remote });
+}
+
+function startQuerySpan(
+  tracer: Tracer | undefined,
+  telemetry: CompiledQuery['telemetry'],
+  parent: Span | undefined,
+): Span | undefined {
+  if (tracer === undefined) {
+    return undefined;
+  }
+  const name = telemetry === undefined ? 'db.query' : `${telemetry.operation} ${telemetry.collection}`;
+  return parent === undefined
+    ? tracer.startSpan(name, { kind: SpanKind.CLIENT })
+    : tracer.startSpan(name, { kind: SpanKind.CLIENT, parent: parent.spanContext() });
+}
+
+function errorValue(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+function errorCode(error: unknown): string | number | undefined {
+  if (error === null || typeof error !== 'object' || !('code' in error)) {
+    return undefined;
+  }
+  const code: unknown = error.code;
+  return typeof code === 'string' || typeof code === 'number' ? code : undefined;
+}
+
+function queryWithComments(
+  query: CompiledQuery,
+  keys: readonly CommentKey[],
+  source: CommentPairs | undefined,
+  span: Span | undefined,
+): CompiledQuery {
+  const pairs = selectedCommentPairs(keys, source, span);
+  const text = appendComment(query.text, pairs);
+  return text === query.text ? query : { ...query, text };
+}
+
+function selectedCommentPairs(
+  keys: readonly CommentKey[],
+  source: CommentPairs | undefined,
+  span: Span | undefined,
+): CommentPairs {
+  const selected = new Map<CommentKey, string>();
+  for (const key of keys) {
+    const value = key === 'traceparent' && span !== undefined ? toTraceparent(span) : ownCommentValue(source, key);
+    if (value !== undefined) {
+      selected.set(key, value);
+    }
+  }
+
+  const action = selected.get('action');
+  const controller = selected.get('controller');
+  const framework = selected.get('framework');
+  const route = selected.get('route');
+  const traceparent = selected.get('traceparent');
+  return {
+    ...(action === undefined ? {} : { action }),
+    ...(controller === undefined ? {} : { controller }),
+    ...(framework === undefined ? {} : { framework }),
+    ...(route === undefined ? {} : { route }),
+    ...(traceparent === undefined ? {} : { traceparent }),
+  };
+}
+
+function ownCommentValue(source: CommentPairs | undefined, key: CommentKey): string | undefined {
+  if (source === undefined || !Object.hasOwn(source, key)) {
+    return undefined;
+  }
+  switch (key) {
+    case 'action':
+      return source.action;
+    case 'controller':
+      return source.controller;
+    case 'framework':
+      return source.framework;
+    case 'route':
+      return source.route;
+    case 'traceparent':
+      return source.traceparent;
+  }
+}

package/src/observability/propagation.ts

@@ -0,0 +1,107 @@
+import type { Span, SpanContext, TraceCarrier } from './types.js';
+
+const LOWER_HEX = /^[0-9a-f]+$/;
+const ZERO_TRACE_ID = '00000000000000000000000000000000';
+const ZERO_SPAN_ID = '0000000000000000';
+const TRACE_STATE_KEY = /^(?:[a-z][_0-9a-z\-*/]{0,255}|[a-z0-9][_0-9a-z\-*/]{0,240}@[a-z][_0-9a-z\-*/]{0,13})$/;
+const TRACE_STATE_VALUE = /^[ -~]{0,255}[!-~]$/;
+
+/** Parse one W3C traceparent value, ignoring malformed input. */
+export function fromTraceparent(header: string): SpanContext | undefined {
+  return fromTraceContext(header);
+}
+
+/** Parse a W3C trace context, keeping a valid parent when tracestate is invalid. */
+export function fromTraceContext(traceparent: string | undefined, tracestate?: string): SpanContext | undefined {
+  if (traceparent === undefined) {
+    return undefined;
+  }
+  const fields = traceparent.split('-');
+  if (fields.length < 4) {
+    return undefined;
+  }
+  const version = fields[0];
+  const traceId = fields[1];
+  const spanId = fields[2];
+  const flags = fields[3];
+  if (
+    version === undefined ||
+    traceId === undefined ||
+    spanId === undefined ||
+    flags === undefined ||
+    version.length !== 2 ||
+    traceId.length !== 32 ||
+    spanId.length !== 16 ||
+    flags.length !== 2 ||
+    !LOWER_HEX.test(version) ||
+    !LOWER_HEX.test(traceId) ||
+    !LOWER_HEX.test(spanId) ||
+    !LOWER_HEX.test(flags) ||
+    version === 'ff' ||
+    traceId === ZERO_TRACE_ID ||
+    spanId === ZERO_SPAN_ID ||
+    (version === '00' && fields.length !== 4)
+  ) {
+    return undefined;
+  }
+  const traceState = validatedTraceState(tracestate);
+  return {
+    traceId,
+    spanId,
+    traceFlags: Number.parseInt(flags, 16),
+    isRemote: true,
+    ...(traceState === undefined ? {} : { traceState }),
+  };
+}
+
+/** Render the current span as a W3C traceparent value for an outbound carrier. */
+export function toTraceparent(span: Span): string {
+  return formatTraceparent(span.spanContext());
+}
+
+function formatTraceparent(context: SpanContext): string {
+  const flags = (context.traceFlags & 0xff).toString(16).padStart(2, '0');
+  return `00-${context.traceId.toLowerCase()}-${context.spanId.toLowerCase()}-${flags}`;
+}
+
+/** Render the current span as the common outbound W3C trace carrier. */
+export function toTraceHeaders(span: Span): TraceCarrier {
+  const context = span.spanContext();
+  const traceState = validatedTraceState(context.traceState);
+  return {
+    traceparent: formatTraceparent(context),
+    ...(traceState === undefined ? {} : { tracestate: traceState }),
+  };
+}
+
+function validatedTraceState(header: string | undefined): string | undefined {
+  if (header === undefined || header.length === 0 || header.length > 512) {
+    return undefined;
+  }
+  const members = header.split(',');
+  if (members.length > 32) {
+    return undefined;
+  }
+
+  const keys = new Set<string>();
+  const normalized: string[] = [];
+  for (const rawMember of members) {
+    const member = trimOptionalWhitespace(rawMember);
+    const separator = member.indexOf('=');
+    if (separator <= 0 || member.indexOf('=', separator + 1) !== -1) {
+      return undefined;
+    }
+    const key = member.slice(0, separator);
+    const value = member.slice(separator + 1);
+    if (!TRACE_STATE_KEY.test(key) || !TRACE_STATE_VALUE.test(value) || value.includes(',') || keys.has(key)) {
+      return undefined;
+    }
+    keys.add(key);
+    normalized.push(member);
+  }
+  return normalized.join(',');
+}
+
+function trimOptionalWhitespace(value: string): string {
+  return value.replace(/^[\t ]+|[\t ]+$/g, '');
+}

package/src/observability/types.ts

@@ -0,0 +1,68 @@
+import { type CommentKey, type CommentKeys, type CommentPairs, type QueryTelemetry } from '@zmdb/sql';
+
+/** Scalar attributes accepted by the framework's telemetry ports. */
+export type Attributes = Readonly<Record<string, string | number | boolean>>;
+
+/** Span roles understood by the framework's telemetry port. */
+export const SpanKind = {
+  INTERNAL: 'internal',
+  SERVER: 'server',
+  CLIENT: 'client',
+  PRODUCER: 'producer',
+  CONSUMER: 'consumer',
+} as const;
+
+export type SpanKind = (typeof SpanKind)[keyof typeof SpanKind];
+
+/** Trace identity carried explicitly between framework layers. */
+export interface SpanContext {
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly traceFlags: number;
+  readonly isRemote?: boolean;
+  /** W3C tracestate serialized for transport without an SDK type dependency. */
+  readonly traceState?: string;
+}
+
+/** The common W3C trace carrier used by HTTP and message transports. */
+export interface TraceCarrier {
+  readonly traceparent?: string;
+  readonly tracestate?: string;
+}
+
+/** The narrow span surface used by @zmdb/app. */
+export interface Span {
+  updateName(name: string): void;
+  setAttribute(key: string, value: string | number | boolean): void;
+  recordException(error: Error): void;
+  setStatus(status: { readonly error: boolean }): void;
+  end(): void;
+  spanContext(): SpanContext;
+}
+
+/** Explicit span creation inputs; ambient context is deliberately absent. */
+export interface SpanOptions {
+  readonly parent?: SpanContext;
+  readonly link?: SpanContext;
+  readonly kind?: SpanKind;
+}
+
+/** The narrow tracer surface used by @zmdb/app. */
+export interface Tracer {
+  startSpan(name: string, options?: SpanOptions): Span;
+}
+
+/** The narrow meter surface used by @zmdb/app. */
+export interface Meter {
+  counter(name: string): { add(value: number, attributes: Attributes): void };
+  histogram(name: string, unit: 's'): { record(value: number, attributes: Attributes): void };
+}
+
+/** App-owned telemetry configuration. Presence means enabled. */
+export interface Observability {
+  readonly tracer?: Tracer;
+  readonly meter?: Meter;
+  readonly comments?: { readonly keys: CommentKeys };
+}
+
+export type { CommentKey, CommentKeys, CommentPairs, QueryTelemetry };

package/src/polyfill.ts

@@ -0,0 +1,24 @@
+// Zero-dependency Symbol.metadata baseline.
+//
+// Stage-3 decorator metadata relies on the well-known `Symbol.metadata`. Node 26
+// / V8 does not yet expose it (`Symbol.metadata === undefined` as of v26.8), so
+// we install it if — and only if — the runtime lacks it. We assign ONLY the
+// well-known symbol and mutate nothing else on any global. When a future runtime
+// ships it natively this becomes a no-op.
+//
+// This module has a side effect and must be imported before any decorated class
+// is evaluated. `@zmdb/app`'s entry imports it first.
+
+interface SymbolWithMetadata {
+  metadata?: symbol;
+}
+
+const carrier: SymbolWithMetadata = Symbol;
+if (carrier.metadata === undefined) {
+  Object.defineProperty(Symbol, 'metadata', {
+    value: Symbol.for('Symbol.metadata'),
+    writable: false,
+    enumerable: false,
+    configurable: true,
+  });
+}

package/src/state/fixtures.ts

@@ -0,0 +1,20 @@
+// The order workflow both state tests are about.
+//
+// `state.spec.ts` checks what branding does at runtime (nothing) and
+// `state.type-test.ts` checks which transitions compile. Those are two halves of
+// one claim, so they read the states and edges from here rather than each
+// declaring their own — the type-test's extra `Shipped` state exists precisely so
+// there is a `Draft -> Shipped` edge that was never defined.
+import { defineState, transition } from './index.js';
+
+export interface Order {
+  id: number;
+  total: number;
+}
+
+export const Draft = defineState<'Draft', Order>();
+export const Paid = defineState<'Paid', Order>();
+export const Shipped = defineState<'Shipped', Order>();
+
+export const pay = transition(Draft, Paid, o => ({ ...o }));
+export const ship = transition(Paid, Shipped, o => ({ ...o }));

package/src/state/index.ts

@@ -0,0 +1,57 @@
+// @zmdb/app — compile-time domain state machines (epic #267, spec ./SPEC.md).
+// Branded/phantom types make illegal transitions fail to compile; branding
+// erases at runtime (0 cost). No `as` on the consumer surface — construction
+// goes through a checked factory. No reflection.
+
+// A unique phantom brand key so branded types are nominal (structurally
+// incompatible across brands) yet erase to the base type at runtime.
+declare const brand: unique symbol;
+
+/** `T` nominally tagged with brand `B`. Erases to `T` at runtime. */
+export type Brand<T, B extends string> = T & { readonly [brand]: B };
+
+/** A state maker for a named state over a base type. */
+export interface State<B extends string, T> {
+  /** Construct a branded value from base fields — no consumer `as`. */
+  create(value: T): Brand<T, B>;
+  /** Type guard narrowing an unknown/base value to this branded state. */
+  is(value: unknown): value is Brand<T, B>;
+}
+
+/**
+ * Define a domain state. Returns a maker whose `create` brands base values and
+ * whose `is` narrows to the branded type. The brand exists only in the type
+ * system, so `create` is an identity at runtime.
+ */
+export function defineState<B extends string, T>(): State<B, T> {
+  return {
+    create(value: T): Brand<T, B> {
+      // boundary: branding is a compile-time-only tag (the brand symbol has no
+      // runtime representation), so returning the value unchanged as the branded
+      // type is sound. This is the single enumerated brand-attach boundary
+      // (ARCHITECTURE.md §2.1); it never appears on the consumer surface.
+      return value as Brand<T, B>;
+    },
+    is(value: unknown): value is Brand<T, B> {
+      // The brand is erased at runtime; a value "is" this state by construction.
+      // We can only assert non-nullish here — the compile-time brand carries the
+      // real guarantee. Callers use `is` to narrow values they already trust.
+      return value !== undefined && value !== null;
+    },
+  };
+}
+
+/**
+ * Declare a legal state transition `From -> To`. The returned function only
+ * accepts a value already branded `From`, so applying it to any other state is
+ * a compile error, and undeclared edges simply have no function.
+ */
+export function transition<T, From extends string, To extends string>(
+  _from: State<From, T>,
+  to: State<To, T>,
+  fn: (value: Brand<T, From>) => T,
+): (value: Brand<T, From>) => Brand<T, To> {
+  return function (value: Brand<T, From>): Brand<T, To> {
+    return to.create(fn(value));
+  };
+}

package/src/state-transitions.ts

@@ -0,0 +1,150 @@
+import type { DeclaredTable, TaggedSchema, UpdateDTO } from '@zmdb/schema';
+
+export type StateTransitions<StateValues extends string | number | symbol = string> = {
+  readonly [From in StateValues]?: readonly StateValues[];
+};
+
+export function defineStateTransitions<
+  StateValues extends string,
+  const T extends { readonly [From in StateValues]?: readonly StateValues[] },
+>(transitions: T): T {
+  return transitions;
+}
+
+export type AllowedTargetStates<Transitions, From extends string> = Transitions extends {
+  readonly [k in From]?: readonly (infer To extends string)[];
+}
+  ? To
+  : never;
+
+export type StateUpdateDTO<
+  T extends DeclaredTable,
+  StateField extends string,
+  FromState extends string,
+  Transitions,
+  AllowedFields extends keyof UpdateDTO<T> = keyof UpdateDTO<T>,
+> = Pick<UpdateDTO<T>, Exclude<AllowedFields, StateField>> & {
+  [P in StateField]?: AllowedTargetStates<Transitions, FromState>;
+};
+
+/** What a transition out of `From` is allowed to patch: the declared restriction if there is one, otherwise every updatable field. */
+type PatchableFields<
+  T extends DeclaredTable,
+  Transitions extends Record<string, readonly string[]>,
+  FieldRestrictions extends { readonly [From in keyof Transitions]?: readonly (keyof UpdateDTO<T>)[] },
+  From extends keyof Transitions & string,
+> = FieldRestrictions[From] extends readonly (keyof UpdateDTO<T>)[]
+  ? FieldRestrictions[From][number]
+  : keyof UpdateDTO<T>;
+
+/**
+ * The `patch` argument of a transition out of `From`. When the only patchable
+ * field is the state field itself there is nothing left to pass, so the argument
+ * narrows to `Record<string, never>` and any property is a type error.
+ */
+type TransitionPatch<
+  T extends DeclaredTable,
+  StateField extends string,
+  Transitions extends Record<string, readonly string[]>,
+  FieldRestrictions extends { readonly [From in keyof Transitions]?: readonly (keyof UpdateDTO<T>)[] },
+  From extends keyof Transitions & string,
+> = [Exclude<PatchableFields<T, Transitions, FieldRestrictions, From>, StateField>] extends [never]
+  ? Record<string, never>
+  : Omit<Pick<UpdateDTO<T>, PatchableFields<T, Transitions, FieldRestrictions, From>>, StateField>;
+
+export interface EntityStateMachineOptions<
+  T extends DeclaredTable,
+  StateField extends string,
+  Transitions extends Record<string, readonly string[]>,
+  FieldRestrictions extends { readonly [From in keyof Transitions]?: readonly (keyof UpdateDTO<T>)[] } = {},
+> {
+  /**
+   * The generated schema value, for inference only — nothing reads it.
+   *
+   * It is the whole reason this machine knows what a patch may contain: `T` is the
+   * declared type, recovered from the value's phantom, and `UpdateDTO<T>` is what the
+   * transitions are checked against. Passing a schema for a different table is the one
+   * mistake this cannot catch, and it is the same mistake as pointing a repository at
+   * the wrong table.
+   */
+  schema?: TaggedSchema<T>;
+  stateField: StateField;
+  transitions: Transitions;
+  allowedFields?: FieldRestrictions | undefined;
+}
+
+export interface EntityStateMachine<
+  T extends DeclaredTable,
+  StateField extends string,
+  Transitions extends Record<string, readonly string[]>,
+  FieldRestrictions extends { readonly [From in keyof Transitions]?: readonly (keyof UpdateDTO<T>)[] } = {},
+> {
+  readonly stateField: StateField;
+  readonly transitions: Transitions;
+  readonly allowedFields?: FieldRestrictions | undefined;
+  canTransition<From extends keyof Transitions & string>(from: From, to: string): boolean;
+  createUpdatePayload<From extends keyof Transitions & string, To extends Transitions[From][number]>(
+    from: From,
+    to: To,
+    patch?: TransitionPatch<T, StateField, Transitions, FieldRestrictions, From>,
+  ): StateUpdateDTO<T, StateField, From, Transitions, PatchableFields<T, Transitions, FieldRestrictions, From>>;
+}
+
+export function createStateUpdatePayload<
+  T extends DeclaredTable,
+  StateField extends string,
+  From extends keyof Transitions & string,
+  const Transitions extends Record<string, readonly string[]>,
+  AllowedFields extends keyof UpdateDTO<T> = keyof UpdateDTO<T>,
+>(
+  stateField: StateField,
+  transitions: Transitions,
+  from: From,
+  to: Transitions[From][number],
+  patch?: Omit<Pick<UpdateDTO<T>, AllowedFields>, StateField> | Record<string, never>,
+): StateUpdateDTO<T, StateField, From, Transitions, AllowedFields> {
+  const allowed = transitions[from];
+  if (!Array.isArray(allowed) || !allowed.includes(to)) {
+    throw new Error(`Invalid state transition from "${from}" to "${to}" for field "${stateField}"`);
+  }
+  const payload = {
+    ...patch,
+    [stateField]: to,
+  };
+  // boundary: return value is certified as StateUpdateDTO after runtime transition validation.
+  return payload as StateUpdateDTO<T, StateField, From, Transitions, AllowedFields>;
+}
+
+export function defineEntityStateMachine<
+  T extends DeclaredTable,
+  StateField extends string,
+  const Transitions extends Record<string, readonly string[]>,
+  const FieldRestrictions extends { readonly [From in keyof Transitions]?: readonly (keyof UpdateDTO<T>)[] } = {},
+>(
+  options: EntityStateMachineOptions<T, StateField, Transitions, FieldRestrictions>,
+): EntityStateMachine<T, StateField, Transitions, FieldRestrictions> {
+  const { stateField, transitions, allowedFields } = options;
+
+  return {
+    stateField,
+    transitions,
+    allowedFields,
+    canTransition(from: keyof Transitions & string, to: string): boolean {
+      const allowed = transitions[from];
+      return Array.isArray(allowed) && allowed.includes(to);
+    },
+    createUpdatePayload<From extends keyof Transitions & string, To extends Transitions[From][number]>(
+      from: From,
+      to: To,
+      patch?: TransitionPatch<T, StateField, Transitions, FieldRestrictions, From>,
+    ) {
+      return createStateUpdatePayload<
+        T,
+        StateField,
+        From,
+        Transitions,
+        PatchableFields<T, Transitions, FieldRestrictions, From>
+      >(stateField, transitions, from, to, patch);
+    },
+  };
+}