@entifix/core 0.1.0-0

package/dist/types/EntitySelection.d.ts

@@ -0,0 +1,117 @@
+import type { Entity, EntityId } from './Entity.js';
+import type { FilterGroup } from './EntityFiltering.js';
+/**
+ * What a collection-bound action acts on.
+ *
+ * The two members are **not** two shapes of one idea, and collapsing them is
+ * the defect this type exists to prevent. "Select all on this page" is a list
+ * of ids the browser already holds; "select all 3.200 matching the filter" is a
+ * *filter expression the server evaluates* — the set is by definition larger
+ * than the page, so there is nothing to enumerate. Written as one optional
+ * field (`ids?: …` beside `all?: boolean`) the second quietly becomes the
+ * first, and a bulk action that reads as "the 25 rows I can see" runs over
+ * every row in the store.
+ *
+ * `excluded` is what makes the second member usable rather than all-or-nothing:
+ * an operator takes everything matching and then drops the two rows they know
+ * about. It is a subtraction from a server-side set, never an addition to a
+ * client-side one.
+ *
+ * `total` is carried rather than derived because only the server knows it, and
+ * the count is the whole affordance — "Retirar 3.200 marcas" is a different
+ * sentence from "Retirar", and the user has to read the number *before* they
+ * confirm ([ADR 0035](../../../../../../docs/adr/0035-entity-actions-selection-and-bulk.md)).
+ */
+export type EntitySelection<TEntity extends Entity> = {
+    mode: 'ids';
+    ids: ReadonlySet<EntityId>;
+} | {
+    mode: 'matching';
+    /** The filtering in effect when the set was taken. Absent means "every row". */
+    filtering?: FilterGroup<TEntity>;
+    /** How many rows the server said match. */
+    total: number;
+    /** Rows the user removed from the matching set. */
+    excluded: ReadonlySet<EntityId>;
+};
+/** An empty `ids` selection — the state a table starts and clears to. */
+export declare const emptySelection: <TEntity extends Entity>() => EntitySelection<TEntity>;
+/**
+ * How many rows the action will touch.
+ *
+ * For `matching` this is the server's count minus what the user removed, which
+ * is the number the confirmation must show. It can only ever be an estimate —
+ * rows may have been written since the count was taken — and that is inherent
+ * to the mode rather than a defect in it.
+ */
+export declare function selectionSize<TEntity extends Entity>(selection: EntitySelection<TEntity>): number;
+/** Whether one row is part of the selection. */
+export declare function isSelected<TEntity extends Entity>(selection: EntitySelection<TEntity>, id: EntityId): boolean;
+/** Whether the action would touch nothing. */
+export declare function isSelectionEmpty<TEntity extends Entity>(selection: EntitySelection<TEntity>): boolean;
+/**
+ * Add or remove one row, in whichever direction the current mode means.
+ *
+ * In `ids` mode a toggle writes the id set; in `matching` mode it writes the
+ * *exclusion* set, because the selection is the server's answer and the only
+ * thing the browser owns is what was taken back out of it. Both return a new
+ * value — the selection is controlled state held above the table.
+ */
+export declare function toggleSelected<TEntity extends Entity>(selection: EntitySelection<TEntity>, id: EntityId, selected: boolean): EntitySelection<TEntity>;
+/**
+ * The ids a bulk request should carry, or `undefined` when it must carry the
+ * filter instead.
+ *
+ * A caller that treats `undefined` as "no rows" has made exactly the mistake
+ * the two modes exist to prevent, so this returns `undefined` rather than an
+ * empty array: an empty array is a plausible payload and would silently do
+ * nothing, where `undefined` cannot be sent at all.
+ */
+export declare function selectionIds<TEntity extends Entity>(selection: EntitySelection<TEntity>): EntityId[] | undefined;
+/**
+ * The selection as it crosses the wire.
+ *
+ * `Set` does not survive `JSON.stringify` — it serializes to `{}`, silently,
+ * and arrives as an empty object that reads as "no rows excluded" rather than
+ * as an error. That is the same class of fault ADR 0032 recorded for autosaved
+ * drafts, and it is worse here: a `matching` selection whose exclusions
+ * evaporate acts on rows the operator deliberately took out.
+ *
+ * So the wire form is arrays and the in-memory form is sets, named separately
+ * rather than one type used loosely. The set is the right in-memory shape
+ * because it dedupes by construction and answers `isSelected` in constant time;
+ * the array is the only JSON shape there is.
+ */
+export type EntitySelectionWire<TEntity extends Entity> = {
+    mode: 'ids';
+    ids: EntityId[];
+} | {
+    mode: 'matching';
+    filtering?: FilterGroup<TEntity>;
+    total: number;
+    excluded: EntityId[];
+};
+/**
+ * Convert a selection to its wire form.
+ *
+ * ⚠️ **`Array.from(set)`, never `[...set]`.** Every package here compiles with
+ * `"loose": true` in its `.swcrc`, and SWC's loose spread helper skips the
+ * iterable protocol: it treats the operand as array-like, finds no `length` on
+ * a `Set`, and **wraps it as a single element** — `[...someSet]` becomes
+ * `[Set]`, silently, with the right `.size` still on the inner value. Measured
+ * against the running service, where it turned a two-row selection into one
+ * outcome whose `id` serialized as `{}`. Vitest and Turbopack transpile
+ * differently, so it passes every unit test and only fails in the built
+ * bundle.
+ */
+export declare function toWireSelection<TEntity extends Entity>(selection: EntitySelection<TEntity>): EntitySelectionWire<TEntity>;
+/**
+ * Read a wire selection back, rejecting anything that is not one.
+ *
+ * Untrusted input: this arrives in a request body and decides which rows a
+ * bulk write touches. A missing `mode` must not fall through to a default —
+ * defaulting to `ids` with no ids would act on nothing (merely confusing),
+ * while defaulting to `matching` would act on **everything**.
+ */
+export declare function readWireSelection<TEntity extends Entity>(value: unknown): EntitySelection<TEntity> | undefined;
+//# sourceMappingURL=EntitySelection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EntitySelection.d.ts","sourceRoot":"","sources":["../../src/types/EntitySelection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,eAAe,CAAC,OAAO,SAAS,MAAM,IAC9C;IACE,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;CAC5B,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,gFAAgF;IAChF,SAAS,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IACjC,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,QAAQ,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;CACjC,CAAC;AAEN,yEAAyE;AACzE,eAAO,MAAM,cAAc,GACzB,OAAO,SAAS,MAAM,OACnB,eAAe,CAAC,OAAO,CAAgD,CAAC;AAE7E;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,SAAS,MAAM,EAClD,SAAS,EAAE,eAAe,CAAC,OAAO,CAAC,GAClC,MAAM,CAIR;AAED,gDAAgD;AAChD,wBAAgB,UAAU,CAAC,OAAO,SAAS,MAAM,EAC/C,SAAS,EAAE,eAAe,CAAC,OAAO,CAAC,EACnC,EAAE,EAAE,QAAQ,GACX,OAAO,CAIT;AAED,8CAA8C;AAC9C,wBAAgB,gBAAgB,CAAC,OAAO,SAAS,MAAM,EACrD,SAAS,EAAE,eAAe,CAAC,OAAO,CAAC,GAClC,OAAO,CAET;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,SAAS,MAAM,EACnD,SAAS,EAAE,eAAe,CAAC,OAAO,CAAC,EACnC,EAAE,EAAE,QAAQ,EACZ,QAAQ,EAAE,OAAO,GAChB,eAAe,CAAC,OAAO,CAAC,CAY1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,OAAO,SAAS,MAAM,EACjD,SAAS,EAAE,eAAe,CAAC,OAAO,CAAC,GAClC,QAAQ,EAAE,GAAG,SAAS,CAExB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,mBAAmB,CAAC,OAAO,SAAS,MAAM,IAClD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,QAAQ,EAAE,CAAA;CAAE,GAChC;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,QAAQ,EAAE,CAAC;CACtB,CAAC;AAEN;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,OAAO,SAAS,MAAM,EACpD,SAAS,EAAE,eAAe,CAAC,OAAO,CAAC,GAClC,mBAAmB,CAAC,OAAO,CAAC,CAI9B;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,SAAS,MAAM,EACtD,KAAK,EAAE,OAAO,GACb,eAAe,CAAC,OAAO,CAAC,GAAG,SAAS,CA0BtC"}

