@zmdb/app 1.0.0-beta.1

package/dist/observability/index.js

@@ -0,0 +1,145 @@
+import {} from '@zmdb/orm';
+import { appendComment } from '@zmdb/sql';
+import { fromTraceContext, toTraceparent } from './propagation.js';
+import { SpanKind } from './types.js';
+export { fromTraceContext, fromTraceparent, toTraceHeaders, toTraceparent } from './propagation.js';
+export { SpanKind } from './types.js';
+/**
+ * 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, observability, parent, commentValues) {
+    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, options) => {
+        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 = {
+                    '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, envelope, delivery) {
+    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, telemetry, parent) {
+    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) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function errorCode(error) {
+    if (error === null || typeof error !== 'object' || !('code' in error)) {
+        return undefined;
+    }
+    const code = error.code;
+    return typeof code === 'string' || typeof code === 'number' ? code : undefined;
+}
+function queryWithComments(query, keys, source, span) {
+    const pairs = selectedCommentPairs(keys, source, span);
+    const text = appendComment(query.text, pairs);
+    return text === query.text ? query : { ...query, text };
+}
+function selectedCommentPairs(keys, source, span) {
+    const selected = new Map();
+    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, key) {
+    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;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"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"}

package/dist/observability/propagation.d.ts

@@ -0,0 +1,10 @@
+import type { Span, SpanContext, TraceCarrier } from './types.js';
+/** Parse one W3C traceparent value, ignoring malformed input. */
+export declare function fromTraceparent(header: string): SpanContext | undefined;
+/** Parse a W3C trace context, keeping a valid parent when tracestate is invalid. */
+export declare function fromTraceContext(traceparent: string | undefined, tracestate?: string): SpanContext | undefined;
+/** Render the current span as a W3C traceparent value for an outbound carrier. */
+export declare function toTraceparent(span: Span): string;
+/** Render the current span as the common outbound W3C trace carrier. */
+export declare function toTraceHeaders(span: Span): TraceCarrier;
+//# sourceMappingURL=propagation.d.ts.map

package/dist/observability/propagation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"propagation.d.ts","sourceRoot":"","sources":["../../src/observability/propagation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAQlE,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEvE;AAED,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAwC9G;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAEhD;AAOD,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,YAAY,CAOvD"}

package/dist/observability/propagation.js

@@ -0,0 +1,96 @@
+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) {
+    return fromTraceContext(header);
+}
+/** Parse a W3C trace context, keeping a valid parent when tracestate is invalid. */
+export function fromTraceContext(traceparent, tracestate) {
+    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) {
+    return formatTraceparent(span.spanContext());
+}
+function formatTraceparent(context) {
+    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) {
+    const context = span.spanContext();
+    const traceState = validatedTraceState(context.traceState);
+    return {
+        traceparent: formatTraceparent(context),
+        ...(traceState === undefined ? {} : { tracestate: traceState }),
+    };
+}
+function validatedTraceState(header) {
+    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();
+    const normalized = [];
+    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) {
+    return value.replace(/^[\t ]+|[\t ]+$/g, '');
+}
+//# sourceMappingURL=propagation.js.map

package/dist/observability/propagation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"propagation.js","sourceRoot":"","sources":["../../src/observability/propagation.ts"],"names":[],"mappings":"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"}

package/dist/observability/types.d.ts

@@ -0,0 +1,66 @@
+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 declare const SpanKind: {
+    readonly INTERNAL: 'internal';
+    readonly SERVER: 'server';
+    readonly CLIENT: 'client';
+    readonly PRODUCER: 'producer';
+    readonly CONSUMER: 'consumer';
+};
+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 };
+//# sourceMappingURL=types.d.ts.map

package/dist/observability/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/observability/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAEtG,qEAAqE;AACrE,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;AAE7E,+DAA+D;AAC/D,eAAO,MAAM,QAAQ;aACnB,QAAQ,EAAE,UAAU;aACpB,MAAM,EAAE,QAAQ;aAChB,MAAM,EAAE,QAAQ;aAChB,QAAQ,EAAE,UAAU;aACpB,QAAQ,EAAE,UAAU;CACZ,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC;AAEhE,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,iDAAiD;AACjD,MAAM,WAAW,IAAI;IACnB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAClE,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpC,SAAS,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACrD,GAAG,IAAI,IAAI,CAAC;IACZ,WAAW,IAAI,WAAW,CAAC;CAC5B;AAED,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;CAC1B;AAED,mDAAmD;AACnD,MAAM,WAAW,MAAM;IACrB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CACtD;AAED,kDAAkD;AAClD,MAAM,WAAW,KAAK;IACpB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI,CAAA;KAAE,CAAC;IAC5E,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG;QAAE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI,CAAA;KAAE,CAAC;CAC7F;AAED,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;KAAE,CAAC;CACpD;AAED,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC"}

