@substrat-run/model-emit 0.5.3 → 0.7.0

package/dist/emit-client.d.ts

@@ -0,0 +1,107 @@
+/**
+ * A vertical's browser client, rendered from its model.
+ *
+ * The pure half of `tools/client-emit.mts` — everything from "a Zod schema" to "a
+ * string of TypeScript", with no filesystem and no `process.exit` in it. It lives here
+ * rather than in the tool for one reason: a Zod→TypeScript printer is the kind of code
+ * that is wrong in ways a drift check cannot see. `--check` re-emits and compares, so it
+ * catches a client that fell behind its model; it cannot catch a client that has been
+ * confidently mis-spelling `z.union([...])` inside an array since the day it was written.
+ * That needs a test with the schema on one side and the expected string on the other,
+ * and a test needs something importable.
+ *
+ * Its home is this package because that is already this package's job: build-time
+ * tooling over a Substrat model. `emitTables` turns entities into DDL; this turns
+ * entities and operations into a typed fetch client.
+ *
+ * ## What it emits
+ *
+ * Standalone TypeScript with no imports at all. A vertical's SPA is a separate Vite
+ * package that depends on neither `@substrat-run/contracts` nor zod and must keep
+ * depending on neither — and a checked-in artifact that re-exports its meaning from
+ * another package is not reviewable in a diff.
+ *
+ * ## What it refuses
+ *
+ * A schema it cannot spell raises `ClientEmitError` naming the operation and the field.
+ * Never `unknown`, never a skipped method: a generated client that quietly degrades to
+ * `any` is more dangerous than the hand-written one it replaced, because the green light
+ * is now mechanical.
+ */
+/** Raised for anything the caller must fix. The CLI turns it into exit 2 and a remedy. */
+export declare class ClientEmitError extends Error {
+    constructor(message: string);
+}
+/**
+ * How a vertical declares its client, from `package.json` under `substrat.client`.
+ */
+export interface ClientConfig {
+    /**
+     * The module(s) the model is declared in.
+     *
+     * A list because a vertical is free to split it: todo keeps entities and operations
+     * in one `spec/model.ts`, callout has `src/entities.ts` and `src/operations.ts`, and
+     * an entry that is not a path is a package specifier — which is how a composed
+     * engine's published schemas are reached. Resolving the names across them is the
+     * caller's job (`tools/client-emit.mts`); this module is handed the values.
+     */
+    readonly model: string | readonly string[];
+    /**
+     * The export(s) holding entity declarations — `{ name: { fields, table } }`.
+     *
+     * A list because a vertical that composes engines wants the ENGINE's entities named
+     * too: without them `protocolGet`'s return type inlines four hundred characters of
+     * protocol row on one line, which is a diff nobody reads.
+     */
+    readonly entities: string | readonly string[];
+    /**
+     * Extra schemas to name, as `InterfaceName` → export name.
+     *
+     * An engine publishes types that are NOT its stored rows — `workOrder` is the
+     * engine's published shape, with the two `facility_*` columns folded into one
+     * `EntityRef`, and no entity's `fields` is that object. Those have nowhere else to
+     * be declared, so they are named here.
+     */
+    readonly schemas?: Readonly<Record<string, string>>;
+    /**
+     * The export(s) holding this vertical's operations.
+     *
+     * An array because a vertical that COMPOSES engines has more than one: callout
+     * declares its own six and then binds three engines' operations to its own URLs
+     * with `defineEngineRoutes`, which returns the same operation objects with `http`
+     * attached. Those are as much part of the app's surface as the vertical's own —
+     * the SPA calls `/workorders/{id}/complete` without caring whose operation it is —
+     * so a generator that read only the first bag would emit a third of the client and
+     * look complete doing it.
+     */
+    readonly operations: string | readonly string[];
+    readonly out: string;
+    readonly name: string;
+    /**
+     * Hand-stated types for schemas the printer cannot spell, keyed by the path the
+     * refusal prints (`<operation>.input.<field>`). Every entry must be reached — a
+     * stale escape hatch is worse than none, so an unused one is exit 2.
+     */
+    readonly types?: Readonly<Record<string, string>>;
+}
+/**
+ * One schema as TypeScript, with no operation around it.
+ *
+ * The printer's entry point for a test. `named` is the identity map an entity's
+ * `fields` would be in — pass one to check that a reference prints as its interface
+ * name rather than as an inline shape.
+ */
+export declare function tsTypeOf(schema: unknown, named?: Map<unknown, string>): string;
+/**
+ * `todo/create-list` → `createList`; `protocol/get` → `protocolGet`.
+ *
+ * The vertical's OWN prefix is dropped — it is the client's identity and repeating it
+ * on every method says nothing (`api.callout.calloutCreateOrder()`). A composed
+ * engine's prefix stays, and has to: callout binds `workorder/get`, `protocol/get` and
+ * `invoicing/get` at three URLs, and a client with one `get()` would reach whichever
+ * bag was read last. Renaming an engine's operation to suit a vertical's client is not
+ * a thing a vertical may do, so the disambiguation belongs here.
+ */
+export declare const methodName: (operation: string, ownPrefix: string) => string;
+export declare function renderClient(vertical: string, config: ClientConfig, source: string, entities: Record<string, unknown>, operations: Record<string, unknown>, extras: Record<string, unknown>): string;
+//# sourceMappingURL=emit-client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emit-client.d.ts","sourceRoot":"","sources":["../src/emit-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,0FAA0F;AAC1F,qBAAa,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAMD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC9C;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACnD;AAmLD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,GAAE,GAAG,CAAC,OAAO,EAAE,MAAM,CAAa,GAAG,MAAM,CAEzF;AAkCD;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,cAAe,MAAM,aAAa,MAAM,WAI9D,CAAC;AAsGF,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAwSR"}