package/dist/types/EntitySelection.js

@@ -0,0 +1,107 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/** An empty `ids` selection — the state a table starts and clears to. */ export const emptySelection = ()=>({
+        mode: 'ids',
+        ids: new Set()
+    });
+/**
+ * How many rows the action will touch.
+ *
+ * For `matching` this is the server's count minus what the user removed, which
+ * is the number the confirmation must show. It can only ever be an estimate —
+ * rows may have been written since the count was taken — and that is inherent
+ * to the mode rather than a defect in it.
+ */ export function selectionSize(selection) {
+    return selection.mode === 'ids' ? selection.ids.size : Math.max(0, selection.total - selection.excluded.size);
+}
+/** Whether one row is part of the selection. */ export function isSelected(selection, id) {
+    return selection.mode === 'ids' ? selection.ids.has(id) : !selection.excluded.has(id);
+}
+/** Whether the action would touch nothing. */ export function isSelectionEmpty(selection) {
+    return selectionSize(selection) === 0;
+}
+/**
+ * Add or remove one row, in whichever direction the current mode means.
+ *
+ * In `ids` mode a toggle writes the id set; in `matching` mode it writes the
+ * *exclusion* set, because the selection is the server's answer and the only
+ * thing the browser owns is what was taken back out of it. Both return a new
+ * value — the selection is controlled state held above the table.
+ */ export function toggleSelected(selection, id, selected) {
+    if (selection.mode === 'ids') {
+        const ids = new Set(selection.ids);
+        if (selected) ids.add(id);
+        else ids.delete(id);
+        return {
+            mode: 'ids',
+            ids
+        };
+    }
+    const excluded = new Set(selection.excluded);
+    if (selected) excluded.delete(id);
+    else excluded.add(id);
+    return _extends({}, selection, {
+        excluded
+    });
+}
+/**
+ * The ids a bulk request should carry, or `undefined` when it must carry the
+ * filter instead.
+ *
+ * A caller that treats `undefined` as "no rows" has made exactly the mistake
+ * the two modes exist to prevent, so this returns `undefined` rather than an
+ * empty array: an empty array is a plausible payload and would silently do
+ * nothing, where `undefined` cannot be sent at all.
+ */ export function selectionIds(selection) {
+    return selection.mode === 'ids' ? Array.from(selection.ids) : undefined;
+}
+/**
+ * Convert a selection to its wire form.
+ *
+ * ⚠️ **`Array.from(set)`, never `[...set]`.** Every package here compiles with
+ * `"loose": true` in its `.swcrc`, and SWC's loose spread helper skips the
+ * iterable protocol: it treats the operand as array-like, finds no `length` on
+ * a `Set`, and **wraps it as a single element** — `[...someSet]` becomes
+ * `[Set]`, silently, with the right `.size` still on the inner value. Measured
+ * against the running service, where it turned a two-row selection into one
+ * outcome whose `id` serialized as `{}`. Vitest and Turbopack transpile
+ * differently, so it passes every unit test and only fails in the built
+ * bundle.
+ */ export function toWireSelection(selection) {
+    return selection.mode === 'ids' ? {
+        mode: 'ids',
+        ids: Array.from(selection.ids)
+    } : _extends({}, selection, {
+        excluded: Array.from(selection.excluded)
+    });
+}
+/**
+ * Read a wire selection back, rejecting anything that is not one.
+ *
+ * Untrusted input: this arrives in a request body and decides which rows a
+ * bulk write touches. A missing `mode` must not fall through to a default —
+ * defaulting to `ids` with no ids would act on nothing (merely confusing),
+ * while defaulting to `matching` would act on **everything**.
+ */ export function readWireSelection(value) {
+    if (typeof value !== 'object' || value === null) return undefined;
+    const candidate = value;
+    if (candidate.mode === 'ids') {
+        return Array.isArray(candidate.ids) ? {
+            mode: 'ids',
+            ids: new Set(candidate.ids)
+        } : undefined;
+    }
+    if (candidate.mode === 'matching') {
+        const matching = candidate;
+        if (typeof matching.total !== 'number') return undefined;
+        if (!Array.isArray(matching.excluded)) return undefined;
+        return {
+            mode: 'matching',
+            filtering: matching.filtering,
+            total: matching.total,
+            excluded: new Set(matching.excluded)
+        };
+    }
+    return undefined;
+}
+
+//# sourceMappingURL=EntitySelection.js.map