package/dist/observability/types.js

@@ -0,0 +1,10 @@
+import {} from '@zmdb/sql';
+/** Span roles understood by the framework's telemetry port. */
+export const SpanKind = {
+    INTERNAL: 'internal',
+    SERVER: 'server',
+    CLIENT: 'client',
+    PRODUCER: 'producer',
+    CONSUMER: 'consumer',
+};
+//# sourceMappingURL=types.js.map

package/dist/observability/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/observability/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6E,MAAM,WAAW,CAAC;AAKtG,+DAA+D;AAC/D,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,QAAQ,EAAE,UAAU;IACpB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;CACZ,CAAC"}

package/dist/polyfill.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=polyfill.d.ts.map

package/dist/polyfill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polyfill.d.ts","sourceRoot":"","sources":["../src/polyfill.ts"],"names":[],"mappings":""}

package/dist/polyfill.js

@@ -0,0 +1,21 @@
+// 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.
+const carrier = Symbol;
+if (carrier.metadata === undefined) {
+    Object.defineProperty(Symbol, 'metadata', {
+        value: Symbol.for('Symbol.metadata'),
+        writable: false,
+        enumerable: false,
+        configurable: true,
+    });
+}
+export {};
+//# sourceMappingURL=polyfill.js.map

package/dist/polyfill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"polyfill.js","sourceRoot":"","sources":["../src/polyfill.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,EAAE;AACF,iFAAiF;AACjF,gFAAgF;AAChF,4EAA4E;AAC5E,iFAAiF;AACjF,0CAA0C;AAC1C,EAAE;AACF,gFAAgF;AAChF,sDAAsD;AAMtD,MAAM,OAAO,GAAuB,MAAM,CAAC;AAC3C,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;IACnC,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE;QACxC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC;QACpC,QAAQ,EAAE,KAAK;QACf,UAAU,EAAE,KAAK;QACjB,YAAY,EAAE,IAAI;KACnB,CAAC,CAAC;AACL,CAAC"}

package/dist/state/fixtures.d.ts

@@ -0,0 +1,10 @@
+export interface Order {
+    id: number;
+    total: number;
+}
+export declare const Draft: import("./index.js").State<"Draft", Order>;
+export declare const Paid: import("./index.js").State<"Paid", Order>;
+export declare const Shipped: import("./index.js").State<"Shipped", Order>;
+export declare const pay: (value: import("./index.js").Brand<Order, "Draft">) => import("./index.js").Brand<Order, "Paid">;
+export declare const ship: (value: import("./index.js").Brand<Order, "Paid">) => import("./index.js").Brand<Order, "Shipped">;
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/state/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../src/state/fixtures.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,KAAK,4CAAgC,CAAC;AACnD,eAAO,MAAM,IAAI,2CAA+B,CAAC;AACjD,eAAO,MAAM,OAAO,8CAAkC,CAAC;AAEvD,eAAO,MAAM,GAAG,kGAA2C,CAAC;AAC5D,eAAO,MAAM,IAAI,oGAA6C,CAAC"}

package/dist/state/fixtures.js

@@ -0,0 +1,14 @@
+// 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 const Draft = defineState();
+export const Paid = defineState();
+export const Shipped = defineState();
+export const pay = transition(Draft, Paid, o => ({ ...o }));
+export const ship = transition(Paid, Shipped, o => ({ ...o }));
+//# sourceMappingURL=fixtures.js.map

package/dist/state/fixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.js","sourceRoot":"","sources":["../../src/state/fixtures.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,EAAE;AACF,qEAAqE;AACrE,iFAAiF;AACjF,0EAA0E;AAC1E,kFAAkF;AAClF,6DAA6D;AAC7D,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAOrD,MAAM,CAAC,MAAM,KAAK,GAAG,WAAW,EAAkB,CAAC;AACnD,MAAM,CAAC,MAAM,IAAI,GAAG,WAAW,EAAiB,CAAC;AACjD,MAAM,CAAC,MAAM,OAAO,GAAG,WAAW,EAAoB,CAAC;AAEvD,MAAM,CAAC,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AAC5D,MAAM,CAAC,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC"}

package/dist/state/index.d.ts