package/dist/emit-client.js

@@ -0,0 +1,566 @@
+/**
+ * A vertical's browser client, rendered from its model.
+ *
+ * The pure half of `tools/client-emit.mts` — everything from "a Zod schema" to "a
+ * string of TypeScript", with no filesystem and no `process.exit` in it. It lives here
+ * rather than in the tool for one reason: a Zod→TypeScript printer is the kind of code
+ * that is wrong in ways a drift check cannot see. `--check` re-emits and compares, so it
+ * catches a client that fell behind its model; it cannot catch a client that has been
+ * confidently mis-spelling `z.union([...])` inside an array since the day it was written.
+ * That needs a test with the schema on one side and the expected string on the other,
+ * and a test needs something importable.
+ *
+ * Its home is this package because that is already this package's job: build-time
+ * tooling over a Substrat model. `emitTables` turns entities into DDL; this turns
+ * entities and operations into a typed fetch client.
+ *
+ * ## What it emits
+ *
+ * Standalone TypeScript with no imports at all. A vertical's SPA is a separate Vite
+ * package that depends on neither `@substrat-run/contracts` nor zod and must keep
+ * depending on neither — and a checked-in artifact that re-exports its meaning from
+ * another package is not reviewable in a diff.
+ *
+ * ## What it refuses
+ *
+ * A schema it cannot spell raises `ClientEmitError` naming the operation and the field.
+ * Never `unknown`, never a skipped method: a generated client that quietly degrades to
+ * `any` is more dangerous than the hand-written one it replaced, because the green light
+ * is now mechanical.
+ */
+/** Raised for anything the caller must fix. The CLI turns it into exit 2 and a remedy. */
+export class ClientEmitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ClientEmitError';
+    }
+}
+function fail(message) {
+    throw new ClientEmitError(message);
+}
+function defOf(schema) {
+    return (schema?._zod?.def ??
+        schema?._def);
+}
+/** The wrappers that do not change a type, only its optionality or its parsing. */
+const TRANSPARENT = new Set(['default', 'prefault', 'catch', 'readonly', 'nonoptional', 'pipe']);
+/** A field is optional when its own outermost wrapper says so — `a?: T`, not `a: T | undefined`. */
+function isOptional(schema) {
+    const def = defOf(schema);
+    if (def?.type === 'optional' || def?.type === 'nullish')
+        return true;
+    if (def && TRANSPARENT.has(def.type ?? '')) {
+        // A defaulted field is optional TO THE CALLER — the server fills it in.
+        return def.type === 'default' || def.type === 'prefault' || isOptional(def.innerType ?? def.in);
+    }
+    return false;
+}
+/**
+ * The type a `?` property carries, with the optionality itself taken off.
+ *
+ * `limit?: number | undefined` says the same thing twice and reads as though the
+ * two halves might differ. A `nullish` field keeps its `| null`, because that half
+ * is a value the server can actually send.
+ */
+function unwrapOptional(schema) {
+    const def = defOf(schema);
+    if (def?.type === 'optional')
+        return unwrapOptional(def.innerType);
+    if (def?.type === 'default' || def?.type === 'prefault')
+        return unwrapOptional(def.innerType);
+    return schema;
+}
+function literalOf(value) {
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (value === null)
+        return 'null';
+    return fail(`a literal of type ${typeof value} has no TypeScript spelling here`);
+}
+/**
+ * A schema as a TypeScript type.
+ *
+ * An entity's `fields` object is matched by IDENTITY, not by shape: `spec/model.ts`
+ * writes `output: todoEntities.item.fields`, so the very same object arrives here
+ * and prints as `Item`. Two entities that happen to share a shape stay two names,
+ * and an inline object that happens to match an entity stays inline — which is
+ * what the model actually said in both cases.
+ */
+function tsType(schema, ctx) {
+    const override = ctx.overrides.get(ctx.where);
+    if (override !== undefined) {
+        ctx.used.add(ctx.where);
+        return override;
+    }
+    const named = ctx.named.get(schema);
+    if (named)
+        return named;
+    const def = defOf(schema);
+    switch (def?.type) {
+        case 'string':
+            return 'string';
+        case 'number':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'bigint':
+            return 'bigint';
+        case 'unknown':
+        case 'any':
+            return 'unknown';
+        case 'null':
+            return 'null';
+        case 'literal': {
+            const values = def.values ?? [];
+            if (values.length === 0)
+                return fail(`${ctx.where}: a literal with no values`);
+            return values.map(literalOf).join(' | ');
+        }
+        case 'enum': {
+            const values = Object.values(def.entries ?? {});
+            if (values.length === 0)
+                return fail(`${ctx.where}: an enum with no members`);
+            return values.map(literalOf).join(' | ');
+        }
+        case 'array':
+            return `${maybeParen(tsType(def.element, ctx), ctx)}[]`;
+        case 'object':
+            return tsObject(def.shape ?? {}, ctx);
+        case 'record':
+            return `Record<${tsType(def.keyType, ctx)}, ${tsType(def.valueType, ctx)}>`;
+        case 'union': {
+            const options = def.options ?? [];
+            if (options.length === 0)
+                return fail(`${ctx.where}: a union with no options`);
+            return [...new Set(options.map((o) => tsType(o, ctx)))].join(' | ');
+        }
+        case 'optional':
+            // Reached only where optionality has no key to hang off — inside an array,
+            // say. As a property it is spelled `a?: T` by `tsObject` instead.
+            return `${tsType(def.innerType, ctx)} | undefined`;
+        case 'nullable':
+            return `${tsType(def.innerType, ctx)} | null`;
+        case 'nullish':
+            return `${tsType(def.innerType, ctx)} | null | undefined`;
+        case 'default':
+        case 'prefault':
+        case 'catch':
+        case 'readonly':
+        case 'nonoptional':
+            return tsType(def.innerType, ctx);
+        case 'pipe':
+            // `z.coerce.number()` is a pipe; the caller supplies its INPUT side.
+            return tsType(def.in, ctx);
+        default:
+            return fail(`${ctx.where}: no TypeScript spelling for a Zod '${def?.type ?? 'unrecognised'}' schema.\n` +
+                `  A generator that answered 'unknown' here would hand the app a green light over a\n` +
+                `  type it never checked.\n` +
+                `  Remedy, in order of preference: teach tsType() this case; declare the field with a\n` +
+                `  shape the client can carry; or, when the schema genuinely has no inferable input\n` +
+                `  type (a preprocess does not), state the type yourself in package.json —\n` +
+                `    "substrat": { "client": { "types": { ${JSON.stringify(ctx.where.split('.').slice(1).join('.'))}: "unknown" } } }`);
+    }
+}
+/** Parenthesise a union before `[]`, so `(A | B)[]` never prints as `A | B[]`. */
+function maybeParen(printed, _ctx) {
+    return printed.includes('|') && !printed.startsWith('(') ? `(${printed})` : printed;
+}
+/**
+ * One schema as TypeScript, with no operation around it.
+ *
+ * The printer's entry point for a test. `named` is the identity map an entity's
+ * `fields` would be in — pass one to check that a reference prints as its interface
+ * name rather than as an inline shape.
+ */
+export function tsTypeOf(schema, named = new Map()) {
+    return tsType(schema, { named, where: 'schema', overrides: new Map(), used: new Set() });
+}
+function tsObject(shape, ctx) {
+    const keys = Object.keys(shape);
+    if (keys.length === 0)
+        return 'Record<string, never>';
+    const fields = keys.map((key) => {
+        const optional = isOptional(shape[key]);
+        const value = optional ? unwrapOptional(shape[key]) : shape[key];
+        return `${key}${optional ? '?' : ''}: ${tsType(value, { ...ctx, where: `${ctx.where}.${key}` })}`;
+    });
+    return `{ ${fields.join('; ')} }`;
+}
+/** An entity's fields printed as a multi-line interface body. */
+function interfaceBody(shape, ctx) {
+    return Object.keys(shape)
+        .map((key) => {
+        const optional = isOptional(shape[key]);
+        const value = optional ? unwrapOptional(shape[key]) : shape[key];
+        return `  ${key}${optional ? '?' : ''}: ${tsType(value, { ...ctx, where: `${ctx.where}.${key}` })};`;
+    })
+        .join('\n');
+}
+// ---------------------------------------------------------------------------
+// Names.
+// ---------------------------------------------------------------------------
+const pascal = (s) => s.replace(/(^|[-_/])(\w)/g, (_, __, c) => c.toUpperCase());
+const camel = (s) => {
+    const p = pascal(s);
+    return p.charAt(0).toLowerCase() + p.slice(1);
+};
+/**
+ * `todo/create-list` → `createList`; `protocol/get` → `protocolGet`.
+ *
+ * The vertical's OWN prefix is dropped — it is the client's identity and repeating it
+ * on every method says nothing (`api.callout.calloutCreateOrder()`). A composed
+ * engine's prefix stays, and has to: callout binds `workorder/get`, `protocol/get` and
+ * `invoicing/get` at three URLs, and a client with one `get()` would reach whichever
+ * bag was read last. Renaming an engine's operation to suit a vertical's client is not
+ * a thing a vertical may do, so the disambiguation belongs here.
+ */
+export const methodName = (operation, ownPrefix) => {
+    const [prefix, ...rest] = operation.split('/');
+    const tail = rest.join('/');
+    return prefix === ownPrefix ? camel(tail) : camel(`${prefix}/${tail}`);
+};
+const pathParams = (path) => [...path.matchAll(/\{(\w+)\}/g)].map((m) => m[1]);
+/**
+ * The fixed runtime, which is a template rather than a derivation — but it is
+ * emitted rather than shipped as a package for the same reason the types are:
+ * the app depends on nothing, and one file is one thing to review.
+ */
+function preamble(name, source, anyPaged, stated) {
+    return `// GENERATED by tools/client-emit.mts from ${source} — do not edit by hand.${stated.length
+        ? `
+//
+// HAND-STATED TYPES (substrat.client.types). These schemas have no inferable input
+// type — a \`z.preprocess\` infers \`unknown\` by construction — so the type below was
+// decided by a person, not derived, and is not checked against the schema:
+${stated.map((line) => `//   ${line}`).join('\n')}`
+        : ''}
+//
+// Re-emit with \`pnpm lint:client\`; CI runs \`pnpm lint:client --check\` and fails on
+// drift, so the client cannot fall behind the model the way a hand-written one did.
+//
+// Standalone on purpose: no imports, so the browser bundle carries no schema library
+// and \`tools/declared-deps.mjs\` has nothing to object to.
+
+/** A failed request. \`status\` is the interesting field — 403 is the permission model answering. */
+export class ApiError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+    readonly body: unknown,
+  ) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+${anyPaged
+        ? `
+/**
+ * One page of a paged read, reassembled from the response.
+ *
+ * The BODY is the entries and always was; the walk rides in headers (#829), which is
+ * what let paging be adopted without renaming a live endpoint's response. This puts
+ * the two back together so a caller sees a page rather than a header protocol.
+ *
+ * \`next\` is an absolute URL to FOLLOW (RFC 8288), not a cursor to reassemble — this
+ * request's filters and page size travel with it. Its absence is how the walk ends.
+ */
+export interface Paged<T> {
+  entries: T[];
+  /** Hand back to \`follow()\`. \`null\` when there is no next page. */
+  next: string | null;
+  /** From \`X-Total-Count\`, and only for a read that declares \`total\`. */
+  total: number | null;
+}
+`
+        : ''}
+export interface ClientOptions {
+  /** Prefixed to every declared path. Matches \`mountOperations\`' own default. */
+  baseUrl?: string;
+  /** Per-request headers — an auth token, or this demo's \`x-principal\` persona seam. */
+  headers?: () => Record<string, string>;
+  /** Injectable so the client works under a test harness, not only in a browser. */
+  fetch?: typeof globalThis.fetch;
+  /**
+   * Pull a message out of an error body.
+   *
+   * The one thing here the model does NOT declare: a vertical picks its error
+   * envelope in its own \`app.onError\`, so this is a best effort over the shapes in
+   * use — \`{ error }\`, and problem+json's \`detail\`/\`title\` — and an app that
+   * answers something else says so here rather than being guessed at.
+   */
+  errorMessage?: (body: unknown, response: Response) => string | undefined;
+}
+
+function defaultErrorMessage(body: unknown): string | undefined {
+  if (typeof body !== 'object' || body === null) return undefined;
+  const b = body as Record<string, unknown>;
+  for (const key of ['error', 'detail', 'title', 'message']) {
+    if (typeof b[key] === 'string') return b[key] as string;
+  }
+  return undefined;
+}
+`;
+}
+export function renderClient(vertical, config, source, entities, operations, extras) {
+    const named = new Map();
+    const claimedBy = new Map();
+    const claim = (schema, name, origin) => {
+        const already = claimedBy.get(name);
+        if (already !== undefined && named.get(schema) !== name) {
+            fail(`${vertical}: two different schemas both want the interface name \`${name}\` ` +
+                `(${already}, ${origin}).\n` +
+                `  Remedy: rename one in substrat.client.schemas.`);
+        }
+        claimedBy.set(name, origin);
+        named.set(schema, name);
+    };
+    for (const [key, def] of Object.entries(entities)) {
+        const fields = def?.fields;
+        if (!fields)
+            fail(`${vertical}: entity '${key}' has no \`fields\` schema`);
+        claim(fields, pascal(key), `entity ${key}`);
+    }
+    for (const [name, exportName] of Object.entries(config.schemas ?? {})) {
+        const schema = extras[exportName];
+        if (schema === undefined)
+            fail(`${vertical}: substrat.client.schemas names \`${exportName}\`, which nothing exports`);
+        claim(schema, name, `schema ${exportName}`);
+    }
+    // Keys are declared relative to the operation, so the vertical's own name is not
+    // repeated in every entry; `where` carries the prefix, so add it here.
+    const overrides = new Map(Object.entries(config.types ?? {}).map(([k, v]) => [`${vertical}.${k}`, v]));
+    const used = new Set();
+    const ctx = { named, where: vertical, overrides, used };
+    // Every named type gets a block: an entity's `fields`, and each extra schema. A name
+    // in the identity map with no interface behind it is a file that references a type it
+    // never declares — which typechecks nowhere and would only be found by building.
+    const blocks = [
+        ...Object.entries(entities).map(([key, def]) => ({
+            name: pascal(key),
+            note: `\`${def.table ?? key}\` — declared in ${source}`,
+            schema: def.fields,
+            where: `${vertical}.${key}`,
+        })),
+        ...Object.entries(config.schemas ?? {}).map(([name, exportName]) => ({
+            name,
+            note: `\`${exportName}\` — a published schema, not a stored row`,
+            schema: extras[exportName],
+            where: `${vertical}.${exportName}`,
+        })),
+    ];
+    const entityBlocks = blocks.map(({ name, note, schema, where }) => {
+        const def = defOf(schema);
+        if (def?.type !== 'object') {
+            fail(`${vertical}: \`${name}\` is not an object schema, so it cannot be an interface.\n` +
+                `  Remedy: drop it from substrat.client.schemas — a union or an array is spelled\n` +
+                `  inline where it is used.`);
+        }
+        // Printed with this schema temporarily UNNAMED, or the body would be `Foo` referring
+        // to itself. Every other reference to it still resolves to the name.
+        const named2 = new Map(ctx.named);
+        named2.delete(schema);
+        return `/** ${note}. */\nexport interface ${name} {\n${interfaceBody(def.shape ?? {}, { ...ctx, named: named2, where })}\n}`;
+    });
+    // Then one method per operation that declares an HTTP binding. An operation
+    // without one is not part of this app's surface — a composed engine's, say.
+    const declared = Object.entries(operations)
+        .map(([operation, op]) => [operation, op])
+        .filter((entry) => Boolean(entry[1]?.http))
+        .sort(([a], [b]) => a.localeCompare(b));
+    if (declared.length === 0)
+        fail(`${vertical}: no operation declares an \`http\` binding — a client over nothing`);
+    // The first named bag is the vertical's own `defineOperations`; the rest are engine
+    // route bindings. Taken from INSERTION order (the bags are merged in the order
+    // package.json names them), never from `declared`, which is sorted for a stable
+    // artifact — reading it there would make the answer depend on the alphabet, and it
+    // happens to be right for callout, which is the worst way for it to be wrong.
+    const ownPrefix = Object.keys(operations)[0]?.split('/')[0] ?? '';
+    const seen = new Map();
+    const methods = [];
+    const impls = [];
+    let anyPaged = false;
+    for (const [operation, op] of declared) {
+        const method = methodName(operation, ownPrefix);
+        const clash = seen.get(method);
+        if (clash) {
+            fail(`${vertical}: '${clash}' and '${operation}' both name the client method \`${method}\`.\n` +
+                `  Two methods with one name is a call site that silently reaches the wrong\n` +
+                `  endpoint. A composed engine's prefix is kept precisely to avoid this, so a\n` +
+                `  collision here means two operations of the SAME module share a name.\n` +
+                `  Remedy: rename one of them.`);
+        }
+        seen.set(method, operation);
+        const where = `${vertical}.${operation}`;
+        const params = pathParams(op.http.path);
+        const inputShape = (defOf(op.input)?.shape ?? {});
+        const hasInput = op.input !== undefined || params.length > 0;
+        // The parameter type is the input schema WHOLE — path parameters included.
+        // `mountOperations` reads them off the URL, but they are declared input fields
+        // and the compile-checked `{var}` join says so, so the caller passes one object.
+        const inputType = op.input ? tsObject(inputShape, { ...ctx, where: `${where}.input` }) : '{}';
+        const entryType = tsType(op.output, { ...ctx, where: `${where}.output` });
+        const returnType = op.paged ? `Paged<${maybeParen(entryType, ctx)}>` : entryType;
+        if (op.paged)
+            anyPaged = true;
+        const signature = hasInput ? `input: ${inputType}` : '';
+        const doc = [
+            '  /**',
+            `   * ${op.summary ?? operation}`,
+            '   *',
+            `   * \`${op.http.method} ${op.http.path}\` — \`${operation}\``,
+            ...(op.paged ? ['   *', '   * Paged: walk it with `follow(page.next)` until `next` is `null`.'] : []),
+            '   */',
+        ].join('\n');
+        methods.push(`${doc}\n  ${method}(${signature}): Promise<${returnType}>;`);
+        // Path parameters are spliced out of the payload; what is left is a body for a
+        // writing method and a query string for a read — exactly what mountOperations
+        // expects on the other side, which is the only reason this can be derived.
+        const takesBody = ['POST', 'PUT', 'PATCH'].includes(op.http.method);
+        const pathExpr = params.length
+            ? '`' + op.http.path.replace(/\{(\w+)\}/g, (_, p) => `\${encodeURIComponent(String(input.${p}))}`) + '`'
+            : JSON.stringify(op.http.path);
+        const rest = params.length ? `omit(input, ${JSON.stringify(params)})` : hasInput ? 'input' : 'undefined';
+        const call = op.paged ? 'page' : 'send';
+        impls.push(`    ${method}: (${hasInput ? 'input: Args' : ''}) =>\n` +
+            `      ${call}(${pathExpr}, ${JSON.stringify(op.http.method)}, ${takesBody ? `${rest}, undefined` : `undefined, ${rest}`}),`);
+    }
+    const runtime = `
+/**
+ * The plumbing below is deliberately untyped against the interface above, and cast
+ * once at the end.
+ *
+ * \`send\` cannot know an operation's return type — it has a \`Response\`, not a schema
+ * — so every method would otherwise need its own \`as\` and the file would carry
+ * fourteen casts instead of one. The interface is what a caller sees, and it IS
+ * derived from the model; this is the seam where a runtime that speaks \`unknown\`
+ * meets it.
+ */
+type Args = Record<string, unknown>;
+
+const omit = (input: Record<string, unknown>, keys: string[]): Record<string, unknown> => {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(input ?? {})) if (!keys.includes(k)) out[k] = v;
+  return out;
+};
+
+/** Declared fields become a query string; \`undefined\` is absent rather than the string "undefined". */
+const query = (values: Record<string, unknown> | undefined): string => {
+  if (!values) return '';
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(values)) {
+    if (v === undefined || v === null) continue;
+    params.set(k, String(v));
+  }
+  const s = params.toString();
+  return s ? \`?\${s}\` : '';
+};
+${anyPaged
+        ? `
+/**
+ * The \`rel="next"\` URL out of an RFC 8288 \`Link\` header, or null.
+ *
+ * Only \`next\` is looked for because only \`next\` is sent: keyset paging walks one
+ * way and does not know its own offset, so there is no \`prev\`, \`first\` or \`last\`
+ * to honour. A header naming some other relation is not this walk's.
+ */
+const nextFrom = (header: string | null): string | null => {
+  if (!header) return null;
+  for (const part of header.split(',')) {
+    const match = /^\\s*<([^>]+)>\\s*;\\s*(.+)$/.exec(part);
+    if (match && /rel\\s*=\\s*"?next"?/.test(match[2] as string)) return match[1] as string;
+  }
+  return null;
+};
+`
+        : ''}
+export function createClient(options: ClientOptions = {}): ${config.name}Client {
+  const baseUrl = options.baseUrl ?? '/api';
+  const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  const readMessage = options.errorMessage ?? defaultErrorMessage;
+
+  /** One request, against a path that is ALREADY prefixed and query-stringed. */
+  const raw = async (fullPath: string, method: string, body: unknown): Promise<Response> => {
+    const hasBody = body !== undefined && method !== 'GET' && method !== 'DELETE';
+    return await doFetch(fullPath, {
+      method,
+      headers: {
+        ...(hasBody ? { 'content-type': 'application/json' } : {}),
+        ...(options.headers?.() ?? {}),
+      },
+      ...(hasBody ? { body: JSON.stringify(body) } : {}),
+    });
+  };
+
+  const parse = async (res: Response): Promise<unknown> => {
+    const text = await res.text();
+    const body: unknown = text ? JSON.parse(text) : null;
+    if (!res.ok) throw new ApiError(res.status, readMessage(body, res) ?? res.statusText, body);
+    return body;
+  };
+
+  const send = async (path: string, method: string, body: unknown, params: unknown): Promise<unknown> =>
+    await parse(await raw(\`\${baseUrl}\${path}\${query(params as Record<string, unknown>)}\`, method, body));
+${anyPaged
+        ? `
+  /**
+   * A paged read: the entries come from the body, the walk from the headers.
+   *
+   * A cross-origin caller reads neither header without \`Access-Control-Expose-Headers\`,
+   * and the symptom is not an error — it is a list that looks like it has one page. Under
+   * a same-origin dev proxy (this demo) or a same-origin deployment, both are readable.
+   */
+  const readPage = async (res: Response): Promise<Paged<unknown>> => {
+    const entries = (await parse(res)) as unknown[];
+    const total = res.headers.get('X-Total-Count');
+    return { entries, next: nextFrom(res.headers.get('Link')), total: total === null ? null : Number(total) };
+  };
+
+  const page = async (path: string, method: string, body: unknown, params: unknown): Promise<Paged<unknown>> =>
+    await readPage(await raw(\`\${baseUrl}\${path}\${query(params as Record<string, unknown>)}\`, method, body));
+`
+        : ''}
+  return {
+${impls.join('\n')}${anyPaged
+        ? `
+    follow: async (next: string) => {
+      // The link names the API's OWN origin, which under a dev proxy is not the origin
+      // this page was served from. So the path is kept and the origin is taken from
+      // whatever this client was configured to talk to: relative for a browser, which
+      // keeps the request same-origin, absolute for a harness that has no page.
+      const link = new URL(next, 'http://substrat.invalid');
+      const target = /^https?:\\/\\//.test(baseUrl)
+        ? new URL(link.pathname + link.search, baseUrl).href
+        : link.pathname + link.search;
+      return await readPage(await raw(target, 'GET', undefined));
+    },`
+        : ''}
+  } as unknown as ${config.name}Client;
+}
+`;
+    const followSignature = anyPaged
+        ? `
+  /**
+   * Fetch the next page of any paged read, given a previous page's \`next\`.
+   *
+   * One method for every paged read rather than one per read: \`next\` is a URL that
+   * already carries the filters, so there is nothing left for a caller to restate.
+   */
+  follow<T>(next: string): Promise<Paged<T>>;
+`
+        : '';
+    const unused = [...overrides.keys()].filter((k) => !used.has(k));
+    if (unused.length) {
+        fail(`${vertical}: substrat.client.types names ${unused.map((k) => k.slice(vertical.length + 1)).join(', ')}, ` +
+            `which the printer never reached.\n` +
+            `  A stale escape hatch reads as a live decision. Remedy: remove the entry.`);
+    }
+    return [
+        preamble(config.name, source, anyPaged, [...used].sort().map((k) => `${k.slice(vertical.length + 1)} → ${overrides.get(k)}`)),
+        entityBlocks.join('\n\n'),
+        `/** Every operation this vertical binds to HTTP, one method each. */\nexport interface ${config.name}Client {\n${methods.join('\n\n')}\n${followSignature}}`,
+        runtime.trimStart(),
+    ].join('\n\n');
+}
+//# sourceMappingURL=emit-client.js.map

package/dist/emit-client.js.map

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

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

@@ -2,4 +2,6 @@ export { emitTables, columnsOf, primaryKeyConstraint, uniqueConstraints, type Em
 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"}
+{"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

@@ -2,4 +2,6 @@ export { emitTables, columnsOf, primaryKeyConstraint, uniqueConstraints, } from
 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"}
+{"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.5.3",
+  "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.82.0"
+    "@substrat-run/contracts": "0.84.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",