package/dist/types/EntitySelection.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/EntitySelection.ts"],"sourcesContent":["import type { Entity, EntityId } from './Entity.js';\nimport type { FilterGroup } from './EntityFiltering.js';\n\n/**\n * What a collection-bound action acts on.\n *\n * The two members are **not** two shapes of one idea, and collapsing them is\n * the defect this type exists to prevent. \"Select all on this page\" is a list\n * of ids the browser already holds; \"select all 3.200 matching the filter\" is a\n * *filter expression the server evaluates* — the set is by definition larger\n * than the page, so there is nothing to enumerate. Written as one optional\n * field (`ids?: …` beside `all?: boolean`) the second quietly becomes the\n * first, and a bulk action that reads as \"the 25 rows I can see\" runs over\n * every row in the store.\n *\n * `excluded` is what makes the second member usable rather than all-or-nothing:\n * an operator takes everything matching and then drops the two rows they know\n * about. It is a subtraction from a server-side set, never an addition to a\n * client-side one.\n *\n * `total` is carried rather than derived because only the server knows it, and\n * the count is the whole affordance — \"Retirar 3.200 marcas\" is a different\n * sentence from \"Retirar\", and the user has to read the number *before* they\n * confirm ([ADR 0035](../../../../../../docs/adr/0035-entity-actions-selection-and-bulk.md)).\n */\nexport type EntitySelection<TEntity extends Entity> =\n  | {\n      mode: 'ids';\n      ids: ReadonlySet<EntityId>;\n    }\n  | {\n      mode: 'matching';\n      /** The filtering in effect when the set was taken. Absent means \"every row\". */\n      filtering?: FilterGroup<TEntity>;\n      /** How many rows the server said match. */\n      total: number;\n      /** Rows the user removed from the matching set. */\n      excluded: ReadonlySet<EntityId>;\n    };\n\n/** An empty `ids` selection — the state a table starts and clears to. */\nexport const emptySelection = <\n  TEntity extends Entity,\n>(): EntitySelection<TEntity> => ({ mode: 'ids', ids: new Set<EntityId>() });\n\n/**\n * How many rows the action will touch.\n *\n * For `matching` this is the server's count minus what the user removed, which\n * is the number the confirmation must show. It can only ever be an estimate —\n * rows may have been written since the count was taken — and that is inherent\n * to the mode rather than a defect in it.\n */\nexport function selectionSize<TEntity extends Entity>(\n  selection: EntitySelection<TEntity>,\n): number {\n  return selection.mode === 'ids'\n    ? selection.ids.size\n    : Math.max(0, selection.total - selection.excluded.size);\n}\n\n/** Whether one row is part of the selection. */\nexport function isSelected<TEntity extends Entity>(\n  selection: EntitySelection<TEntity>,\n  id: EntityId,\n): boolean {\n  return selection.mode === 'ids'\n    ? selection.ids.has(id)\n    : !selection.excluded.has(id);\n}\n\n/** Whether the action would touch nothing. */\nexport function isSelectionEmpty<TEntity extends Entity>(\n  selection: EntitySelection<TEntity>,\n): boolean {\n  return selectionSize(selection) === 0;\n}\n\n/**\n * Add or remove one row, in whichever direction the current mode means.\n *\n * In `ids` mode a toggle writes the id set; in `matching` mode it writes the\n * *exclusion* set, because the selection is the server's answer and the only\n * thing the browser owns is what was taken back out of it. Both return a new\n * value — the selection is controlled state held above the table.\n */\nexport function toggleSelected<TEntity extends Entity>(\n  selection: EntitySelection<TEntity>,\n  id: EntityId,\n  selected: boolean,\n): EntitySelection<TEntity> {\n  if (selection.mode === 'ids') {\n    const ids = new Set(selection.ids);\n    if (selected) ids.add(id);\n    else ids.delete(id);\n    return { mode: 'ids', ids };\n  }\n\n  const excluded = new Set(selection.excluded);\n  if (selected) excluded.delete(id);\n  else excluded.add(id);\n  return { ...selection, excluded };\n}\n\n/**\n * The ids a bulk request should carry, or `undefined` when it must carry the\n * filter instead.\n *\n * A caller that treats `undefined` as \"no rows\" has made exactly the mistake\n * the two modes exist to prevent, so this returns `undefined` rather than an\n * empty array: an empty array is a plausible payload and would silently do\n * nothing, where `undefined` cannot be sent at all.\n */\nexport function selectionIds<TEntity extends Entity>(\n  selection: EntitySelection<TEntity>,\n): EntityId[] | undefined {\n  return selection.mode === 'ids' ? Array.from(selection.ids) : undefined;\n}\n\n/**\n * The selection as it crosses the wire.\n *\n * `Set` does not survive `JSON.stringify` — it serializes to `{}`, silently,\n * and arrives as an empty object that reads as \"no rows excluded\" rather than\n * as an error. That is the same class of fault ADR 0032 recorded for autosaved\n * drafts, and it is worse here: a `matching` selection whose exclusions\n * evaporate acts on rows the operator deliberately took out.\n *\n * So the wire form is arrays and the in-memory form is sets, named separately\n * rather than one type used loosely. The set is the right in-memory shape\n * because it dedupes by construction and answers `isSelected` in constant time;\n * the array is the only JSON shape there is.\n */\nexport type EntitySelectionWire<TEntity extends Entity> =\n  | { mode: 'ids'; ids: EntityId[] }\n  | {\n      mode: 'matching';\n      filtering?: FilterGroup<TEntity>;\n      total: number;\n      excluded: EntityId[];\n    };\n\n/**\n * Convert a selection to its wire form.\n *\n * ⚠️ **`Array.from(set)`, never `[...set]`.** Every package here compiles with\n * `\"loose\": true` in its `.swcrc`, and SWC's loose spread helper skips the\n * iterable protocol: it treats the operand as array-like, finds no `length` on\n * a `Set`, and **wraps it as a single element** — `[...someSet]` becomes\n * `[Set]`, silently, with the right `.size` still on the inner value. Measured\n * against the running service, where it turned a two-row selection into one\n * outcome whose `id` serialized as `{}`. Vitest and Turbopack transpile\n * differently, so it passes every unit test and only fails in the built\n * bundle.\n */\nexport function toWireSelection<TEntity extends Entity>(\n  selection: EntitySelection<TEntity>,\n): EntitySelectionWire<TEntity> {\n  return selection.mode === 'ids'\n    ? { mode: 'ids', ids: Array.from(selection.ids) }\n    : { ...selection, excluded: Array.from(selection.excluded) };\n}\n\n/**\n * Read a wire selection back, rejecting anything that is not one.\n *\n * Untrusted input: this arrives in a request body and decides which rows a\n * bulk write touches. A missing `mode` must not fall through to a default —\n * defaulting to `ids` with no ids would act on nothing (merely confusing),\n * while defaulting to `matching` would act on **everything**.\n */\nexport function readWireSelection<TEntity extends Entity>(\n  value: unknown,\n): EntitySelection<TEntity> | undefined {\n  if (typeof value !== 'object' || value === null) return undefined;\n  const candidate = value as Partial<EntitySelectionWire<TEntity>>;\n\n  if (candidate.mode === 'ids') {\n    return Array.isArray(candidate.ids)\n      ? { mode: 'ids', ids: new Set(candidate.ids) }\n      : undefined;\n  }\n\n  if (candidate.mode === 'matching') {\n    const matching = candidate as Extract<\n      EntitySelectionWire<TEntity>,\n      { mode: 'matching' }\n    >;\n    if (typeof matching.total !== 'number') return undefined;\n    if (!Array.isArray(matching.excluded)) return undefined;\n    return {\n      mode: 'matching',\n      filtering: matching.filtering,\n      total: matching.total,\n      excluded: new Set(matching.excluded),\n    };\n  }\n\n  return undefined;\n}\n"],"names":["emptySelection","mode","ids","Set","selectionSize","selection","size","Math","max","total","excluded","isSelected","id","has","isSelectionEmpty","toggleSelected","selected","add","delete","selectionIds","Array","from","undefined","toWireSelection","readWireSelection","value","candidate","isArray","matching","filtering"],"mappings":";AAwCA,uEAAuE,GACvE,OAAO,MAAMA,iBAAiB,IAEI,CAAA;QAAEC,MAAM;QAAOC,KAAK,IAAIC;IAAgB,CAAA,EAAG;AAE7E;;;;;;;CAOC,GACD,OAAO,SAASC,cACdC,SAAmC;IAEnC,OAAOA,UAAUJ,IAAI,KAAK,QACtBI,UAAUH,GAAG,CAACI,IAAI,GAClBC,KAAKC,GAAG,CAAC,GAAGH,UAAUI,KAAK,GAAGJ,UAAUK,QAAQ,CAACJ,IAAI;AAC3D;AAEA,8CAA8C,GAC9C,OAAO,SAASK,WACdN,SAAmC,EACnCO,EAAY;IAEZ,OAAOP,UAAUJ,IAAI,KAAK,QACtBI,UAAUH,GAAG,CAACW,GAAG,CAACD,MAClB,CAACP,UAAUK,QAAQ,CAACG,GAAG,CAACD;AAC9B;AAEA,4CAA4C,GAC5C,OAAO,SAASE,iBACdT,SAAmC;IAEnC,OAAOD,cAAcC,eAAe;AACtC;AAEA;;;;;;;CAOC,GACD,OAAO,SAASU,eACdV,SAAmC,EACnCO,EAAY,EACZI,QAAiB;IAEjB,IAAIX,UAAUJ,IAAI,KAAK,OAAO;QAC5B,MAAMC,MAAM,IAAIC,IAAIE,UAAUH,GAAG;QACjC,IAAIc,UAAUd,IAAIe,GAAG,CAACL;aACjBV,IAAIgB,MAAM,CAACN;QAChB,OAAO;YAAEX,MAAM;YAAOC;QAAI;IAC5B;IAEA,MAAMQ,WAAW,IAAIP,IAAIE,UAAUK,QAAQ;IAC3C,IAAIM,UAAUN,SAASQ,MAAM,CAACN;SACzBF,SAASO,GAAG,CAACL;IAClB,OAAO,aAAKP;QAAWK;;AACzB;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASS,aACdd,SAAmC;IAEnC,OAAOA,UAAUJ,IAAI,KAAK,QAAQmB,MAAMC,IAAI,CAAChB,UAAUH,GAAG,IAAIoB;AAChE;AAyBA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASC,gBACdlB,SAAmC;IAEnC,OAAOA,UAAUJ,IAAI,KAAK,QACtB;QAAEA,MAAM;QAAOC,KAAKkB,MAAMC,IAAI,CAAChB,UAAUH,GAAG;IAAE,IAC9C,aAAKG;QAAWK,UAAUU,MAAMC,IAAI,CAAChB,UAAUK,QAAQ;;AAC7D;AAEA;;;;;;;CAOC,GACD,OAAO,SAASc,kBACdC,KAAc;IAEd,IAAI,OAAOA,UAAU,YAAYA,UAAU,MAAM,OAAOH;IACxD,MAAMI,YAAYD;IAElB,IAAIC,UAAUzB,IAAI,KAAK,OAAO;QAC5B,OAAOmB,MAAMO,OAAO,CAACD,UAAUxB,GAAG,IAC9B;YAAED,MAAM;YAAOC,KAAK,IAAIC,IAAIuB,UAAUxB,GAAG;QAAE,IAC3CoB;IACN;IAEA,IAAII,UAAUzB,IAAI,KAAK,YAAY;QACjC,MAAM2B,WAAWF;QAIjB,IAAI,OAAOE,SAASnB,KAAK,KAAK,UAAU,OAAOa;QAC/C,IAAI,CAACF,MAAMO,OAAO,CAACC,SAASlB,QAAQ,GAAG,OAAOY;QAC9C,OAAO;YACLrB,MAAM;YACN4B,WAAWD,SAASC,SAAS;YAC7BpB,OAAOmB,SAASnB,KAAK;YACrBC,UAAU,IAAIP,IAAIyB,SAASlB,QAAQ;QACrC;IACF;IAEA,OAAOY;AACT"}

