@owlmeans/planning 0.1.18-rc.8 → 0.1.18

package/build/helpers/changes.d.ts

@@ -1,51 +1,20 @@
-import type { AnyTypeSchema, PlanningSchemaRegistry, SpecificationSlot, TransitionExecution, Workcard, WorkcardChanges } from '../types.js';
-type FlowLookup = Pick<PlanningSchemaRegistry, 'flow'>;
-export interface ChangeSet {
-    changes: WorkcardChanges;
-    unset: string[];
-    /** Transit only: the flow that moved, and the move. */
-    flow?: string;
-    from?: string;
-    to?: string;
-}
-/** Structural equality over JSON values. */
+import type { AnyTypeSchema, SpecificationSlot, TransitionExecution, Workcard } from '../types.js';
+import type { ChangeSet, ChangesHelper } from './changes/types.js';
+import type { FlowLookup } from './types.local.js';
+export declare const createChangesHelper: () => ChangesHelper;
+export declare const changesHelper: ChangesHelper;
+/** @deprecated compat:factory-refactor — use `changesHelper.sameValue(…)` */
 export declare const sameValue: (left: unknown, right: unknown) => boolean;
-/** A shallow merge that drops keys patched to `null`. */
+/** @deprecated compat:factory-refactor — use `changesHelper.mergeFields(…)` */
 export declare const mergeFields: (base?: Record<string, unknown> | null, patch?: Record<string, unknown> | null) => Record<string, unknown>;
-/** A copy of the record with the paths (`key`, `fields.key`, `flows.id`) removed. */
+/** @deprecated compat:factory-refactor — use `changesHelper.applyUnset(…)` */
 export declare const applyUnset: <T extends object>(record: T, unset?: string[]) => T;
-/**
- * Refuse an execution that writes what only the transition, the flow or the executor may write.
- *
- * `status`/`intrinsic`/`flows`/`closedAt` move only through `transit` (a create's draft may name
- * the initial status); `code` is fixed once minted unless the type's policy says `mutable`;
- * `category` is fixed; `revision`/`bodyChars` are computed.
- *
- * @throws {PlanningError} `planning:immutable:<field>`
- */
+/** @deprecated compat:factory-refactor — use `changesHelper.assertMutable(…)` */
 export declare const assertMutable: (exec: TransitionExecution, type: AnyTypeSchema) => void;
-/**
- * The `changes`/`unset` a transition records (plan step 9).
- *
- * - `create`: the whole initial record from the draft (overlaid by `exec.changes`) — `parents`
- *   normalized, every flow at its initial status (the draft's `status` for the primary one),
- *   `status`/`intrinsic` mirrored, `closedAt` when it starts closed; a specification gets its
- *   format, `bodyChars` and revision 1 when the slot is revisioned.
- * - `update`: only what differs; `null` or `exec.unset` clears a field that has a value; a moved
- *   `parent` replaces the old one in `parents`; a revisioned document whose content changed gets
- *   `revision + 1`. An update that changes nothing is empty ({@link isEmptyChange}).
- * - `transit`: `flows[flow] = rule.to`, `status` when the flow is primary, `intrinsic` when it
- *   moves, `closedAt` set on entering closed and cleared on leaving it — plus the caller's own
- *   changes, diffed as in an update.
- * - `link`, `unlink`, `delete`: nothing.
- *
- * @throws {IllegalTransition} a transit the flow does not offer from the current status
- * @throws {PlanningError} `malformed:*` for an execution missing what its action needs
- */
+/** @deprecated compat:factory-refactor — use `changesHelper.computeChanges(…)` */
 export declare const computeChanges: (card: Workcard | null | undefined, exec: TransitionExecution, type: AnyTypeSchema, registry: FlowLookup, at: string, opts?: {
     slot?: SpecificationSlot | null;
 }) => ChangeSet;