@@ -0,0 +1,26 @@
+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 declare function defineState<B extends string, T>(): State<B, T>;
+/**
+ * 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 declare 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>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/state/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAOA,OAAO,CAAC,MAAM,KAAK,EAAE,OAAO,MAAM,CAAC;AAEnC,qEAAqE;AACrE,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,CAAC,GAAG;IAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC;AAErE,wDAAwD;AACxD,MAAM,WAAW,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC;IACxC,qEAAqE;IACrE,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9B,wEAAwE;IACxE,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAgB9D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,SAAS,MAAM,EAAE,EAAE,SAAS,MAAM,EAClE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,EACrB,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAChB,EAAE,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,GAC/B,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAIzC"}

package/dist/state/index.js

@@ -0,0 +1,37 @@
+// @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.
+/**
+ * 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() {
+    return {
+        create(value) {
+            // 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;
+        },
+        is(value) {
+            // 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(_from, to, fn) {
+    return function (value) {
+        return to.create(fn(value));
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/state/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,2EAA2E;AAC3E,6EAA6E;AAC7E,iDAAiD;AAiBjD;;;;GAIG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO;QACL,MAAM,CAAC,KAAQ;YACb,yEAAyE;YACzE,2EAA2E;YAC3E,qEAAqE;YACrE,oEAAoE;YACpE,OAAO,KAAoB,CAAC;QAC9B,CAAC;QACD,EAAE,CAAC,KAAc;YACf,2EAA2E;YAC3E,2EAA2E;YAC3E,wEAAwE;YACxE,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC;QAC/C,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,KAAqB,EACrB,EAAgB,EAChB,EAAgC;IAEhC,OAAO,UAAU,KAAqB;QACpC,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9B,CAAC,CAAC;AACJ,CAAC"}

package/dist/state-transitions.d.ts

@@ -0,0 +1,57 @@
+import type { DeclaredTable, TaggedSchema, UpdateDTO } from '@zmdb/schema';
+export type StateTransitions<StateValues extends string | number | symbol = string> = {
+    readonly [From in StateValues]?: readonly StateValues[];
+};
+export declare function defineStateTransitions<StateValues extends string, const T extends {
+    readonly [From in StateValues]?: readonly StateValues[];
+}>(transitions: T): T;
+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 declare 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>;
+export declare 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>;
+export {};
+//# sourceMappingURL=state-transitions.d.ts.map

package/dist/state-transitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-transitions.d.ts","sourceRoot":"","sources":["../src/state-transitions.ts"],"names":[],"mappings":"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"}

package/dist/state-transitions.js

@@ -0,0 +1,31 @@
+export function defineStateTransitions(transitions) {
+    return transitions;
+}
+export function createStateUpdatePayload(stateField, transitions, from, to, patch) {
+    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;
+}
+export function defineEntityStateMachine(options) {
+    const { stateField, transitions, allowedFields } = options;
+    return {
+        stateField,
+        transitions,
+        allowedFields,
+        canTransition(from, to) {
+            const allowed = transitions[from];
+            return Array.isArray(allowed) && allowed.includes(to);
+        },
+        createUpdatePayload(from, to, patch) {
+            return createStateUpdatePayload(stateField, transitions, from, to, patch);
+        },
+    };
+}
+//# sourceMappingURL=state-transitions.js.map

package/dist/state-transitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-transitions.js","sourceRoot":"","sources":["../src/state-transitions.ts"],"names":[],"mappings":"AAMA,MAAM,UAAU,sBAAsB,CAGpC,WAAc;IACd,OAAO,WAAW,CAAC;AACrB,CAAC;AAiFD,MAAM,UAAU,wBAAwB,CAOtC,UAAsB,EACtB,WAAwB,EACxB,IAAU,EACV,EAA6B,EAC7B,KAAmF;IAEnF,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,kCAAkC,IAAI,SAAS,EAAE,gBAAgB,UAAU,GAAG,CAAC,CAAC;IAClG,CAAC;IACD,MAAM,OAAO,GAAG;QACd,GAAG,KAAK;QACR,CAAC,UAAU,CAAC,EAAE,EAAE;KACjB,CAAC;IACF,6FAA6F;IAC7F,OAAO,OAA0E,CAAC;AACpF,CAAC;AAED,MAAM,UAAU,wBAAwB,CAMtC,OAAiF;IAEjF,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;IAE3D,OAAO;QACL,UAAU;QACV,WAAW;QACX,aAAa;QACb,aAAa,CAAC,IAAgC,EAAE,EAAU;YACxD,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;YAClC,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,mBAAmB,CACjB,IAAU,EACV,EAAM,EACN,KAA4E;YAE5E,OAAO,wBAAwB,CAM7B,UAAU,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;QAC9C,CAAC;KACF,CAAC;AACJ,CAAC"}