package/dist/types/EntitySorting.d.ts

@@ -0,0 +1,7 @@
+import type { Entity } from './Entity.js';
+export type EntitySortType = 'asc' | 'desc';
+export type EntitySorting<TEntity extends Entity> = Record<number, {
+    property: keyof TEntity;
+    type: EntitySortType;
+}>;
+//# sourceMappingURL=EntitySorting.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EntitySorting.d.ts","sourceRoot":"","sources":["../../src/types/EntitySorting.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,CAAC;AAE5C,MAAM,MAAM,aAAa,CAAC,OAAO,SAAS,MAAM,IAAI,MAAM,CACxD,MAAM,EACN;IACE,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,IAAI,EAAE,cAAc,CAAC;CACtB,CACF,CAAC"}

package/dist/types/EntitySorting.js

@@ -0,0 +1,3 @@
+export { };
+
+//# sourceMappingURL=EntitySorting.js.map

package/dist/types/EntitySorting.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/EntitySorting.ts"],"sourcesContent":["import type { Entity } from './Entity.js';\n\nexport type EntitySortType = 'asc' | 'desc';\n\nexport type EntitySorting<TEntity extends Entity> = Record<\n  number,\n  {\n    property: keyof TEntity;\n    type: EntitySortType;\n  }\n>;\n"],"names":[],"mappings":"AAIA,WAME"}