-/** Nothing to write: no changed value and nothing to clear. */
+/** @deprecated compat:factory-refactor — use `changesHelper.isEmptyChange(…)` */
 export declare const isEmptyChange: (set: Pick<ChangeSet, 'changes' | 'unset'>) => boolean;
-export {};
 //# sourceMappingURL=changes.d.ts.map

package/build/helpers/changes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"changes.d.ts","sourceRoot":"","sources":["../../src/helpers/changes.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EAAE,sBAAsB,EAAiB,iBAAiB,EAAE,mBAAmB,EAC5F,QAAQ,EAAE,eAAe,EAC1B,MAAM,aAAa,CAAA;AAKpB,KAAK,UAAU,GAAG,IAAI,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAA;AAEtD,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,eAAe,CAAA;IACxB,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,EAAE,CAAC,EAAE,MAAM,CAAA;CACZ;AAgBD,4CAA4C;AAC5C,eAAO,MAAM,SAAS,SAAU,OAAO,SAAS,OAAO,KAAG,OAczD,CAAA;AAKD,yDAAyD;AACzD,eAAO,MAAM,WAAW,UACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,UAAU,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,KAC5E,MAAM,CAAC,MAAM,EAAE,OAAO,CACuC,CAAA;AAEhE,qFAAqF;AACrF,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,UAAU,CAAC,UAAU,MAAM,EAAE,KAAG,CAe1E,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,SAAU,mBAAmB,QAAQ,aAAa,KAAG,IA0B9E,CAAA;AAsID;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,SACnB,QAAQ,GAAG,IAAI,GAAG,SAAS,QAC3B,mBAAmB,QACnB,aAAa,YACT,UAAU,MAChB,MAAM,SACH;IAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAA;CAAE,KACzC,SAsDF,CAAA;AAED,+DAA+D;AAC/D,eAAO,MAAM,aAAa,QAAS,IAAI,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,KAAG,OAEW,CAAA"}
+{"version":3,"file":"changes.d.ts","sourceRoot":"","sources":["../../src/helpers/changes.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAiB,iBAAiB,EAAE,mBAAmB,EAAE,QAAQ,EAAkC,MAAM,aAAa,CAAA;AAEjJ,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAIlE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAQlD,eAAO,MAAM,mBAAmB,QAAO,aAqRtC,CAAA;AAED,eAAO,MAAM,aAAa,eAAwB,CAAA;AAElD,6EAA6E;AAC7E,eAAO,MAAM,SAAS,SAAU,OAAO,SAAS,OAAO,KAAG,OAA+C,CAAA;AAEzG,+EAA+E;AAC/E,eAAO,MAAM,WAAW,UACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,UAAU,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,KAC5E,MAAM,CAAC,MAAM,EAAE,OAAO,CAA2C,CAAA;AAEpE,8EAA8E;AAC9E,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,UAAU,CAAC,UAAU,MAAM,EAAE,KAAG,CAA+C,CAAA;AAE1H,iFAAiF;AACjF,eAAO,MAAM,aAAa,SAAU,mBAAmB,QAAQ,aAAa,KAAG,IAA+C,CAAA;AAE9H,kFAAkF;AAClF,eAAO,MAAM,cAAc,SACnB,QAAQ,GAAG,IAAI,GAAG,SAAS,QAC3B,mBAAmB,QACnB,aAAa,YACT,UAAU,MAChB,MAAM,SACH;IAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAA;CAAE,KACzC,SAA+E,CAAA;AAElF,iFAAiF;AACjF,eAAO,MAAM,aAAa,QAAS,IAAI,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,KAAG,OAA2C,CAAA"}

package/build/helpers/changes.js

@@ -1,277 +1,263 @@
 import { IntrinsicStatus, SpecificationFormat, TransitionAction, WorkcardKind } from '../consts.js';
 import { IllegalTransition, PlanningError } from '../errors.js';
-import { normalizeParents } from './card.js';
-import { bodyCharsOf, nextRevision } from './specification.js';
-import { initialFlowsOf, initialStatusOf, primaryFlowOf, resolveIntrinsic, ruleOf } from './status.js';
-/** Never in a caller's changes: the transition itself carries them. */
-const IDENTITY_KEYS = ['id', 'kind', 'type', 'entityId', 'seq', 'head', 'createdAt'];
-/** Move only through `transit` (or a create's draft). */
-const FLOW_KEYS = ['status', 'intrinsic', 'flows', 'closedAt'];
-/** Computed by the executor, never supplied. */
-const DERIVED_KEYS = ['revision', 'bodyChars'];
-/** Cannot be cleared. */
-const REQUIRED_KEYS = ['title', 'parents', 'labels', 'fields', 'category', 'format'];
-/** Changing one of these produces a new revision of a revisioned document. */
-const CONTENT_KEYS = ['body', 'ref', 'format', 'version'];
+import { cardHelper } from './card.js';
+import { CONTENT_KEYS, DERIVED_KEYS, FLOW_KEYS, IDENTITY_KEYS, PROVENANCE_KEYS, REQUIRED_KEYS } from './changes/consts.local.js';
+import { specificationHelper } from './specification.js';
+import { statusHelper } from './status.js';
 const isPlainObject = (value) => value != null && typeof value === 'object' && !Array.isArray(value);
-/** Structural equality over JSON values. */
-export const sameValue = (left, right) => {
-    if (left === right) {
-        return true;
-    }
-    if (Array.isArray(left) && Array.isArray(right)) {
-        return left.length === right.length && left.every((entry, index) => sameValue(entry, right[index]));
-    }
-    if (isPlainObject(left) && isPlainObject(right)) {
-        const keys = Object.keys(left).filter(key => left[key] !== undefined);
-        const other = Object.keys(right).filter(key => right[key] !== undefined);
-        return keys.length === other.length && keys.every(key => sameValue(left[key], right[key]));
-    }
-    return false;
-};
 const clean = (record) => Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined));