package/dist/types/Json.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A value that survives `JSON.parse(JSON.stringify(x))` unchanged.
+ *
+ * It exists to make one rule checkable at compile time: **anything persisted as
+ * an autosaved draft is JSON round-trippable, period** — no class instances, no
+ * `EntityLink`, no `Date`. A draft is written through `createJSONStorage`, so a
+ * value that is not this is not "mostly preserved"; it comes back as something
+ * else (a `Date` as a string, an entity as a bare object, a `Map` as `{}`) and
+ * the loss is silent.
+ *
+ * Note the deliberate asymmetry with `UiPreferencesState`, the other persisted
+ * client store: that one writes through IndexedDB's **structured clone**, which
+ * does preserve a `Date` and a `Map`. The two contracts differ, so a type that
+ * describes one must not be reused for the other.
+ *
+ * `undefined` is absent on purpose — `JSON.stringify` drops an `undefined`
+ * member rather than round-tripping it, so a draft holding one restores with
+ * that key missing. Model "no value" as `null`, or leave the key out.
+ */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/** A JSON object — the shape a draft always takes at its top level. */
+export type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
+/**
+ * Whether a runtime value is {@link JsonValue}-shaped.
+ *
+ * The type above is the compile-time half; this is what a restore boundary needs,
+ * because a value read back out of storage arrives as `unknown` and no cast makes
+ * it true. Deliberately structural rather than a `JSON.stringify` round trip: a
+ * cycle throws there, and a `Date` survives it while being exactly what this must
+ * reject.
+ */
+export declare function isJsonValue(value: unknown): value is JsonValue;
+//# sourceMappingURL=Json.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Json.d.ts","sourceRoot":"","sources":["../../src/types/Json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,SAAS,EAAE,GACpB;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAE1C,uEAAuE;AACvE,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAE/D;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAc9D"}

package/dist/types/Json.js

@@ -0,0 +1,43 @@
+/**
+ * A value that survives `JSON.parse(JSON.stringify(x))` unchanged.
+ *
+ * It exists to make one rule checkable at compile time: **anything persisted as
+ * an autosaved draft is JSON round-trippable, period** — no class instances, no
+ * `EntityLink`, no `Date`. A draft is written through `createJSONStorage`, so a
+ * value that is not this is not "mostly preserved"; it comes back as something
+ * else (a `Date` as a string, an entity as a bare object, a `Map` as `{}`) and
+ * the loss is silent.
+ *
+ * Note the deliberate asymmetry with `UiPreferencesState`, the other persisted
+ * client store: that one writes through IndexedDB's **structured clone**, which
+ * does preserve a `Date` and a `Map`. The two contracts differ, so a type that
+ * describes one must not be reused for the other.
+ *
+ * `undefined` is absent on purpose — `JSON.stringify` drops an `undefined`
+ * member rather than round-tripping it, so a draft holding one restores with
+ * that key missing. Model "no value" as `null`, or leave the key out.
+ */ /**
+ * Whether a runtime value is {@link JsonValue}-shaped.
+ *
+ * The type above is the compile-time half; this is what a restore boundary needs,
+ * because a value read back out of storage arrives as `unknown` and no cast makes
+ * it true. Deliberately structural rather than a `JSON.stringify` round trip: a
+ * cycle throws there, and a `Date` survives it while being exactly what this must
+ * reject.
+ */ export function isJsonValue(value) {
+    if (value === null) return true;
+    const type = typeof value;
+    if (type === 'string' || type === 'number' || type === 'boolean') {
+        // `NaN` and `Infinity` serialize as `null`, so they do not round-trip.
+        return type !== 'number' || Number.isFinite(value);
+    }
+    if (Array.isArray(value)) return value.every(isJsonValue);
+    if (type !== 'object') return false;
+    // A plain object only. `Object.create(null)` is JSON-safe too and is what a
+    // `JSON.parse` reviver can produce, so both prototypes are accepted.
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) return false;
+    return Object.values(value).every(isJsonValue);
+}
+
+//# sourceMappingURL=Json.js.map

package/dist/types/Json.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/Json.ts"],"sourcesContent":["/**\n * A value that survives `JSON.parse(JSON.stringify(x))` unchanged.\n *\n * It exists to make one rule checkable at compile time: **anything persisted as\n * an autosaved draft is JSON round-trippable, period** — no class instances, no\n * `EntityLink`, no `Date`. A draft is written through `createJSONStorage`, so a\n * value that is not this is not \"mostly preserved\"; it comes back as something\n * else (a `Date` as a string, an entity as a bare object, a `Map` as `{}`) and\n * the loss is silent.\n *\n * Note the deliberate asymmetry with `UiPreferencesState`, the other persisted\n * client store: that one writes through IndexedDB's **structured clone**, which\n * does preserve a `Date` and a `Map`. The two contracts differ, so a type that\n * describes one must not be reused for the other.\n *\n * `undefined` is absent on purpose — `JSON.stringify` drops an `undefined`\n * member rather than round-tripping it, so a draft holding one restores with\n * that key missing. Model \"no value\" as `null`, or leave the key out.\n */\nexport type JsonValue =\n  | string\n  | number\n  | boolean\n  | null\n  | readonly JsonValue[]\n  | { readonly [key: string]: JsonValue };\n\n/** A JSON object — the shape a draft always takes at its top level. */\nexport type JsonObject = { readonly [key: string]: JsonValue };\n\n/**\n * Whether a runtime value is {@link JsonValue}-shaped.\n *\n * The type above is the compile-time half; this is what a restore boundary needs,\n * because a value read back out of storage arrives as `unknown` and no cast makes\n * it true. Deliberately structural rather than a `JSON.stringify` round trip: a\n * cycle throws there, and a `Date` survives it while being exactly what this must\n * reject.\n */\nexport function isJsonValue(value: unknown): value is JsonValue {\n  if (value === null) return true;\n  const type = typeof value;\n  if (type === 'string' || type === 'number' || type === 'boolean') {\n    // `NaN` and `Infinity` serialize as `null`, so they do not round-trip.\n    return type !== 'number' || Number.isFinite(value);\n  }\n  if (Array.isArray(value)) return value.every(isJsonValue);\n  if (type !== 'object') return false;\n  // A plain object only. `Object.create(null)` is JSON-safe too and is what a\n  // `JSON.parse` reviver can produce, so both prototypes are accepted.\n  const prototype = Object.getPrototypeOf(value);\n  if (prototype !== Object.prototype && prototype !== null) return false;\n  return Object.values(value as Record<string, unknown>).every(isJsonValue);\n}\n"],"names":["isJsonValue","value","type","Number","isFinite","Array","isArray","every","prototype","Object","getPrototypeOf","values"],"mappings":"AAAA;;;;;;;;;;;;;;;;;;CAkBC,GAYD;;;;;;;;CAQC,GACD,OAAO,SAASA,YAAYC,KAAc;IACxC,IAAIA,UAAU,MAAM,OAAO;IAC3B,MAAMC,OAAO,OAAOD;IACpB,IAAIC,SAAS,YAAYA,SAAS,YAAYA,SAAS,WAAW;QAChE,uEAAuE;QACvE,OAAOA,SAAS,YAAYC,OAAOC,QAAQ,CAACH;IAC9C;IACA,IAAII,MAAMC,OAAO,CAACL,QAAQ,OAAOA,MAAMM,KAAK,CAACP;IAC7C,IAAIE,SAAS,UAAU,OAAO;IAC9B,4EAA4E;IAC5E,qEAAqE;IACrE,MAAMM,YAAYC,OAAOC,cAAc,CAACT;IACxC,IAAIO,cAAcC,OAAOD,SAAS,IAAIA,cAAc,MAAM,OAAO;IACjE,OAAOC,OAAOE,MAAM,CAACV,OAAkCM,KAAK,CAACP;AAC/D"}

package/dist/types/StandardSchema.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The [Standard Schema](https://standardschema.dev) v1 contract, vendored.
+ *
+ * Standard Schema is an interface, not a library: Zod, Valibot and ArkType all
+ * expose `~standard` and nothing else is needed to run one. Declaring it here
+ * lets an entity carry a real schema without `@entifix/core` — the bottom of
+ * the stack — taking a runtime dependency on any validation library, and keeps
+ * whichever one a domain picks an implementation detail of that domain.
+ *
+ * Only the parts a caller needs to *run* a schema are vendored; the inference
+ * helpers from the published package are left out deliberately, since a draft
+ * arrives as strings and is validated, never parsed into a typed value here.
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': StandardSchemaV1Props<Input, Output>;
+}
+export interface StandardSchemaV1Props<Input = unknown, Output = Input> {
+    /** Contract version, for a consumer that has to branch on it. */
+    readonly version: 1;
+    /** The library that produced the schema (`zod`, `valibot`, …). */
+    readonly vendor: string;
+    /**
+     * Validates a value. Returns issues on failure and the parsed value on
+     * success — a Promise when the schema has async rules.
+     */
+    readonly validate: (value: unknown) => StandardSchemaV1Result<Output> | Promise<StandardSchemaV1Result<Output>>;
+    readonly types?: {
+        readonly input: Input;
+        readonly output: Output;
+    };
+}
+export type StandardSchemaV1Result<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: readonly StandardSchemaV1Issue[];
+};
+export interface StandardSchemaV1Issue {
+    readonly message: string;
+    /** Where the issue occurred; empty (or absent) means the value as a whole. */
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }>;
+}
+//# sourceMappingURL=StandardSchema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StandardSchema.d.ts","sourceRoot":"","sources":["../../src/types/StandardSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK;IAC/D,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,qBAAqB,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK;IACpE,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,CACjB,KAAK,EAAE,OAAO,KACX,sBAAsB,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACrE;AAED,MAAM,MAAM,sBAAsB,CAAC,MAAM,IACrC;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAA;CAAE,CAAC;AAE1D,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,WAAW,GAAG;QAAE,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC;CAC5E"}