-/** A shallow merge that drops keys patched to `null`. */
-export const mergeFields = (base, patch) => Object.fromEntries(Object.entries({ ...(base ?? {}), ...(patch ?? {}) })
-    .filter(([, value]) => value !== null && value !== undefined));
-/** A copy of the record with the paths (`key`, `fields.key`, `flows.id`) removed. */
-export const applyUnset = (record, unset) => {
-    const copy = structuredClone(record);
-    for (const path of unset ?? []) {
-        const [head, ...rest] = path.split('.');
-        if (rest.length > 0) {
-            const map = copy[head];
-            if (isPlainObject(map)) {
-                delete map[rest.join('.')];
-            }
+export const createChangesHelper = () => {
+    const sameValue = (left, right) => {
+        if (left === right) {
+            return true;
         }
-        else {
-            delete copy[head];
+        if (Array.isArray(left) && Array.isArray(right)) {
+            return left.length === right.length && left.every((entry, index) => sameValue(entry, right[index]));
         }
-    }
-    return copy;
-};
-/**
- * Refuse an execution that writes what only the transition, the flow or the executor may write.
- *
- * `status`/`intrinsic`/`flows`/`closedAt` move only through `transit` (a create's draft may name
- * the initial status); `code` is fixed once minted unless the type's policy says `mutable`;
- * `category` is fixed; `revision`/`bodyChars` are computed.
- *
- * @throws {PlanningError} `planning:immutable:<field>`
- */
-export const assertMutable = (exec, type) => {
-    const create = exec.action === TransitionAction.Create;
-    const codeFixed = type.code != null && type.code.mutable !== true;
-    const refuse = (key) => {
-        throw new PlanningError(`immutable:${FLOW_KEYS.includes(key) ? 'status' : key}`);
-    };
-    for (const [key, value] of Object.entries(exec.changes ?? {})) {
-        if (value === undefined) {
-            continue;
+        if (isPlainObject(left) && isPlainObject(right)) {
+            const keys = Object.keys(left).filter(key => left[key] !== undefined);
+            const other = Object.keys(right).filter(key => right[key] !== undefined);
+            return keys.length === other.length && keys.every(key => sameValue(left[key], right[key]));
         }
-        if (IDENTITY_KEYS.includes(key) || DERIVED_KEYS.includes(key)) {
-            refuse(key);
-        }
-        if (!create && (FLOW_KEYS.includes(key) || key === 'category' || (key === 'code' && codeFixed))) {
-            refuse(key);
+        return false;
+    };
+    const mergeFields = (base, patch) => Object.fromEntries(Object.entries({ ...(base ?? {}), ...(patch ?? {}) })
+        .filter(([, value]) => value !== null && value !== undefined));
+    const applyUnset = (record, unset) => {
+        const copy = structuredClone(record);
+        for (const path of unset ?? []) {
+            const [head, ...rest] = path.split('.');
+            if (rest.length > 0) {
+                const map = copy[head];
+                if (isPlainObject(map)) {
+                    delete map[rest.join('.')];
+                }
+            }
+            else {
+                delete copy[head];
+            }
         }
-    }
-    for (const path of exec.unset ?? []) {
-        const head = path.split('.')[0];
-        if (IDENTITY_KEYS.includes(path) || DERIVED_KEYS.includes(path) || REQUIRED_KEYS.includes(path)
-            || FLOW_KEYS.includes(head) || (path === 'code' && codeFixed)) {
-            refuse(path);
+        return copy;
+    };
+    const assertMutable = (exec, type) => {
+        const create = exec.action === TransitionAction.Create;
+        const codeFixed = type.code != null && type.code.mutable !== true;
+        const refuse = (key) => {
+            throw new PlanningError(`immutable:${FLOW_KEYS.includes(key) ? 'status' : key}`);
+        };
+        for (const [key, value] of Object.entries(exec.changes ?? {})) {
+            if (value === undefined) {
+                continue;
+            }
+            if (IDENTITY_KEYS.includes(key) || PROVENANCE_KEYS.includes(key) || DERIVED_KEYS.includes(key)) {
+                refuse(key);
+            }
+            if (!create && (FLOW_KEYS.includes(key) || key === 'category' || (key === 'code' && codeFixed))) {
+                refuse(key);
+            }
         }
-    }
-};
-const reach = (record, path) => path.split('.')
-    .reduce((value, step) => isPlainObject(value) ? value[step] : undefined, record);
-/** Only what differs from the card; `null` becomes an unset of a field that has a value. */
-const diffInto = (card, changes, skip, set) => {
-    const out = set.changes;
-    const current = card;
-    for (const [key, value] of Object.entries(changes ?? {})) {
-        if (value === undefined || IDENTITY_KEYS.includes(key) || skip.includes(key)) {
-            continue;
+        for (const path of exec.unset ?? []) {
+            const head = path.split('.')[0];
+            if (PROVENANCE_KEYS.includes(head)) {
+                refuse(head);
+            }
+            if (IDENTITY_KEYS.includes(path) || DERIVED_KEYS.includes(path) || REQUIRED_KEYS.includes(path)
+                || FLOW_KEYS.includes(head) || (path === 'code' && codeFixed)) {
+                refuse(path);
+            }
         }
-        if (key === 'fields' || key === 'flows') {
-            const own = (current[key] ?? {});
-            const patch = {};
-            for (const [entry, entryValue] of Object.entries(value ?? {})) {
-                if (entryValue === undefined) {
-                    continue;
-                }
-                if (entryValue === null) {
-                    if (own[entry] !== undefined) {
-                        set.unset.push(`${key}.${entry}`);
+    };
+    const reach = (record, path) => path.split('.')
+        .reduce((value, step) => isPlainObject(value) ? value[step] : undefined, record);
+    /** Only what differs from the card; `null` becomes an unset of a field that has a value. */
+    const diffInto = (card, changes, skip, set) => {
+        const out = set.changes;
+        const current = card;
+        for (const [key, value] of Object.entries(changes ?? {})) {
+            if (value === undefined || IDENTITY_KEYS.includes(key) || PROVENANCE_KEYS.includes(key) || skip.includes(key)) {
+                continue;
+            }
+            if (key === 'fields' || key === 'flows') {
+                const own = (current[key] ?? {});
+                const patch = {};
+                for (const [entry, entryValue] of Object.entries(value ?? {})) {
+                    if (entryValue === undefined) {
+                        continue;
                     }
+                    if (entryValue === null) {
+                        if (own[entry] !== undefined) {
+                            set.unset.push(`${key}.${entry}`);
+                        }
+                    }
+                    else if (!sameValue(own[entry], entryValue)) {
+                        patch[entry] = entryValue;
+                    }
+                }
+                if (Object.keys(patch).length > 0) {
+                    out[key] = patch;
                 }
-                else if (!sameValue(own[entry], entryValue)) {
-                    patch[entry] = entryValue;
+                continue;
+            }
+            if (value === null) {
+                if (current[key] != null) {
+                    set.unset.push(key);
                 }
+                continue;
             }
-            if (Object.keys(patch).length > 0) {
-                out[key] = patch;
+            if (!sameValue(current[key], value)) {
+                out[key] = value;
             }
-            continue;
         }
-        if (value === null) {
-            if (current[key] != null) {
-                set.unset.push(key);
+    };
+    const unsetInto = (card, unset, set) => {
+        for (const path of unset ?? []) {
+            if (PROVENANCE_KEYS.includes(path.split('.')[0])) {
+                continue;
+            }
+            if (reach(card, path) !== undefined && !set.unset.includes(path)) {
+                set.unset.push(path);
             }
-            continue;
         }
-        if (!sameValue(current[key], value)) {
-            out[key] = value;
+    };
+    /** A moved primary parent replaces the old one in `parents`. */
+    const reparent = (card, set) => {
+        const out = set.changes;
+        const moved = out.parent !== undefined || set.unset.includes('parent');
+        if (!moved || out.parents !== undefined) {
+            return;
         }
-    }
-};
-const unsetInto = (card, unset, set) => {
-    for (const path of unset ?? []) {
-        if (reach(card, path) !== undefined && !set.unset.includes(path)) {
-            set.unset.push(path);
+        const parents = cardHelper.normalizeParents(out.parent, card.parents.filter(parent => parent !== card.parent));
+        if (!sameValue(parents, card.parents)) {
+            out.parents = parents;
         }
-    }
-};
-/** A moved primary parent replaces the old one in `parents`. */
-const reparent = (card, set) => {
-    const out = set.changes;
-    const moved = out.parent !== undefined || set.unset.includes('parent');
-    if (!moved || out.parents !== undefined) {
-        return;
-    }
-    const parents = normalizeParents(out.parent, card.parents.filter(parent => parent !== card.parent));
-    if (!sameValue(parents, card.parents)) {
-        out.parents = parents;
-    }
-};
-const reviseInto = (card, slot, set) => {
-    if (card.kind !== WorkcardKind.Specification) {
-        return;
-    }
-    const out = set.changes;
-    if (out.body !== undefined) {
-        out.bodyChars = bodyCharsOf(out.body);
-    }
-    else if (set.unset.includes('body') && !set.unset.includes('bodyChars')) {
-        set.unset.push('bodyChars');
-    }
-    const revised = CONTENT_KEYS.some(key => out[key] !== undefined || set.unset.includes(key));
-    if (revised) {
-        const revision = nextRevision(card, slot);
-        if (revision != null) {
-            out.revision = revision;
+    };
+    const reviseInto = (card, slot, set) => {
+        if (card.kind !== WorkcardKind.Specification) {
+            return;
+        }
+        const out = set.changes;
+        if (out.body !== undefined) {
+            out.bodyChars = specificationHelper.bodyCharsOf(out.body);
+        }
+        else if (set.unset.includes('body') && !set.unset.includes('bodyChars')) {
+            set.unset.push('bodyChars');
+        }
+        const revised = CONTENT_KEYS.some(key => out[key] !== undefined || set.unset.includes(key));
+        if (revised) {
+            const revision = specificationHelper.nextRevision(card, slot);
+            if (revision != null) {
+                out.revision = revision;
+            }
         }
-    }
-};
-const createOf = (exec, type, registry, at, slot) => {
-    if (typeof exec.card === 'string') {
-        throw new PlanningError('malformed:create-without-draft');
-    }
-    const draft = exec.card;
-    const overlay = Object.fromEntries(Object.entries(exec.changes ?? {})
-        .filter(([key]) => !FLOW_KEYS.includes(key) && !IDENTITY_KEYS.includes(key) && !DERIVED_KEYS.includes(key)));
-    const parent = overlay.parent ?? draft.parent;
-    const flows = initialFlowsOf(type, registry, draft.status ?? exec.changes?.status);
-    const intrinsic = resolveIntrinsic(type, flows, registry);
-    const record = {
-        title: draft.title,
-        description: draft.description,
-        code: draft.code,
-        order: draft.order,
-        createdBy: draft.createdBy,
-        ...overlay,
-        labels: [...new Set(overlay.labels ?? draft.labels ?? [])],
-        parent,
-        parents: normalizeParents(parent, overlay.parents ?? draft.parents),
-        fields: mergeFields(draft.fields, overlay.fields),
-        flows,
-        status: flows[primaryFlowOf(type)],
-        intrinsic,
-        closedAt: intrinsic === IntrinsicStatus.Closed ? at : undefined,
     };
-    if (draft.kind === WorkcardKind.Specification) {
-        const body = overlay.body ?? draft.body;
-        Object.assign(record, {
-            category: overlay.category ?? draft.category ?? slot?.category,
-            format: overlay.format ?? draft.format ?? slot?.format ?? SpecificationFormat.Markdown,
-            body,
-            ref: overlay.ref ?? draft.ref,
-            version: overlay.version ?? draft.version ?? slot?.version,
-            bodyChars: bodyCharsOf(body),
-            revision: nextRevision(null, slot),
-        });
-    }
-    return { changes: clean(record), unset: [] };
-};
-/**
- * The `changes`/`unset` a transition records (plan step 9).
- *
- * - `create`: the whole initial record from the draft (overlaid by `exec.changes`) — `parents`
- *   normalized, every flow at its initial status (the draft's `status` for the primary one),
- *   `status`/`intrinsic` mirrored, `closedAt` when it starts closed; a specification gets its
- *   format, `bodyChars` and revision 1 when the slot is revisioned.
- * - `update`: only what differs; `null` or `exec.unset` clears a field that has a value; a moved
- *   `parent` replaces the old one in `parents`; a revisioned document whose content changed gets
- *   `revision + 1`. An update that changes nothing is empty ({@link isEmptyChange}).
- * - `transit`: `flows[flow] = rule.to`, `status` when the flow is primary, `intrinsic` when it
- *   moves, `closedAt` set on entering closed and cleared on leaving it — plus the caller's own
- *   changes, diffed as in an update.
- * - `link`, `unlink`, `delete`: nothing.
- *
- * @throws {IllegalTransition} a transit the flow does not offer from the current status
- * @throws {PlanningError} `malformed:*` for an execution missing what its action needs
- */
-export const computeChanges = (card, exec, type, registry, at, opts) => {
-    if (exec.action === TransitionAction.Create) {
-        return createOf(exec, type, registry, at, opts?.slot);
-    }
-    const set = { changes: {}, unset: [] };
-    if (exec.action !== TransitionAction.Update && exec.action !== TransitionAction.Transit) {
-        return set;
-    }
-    if (card == null) {
-        throw new PlanningError(`malformed:${exec.action}-without-card`);
-    }
-    if (exec.action === TransitionAction.Update) {
-        diffInto(card, exec.changes, [], set);
-        unsetInto(card, exec.unset, set);
+    const createOf = (exec, type, registry, at, slot) => {
+        if (typeof exec.card === 'string') {
+            throw new PlanningError('malformed:create-without-draft');
+        }
+        const draft = exec.card;
+        const overlay = Object.fromEntries(Object.entries(exec.changes ?? {})
+            .filter(([key]) => !FLOW_KEYS.includes(key) && !IDENTITY_KEYS.includes(key) && !PROVENANCE_KEYS.includes(key)
+            && !DERIVED_KEYS.includes(key)));
+        const parent = overlay.parent ?? draft.parent;
+        const flows = statusHelper.initialFlowsOf(type, registry, draft.status ?? exec.changes?.status);
+        const intrinsic = statusHelper.resolveIntrinsic(type, flows, registry);
+        const record = {
+            title: draft.title,
+            description: draft.description,
+            code: draft.code,
+            order: draft.order,
+            createdBy: draft.createdBy,
+            reporter: draft.reporter,
+            assignee: draft.assignee,
+            mode: draft.mode ?? (draft.kind === WorkcardKind.Project ? 'opened' : undefined),
+            ...overlay,
+            labels: [...new Set(overlay.labels ?? draft.labels ?? [])],
+            parent,
+            parents: cardHelper.normalizeParents(parent, overlay.parents ?? draft.parents),
+            fields: mergeFields(draft.fields, overlay.fields),
+            flows,
+            status: flows[statusHelper.primaryFlowOf(type)],
+            intrinsic,
+            closedAt: intrinsic === IntrinsicStatus.Closed ? at : undefined,
+        };
+        if (draft.kind === WorkcardKind.Specification) {
+            const body = overlay.body ?? draft.body;
+            Object.assign(record, {
+                category: overlay.category ?? draft.category ?? slot?.category,
+                format: overlay.format ?? draft.format ?? slot?.format ?? SpecificationFormat.Markdown,
+                body,
+                ref: overlay.ref ?? draft.ref,
+                version: overlay.version ?? draft.version ?? slot?.version,
+                bodyChars: specificationHelper.bodyCharsOf(body),
+                revision: specificationHelper.nextRevision(null, slot),
+            });
+        }
+        return { changes: clean(record), unset: [] };
+    };
+    const computeChanges = (card, exec, type, registry, at, opts) => {
+        if (exec.action === TransitionAction.Create) {
+            return createOf(exec, type, registry, at, opts?.slot);
+        }
+        const set = { changes: {}, unset: [] };
+        if (exec.action !== TransitionAction.Update && exec.action !== TransitionAction.Transit) {
+            return set;
+        }
+        if (card == null) {
+            throw new PlanningError(`malformed:${exec.action}-without-card`);
+        }
+        if (exec.action === TransitionAction.Update) {
+            diffInto(card, exec.changes, [], set);
+            unsetInto(card, exec.unset, set);
+            reparent(card, set);
+            reviseInto(card, opts?.slot, set);
+            return set;
+        }
+        if (exec.transition == null) {
+            throw new PlanningError('malformed:transit-without-transition');
+        }
+        const primary = statusHelper.primaryFlowOf(type);
+        const flowId = exec.flow ?? primary;
+        const flow = registry.flow(flowId);
+        const from = card.flows[flowId] ?? (flowId === primary ? card.status : statusHelper.initialStatusOf(flow));
+        const rule = statusHelper.ruleOf(flow, exec.transition, from);
+        if (rule == null) {
+            throw new IllegalTransition(`${flowId}:${exec.transition}:${from}`);
+        }
+        diffInto(card, exec.changes, FLOW_KEYS, set);
+        unsetInto(card, exec.unset?.filter(path => !FLOW_KEYS.includes(path.split('.')[0])), set);
         reparent(card, set);
         reviseInto(card, opts?.slot, set);
-        return set;
-    }
-    if (exec.transition == null) {
-        throw new PlanningError('malformed:transit-without-transition');
-    }
-    const primary = primaryFlowOf(type);
-    const flowId = exec.flow ?? primary;
-    const flow = registry.flow(flowId);
-    const from = card.flows[flowId] ?? (flowId === primary ? card.status : initialStatusOf(flow));
-    const rule = ruleOf(flow, exec.transition, from);
-    if (rule == null) {
-        throw new IllegalTransition(`${flowId}:${exec.transition}:${from}`);
-    }
-    diffInto(card, exec.changes, FLOW_KEYS, set);
-    unsetInto(card, exec.unset?.filter(path => !FLOW_KEYS.includes(path.split('.')[0])), set);
-    reparent(card, set);
-    reviseInto(card, opts?.slot, set);
-    const flows = { ...card.flows, [flowId]: rule.to };
-    set.changes.flows = { [flowId]: rule.to };
-    if (flowId === primary) {
-        set.changes.status = rule.to;
-    }
-    const intrinsic = resolveIntrinsic(type, flows, registry);
-    if (intrinsic !== card.intrinsic) {
-        set.changes.intrinsic = intrinsic;
-    }
-    if (intrinsic === IntrinsicStatus.Closed && card.intrinsic !== IntrinsicStatus.Closed) {
-        set.changes.closedAt = at;
-    }
-    else if (intrinsic !== IntrinsicStatus.Closed && card.closedAt != null) {
-        set.unset.push('closedAt');
-    }
-    return { ...set, flow: flowId, from, to: rule.to };
+        const flows = { ...card.flows, [flowId]: rule.to };
+        set.changes.flows = { [flowId]: rule.to };
+        if (flowId === primary) {
+            set.changes.status = rule.to;
+        }
+        const intrinsic = statusHelper.resolveIntrinsic(type, flows, registry);
+        if (intrinsic !== card.intrinsic) {
+            set.changes.intrinsic = intrinsic;
+        }
+        if (intrinsic === IntrinsicStatus.Closed && card.intrinsic !== IntrinsicStatus.Closed) {
+            set.changes.closedAt = at;
+        }
+        else if (intrinsic !== IntrinsicStatus.Closed && card.closedAt != null) {
+            set.unset.push('closedAt');
+        }
+        return { ...set, flow: flowId, from, to: rule.to };
+    };
+    const isEmptyChange = (set) => set.unset.length === 0 && Object.entries(set.changes).every(([, value]) => value === undefined || (isPlainObject(value) && Object.keys(value).length === 0));
+    return { sameValue, mergeFields, applyUnset, assertMutable, computeChanges, isEmptyChange };
 };
-/** Nothing to write: no changed value and nothing to clear. */
-export const isEmptyChange = (set) => set.unset.length === 0 && Object.entries(set.changes).every(([, value]) => value === undefined || (isPlainObject(value) && Object.keys(value).length === 0));
+export const changesHelper = createChangesHelper();
+/** @deprecated compat:factory-refactor — use `changesHelper.sameValue(…)` */
+export const sameValue = (left, right) => changesHelper.sameValue(left, right);
+/** @deprecated compat:factory-refactor — use `changesHelper.mergeFields(…)` */
+export const mergeFields = (base, patch) => changesHelper.mergeFields(base, patch);
+/** @deprecated compat:factory-refactor — use `changesHelper.applyUnset(…)` */
+export const applyUnset = (record, unset) => changesHelper.applyUnset(record, unset);
+/** @deprecated compat:factory-refactor — use `changesHelper.assertMutable(…)` */
+export const assertMutable = (exec, type) => changesHelper.assertMutable(exec, type);
+/** @deprecated compat:factory-refactor — use `changesHelper.computeChanges(…)` */
+export const computeChanges = (card, exec, type, registry, at, opts) => changesHelper.computeChanges(card, exec, type, registry, at, opts);
+/** @deprecated compat:factory-refactor — use `changesHelper.isEmptyChange(…)` */
+export const isEmptyChange = (set) => changesHelper.isEmptyChange(set);
 //# sourceMappingURL=changes.js.map