package/dist/types/StandardSchema.js

@@ -0,0 +1,15 @@
+/**
+ * The [Standard Schema](https://standardschema.dev) v1 contract, vendored.
+ *
+ * Standard Schema is an interface, not a library: Zod, Valibot and ArkType all
+ * expose `~standard` and nothing else is needed to run one. Declaring it here
+ * lets an entity carry a real schema without `@entifix/core` — the bottom of
+ * the stack — taking a runtime dependency on any validation library, and keeps
+ * whichever one a domain picks an implementation detail of that domain.
+ *
+ * Only the parts a caller needs to *run* a schema are vendored; the inference
+ * helpers from the published package are left out deliberately, since a draft
+ * arrives as strings and is validated, never parsed into a typed value here.
+ */ export { };
+
+//# sourceMappingURL=StandardSchema.js.map

package/dist/types/StandardSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/StandardSchema.ts"],"sourcesContent":["/**\n * The [Standard Schema](https://standardschema.dev) v1 contract, vendored.\n *\n * Standard Schema is an interface, not a library: Zod, Valibot and ArkType all\n * expose `~standard` and nothing else is needed to run one. Declaring it here\n * lets an entity carry a real schema without `@entifix/core` — the bottom of\n * the stack — taking a runtime dependency on any validation library, and keeps\n * whichever one a domain picks an implementation detail of that domain.\n *\n * Only the parts a caller needs to *run* a schema are vendored; the inference\n * helpers from the published package are left out deliberately, since a draft\n * arrives as strings and is validated, never parsed into a typed value here.\n */\nexport interface StandardSchemaV1<Input = unknown, Output = Input> {\n  readonly '~standard': StandardSchemaV1Props<Input, Output>;\n}\n\nexport interface StandardSchemaV1Props<Input = unknown, Output = Input> {\n  /** Contract version, for a consumer that has to branch on it. */\n  readonly version: 1;\n  /** The library that produced the schema (`zod`, `valibot`, …). */\n  readonly vendor: string;\n  /**\n   * Validates a value. Returns issues on failure and the parsed value on\n   * success — a Promise when the schema has async rules.\n   */\n  readonly validate: (\n    value: unknown,\n  ) => StandardSchemaV1Result<Output> | Promise<StandardSchemaV1Result<Output>>;\n  readonly types?: { readonly input: Input; readonly output: Output };\n}\n\nexport type StandardSchemaV1Result<Output> =\n  | { readonly value: Output; readonly issues?: undefined }\n  | { readonly issues: readonly StandardSchemaV1Issue[] };\n\nexport interface StandardSchemaV1Issue {\n  readonly message: string;\n  /** Where the issue occurred; empty (or absent) means the value as a whole. */\n  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }>;\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;CAYC,GAwBD,WAIC"}

package/dist/types/UseCase.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A `@useCase()`-decorated class.
+ *
+ * It is never instantiated: the class exists because stage-3 decorators apply to
+ * classes, methods, fields and accessors only, so `@useCase() export function
+ * publishUC()` does not parse. The class is what makes annotation possible at
+ * all, and its behaviour lives in a static.
+ */
+export type UseCaseConstructor = new (...args: any[]) => unknown;
+//# sourceMappingURL=UseCase.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UseCase.d.ts","sourceRoot":"","sources":["../../src/types/UseCase.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,KAG/B,GAAG,IAAI,EAAE,GAAG,EAAE,KACX,OAAO,CAAC"}

package/dist/types/UseCase.js

@@ -0,0 +1,10 @@
+/**
+ * A `@useCase()`-decorated class.
+ *
+ * It is never instantiated: the class exists because stage-3 decorators apply to
+ * classes, methods, fields and accessors only, so `@useCase() export function
+ * publishUC()` does not parse. The class is what makes annotation possible at
+ * all, and its behaviour lives in a static.
+ */ export { };
+
+//# sourceMappingURL=UseCase.js.map

package/dist/types/UseCase.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/UseCase.ts"],"sourcesContent":["/**\n * A `@useCase()`-decorated class.\n *\n * It is never instantiated: the class exists because stage-3 decorators apply to\n * classes, methods, fields and accessors only, so `@useCase() export function\n * publishUC()` does not parse. The class is what makes annotation possible at\n * all, and its behaviour lives in a static.\n */\nexport type UseCaseConstructor = new (\n  // Same reason as `EntityConstructor`: the parameters are the author's business.\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  ...args: any[]\n) => unknown;\n"],"names":[],"mappings":"AAAA;;;;;;;CAOC,GACD,WAIa"}

package/dist/wizard/index.d.ts

@@ -0,0 +1,4 @@
+export * from './wizard-definition.js';
+export * from './wizard-navigation.js';
+export * from './wizard-state.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/wizard/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC"}

package/dist/wizard/index.js

@@ -0,0 +1,5 @@
+export * from './wizard-definition.js';
+export * from './wizard-navigation.js';
+export * from './wizard-state.js';
+
+//# sourceMappingURL=index.js.map

package/dist/wizard/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/wizard/index.ts"],"sourcesContent":["export * from './wizard-definition.js';\nexport * from './wizard-navigation.js';\nexport * from './wizard-state.js';\n"],"names":[],"mappings":"AAAA,cAAc,yBAAyB;AACvC,cAAc,yBAAyB;AACvC,cAAc,oBAAoB"}

package/dist/wizard/wizard-definition.d.ts

@@ -0,0 +1,108 @@
+/**
+ * What a step holds, which decides how its value is stored and edited.
+ *
+ * `form` is one `useEntityForm` instance over part of an entity; `selection` is
+ * a table step whose value is a set of ids; `choice` is a branch point offering
+ * a fixed list of options; `summary` is the read-only recap; `custom` is
+ * anything else the host renders and reads itself.
+ */
+export declare const WizardStepKinds: readonly ["form", "selection", "choice", "summary", "custom"];
+export type WizardStepKind = (typeof WizardStepKinds)[number];
+/**
+ * One step, and the edges out of it.
+ *
+ * **The graph is data; `next` only chooses along it.** `to` lists the steps this
+ * one may lead to, so reachability, unknown targets, cycles and terminality are
+ * decidable by reading the definition — no probing, no enumeration of the state
+ * space, and no rule that "only appears to hold" because a `next` reading a form
+ * value could never be enumerated. It is the move
+ * [ADR 0039](../../../../../../docs/adr/0039-multi-step-sagas-are-orchestrated.md)
+ * made for saga steps, for the same reason: a walkable definition is checkable
+ * at load, and a function is not.
+ *
+ * A step with an empty `to` is **terminal**, and
+ * {@link assertWizardDefinition} requires that to be the summary.
+ */
+export interface WizardStep {
+    readonly id: string;
+    readonly kind: WizardStepKind;
+    /** Catalog key for the stepper's label. Resolved by the renderer, never here. */
+    readonly labelKey: string;
+    /**
+     * The options a `choice` step offers, as stable identifiers.
+     *
+     * Required on `choice` and forbidden elsewhere: the value of a choice step is
+     * one of these strings, so a choice with no options can never be answered and
+     * options on a form step describe nothing.
+     */
+    readonly options?: readonly string[];
+    /** Every step this one may lead to. Empty means the flow ends here. */
+    readonly to: readonly string[];
+    /**
+     * Which of {@link WizardStep.to} comes next, given everything answered so far.
+     *
+     * Optional, and omitting it is the ordinary case: a step with exactly one edge
+     * needs no function to pick it. A step with several **must** declare one, or
+     * the definition cannot say where it goes.
+     *
+     * It returns a step id and never `undefined`: **the end of the flow is an
+     * empty `to`, not a `next` that declines**. Two ways of saying the same thing
+     * would let a step be terminal in one of them and not the other, and it is
+     * `to` that {@link assertWizardDefinition} can read.
+     */
+    next?(state: WizardStateLike): string;
+}
+/**
+ * The part of the state a `next` may read.
+ *
+ * Declared structurally rather than importing `WizardState`, so the definition
+ * module stays below the state module and neither has to import the other.
+ */
+export interface WizardStateLike {
+    readonly activeStep: string;
+    readonly steps: {
+        readonly [stepId: string]: unknown;
+    };
+}
+/**
+ * A whole wizard: its key — which is also its screen key in a workspace address
+ * — and its steps, the first of which is where the flow begins.
+ */
+export interface WizardDefinition {
+    readonly key: string;
+    readonly steps: readonly WizardStep[];
+}
+/** The step a flow starts at: the first declared. */
+export declare const entryStep: (definition: WizardDefinition) => WizardStep;
+/** The step with this id, or `undefined` when the definition has none. */
+export declare const findStep: (definition: WizardDefinition, stepId: string) => WizardStep | undefined;
+/**
+ * Checks a definition the moment it is declared, and throws rather than
+ * degrading.
+ *
+ * **Load time, not step time.** A wizard whose last step is missing, or whose
+ * branch names a step that does not exist, must fail on the first render of any
+ * surface rather than on the render of the step nobody reached — otherwise the
+ * failure of the longest flow in the product arrives at the end of it. That is
+ * the posture `assertLinkSourcesAreEditable` and `surfaceFor` already take
+ * ([ADR 0035](../../../../../../docs/adr/0035-entity-actions-selection-and-bulk.md)).
+ *
+ * Six faults, each of which is silent otherwise:
+ *
+ * - **no steps**, which renders an empty frame with a disabled button;
+ * - **a duplicate id**, which makes one step's stored value overwrite another's;
+ * - **an unknown `to` target**, a typo that strands the flow mid-way;
+ * - **several edges and no `next`**, which cannot say where the step goes;
+ * - **a step nothing reaches**, which is either a dead branch or a missing edge;
+ * - **the wrong terminal step** — the flow must end in the summary, and there
+ *   must be exactly one of those. A wizard ending anywhere else commits without
+ *   the operator ever seeing what they answered, which
+ *   [#111](https://github.com/r10c-technologies/r10c/issues/111) records as not
+ *   optional.
+ *
+ * A cycle needs no separate check: every step is reachable from the entry and
+ * exactly one is terminal, so a cycle would leave the steps on it unable to
+ * reach that terminal, which the walk below reports as unreachable-from-here.
+ */
+export declare function assertWizardDefinition(definition: WizardDefinition): void;
+//# sourceMappingURL=wizard-definition.d.ts.map

package/dist/wizard/wizard-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wizard-definition.d.ts","sourceRoot":"","sources":["../../src/wizard/wizard-definition.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,+DAMlB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,uEAAuE;IACvE,QAAQ,CAAC,EAAE,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;CACxD;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;CACvC;AAED,qDAAqD;AACrD,eAAO,MAAM,SAAS,GAAI,YAAY,gBAAgB,KAAG,UAMxD,CAAC;AAEF,0EAA0E;AAC1E,eAAO,MAAM,QAAQ,GACnB,YAAY,gBAAgB,EAC5B,QAAQ,MAAM,KACb,UAAU,GAAG,SAA8D,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAiCzE"}