@things-factory/fact-change 0.0.0-stage → 10.1.145

package/dist-server/index.d.ts

@@ -0,0 +1,6 @@
+import { FactChange } from './service/fact-change.js';
+export * from './service/fact-change.js';
+export * from './service/fact-change-text.js';
+export * from './service/fact-change-rows.js';
+export * from './service/fact-change-service.js';
+export declare const entities: (typeof FactChange)[];

package/dist-server/index.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.entities = void 0;
+const tslib_1 = require("tslib");
+/*
+ * What moved on a recorded fact, field by field (ADR-0124).
+ *
+ * plant (`fact_changes`) and warehouse (`warehouse_change_records`) each kept the same table, and
+ * station asked every product for a function that wrote into it. This package holds the one table, the
+ * writer every product and station call, and the helpers that turn two versions of a fact into rows.
+ * Products keep their vocabulary (`factKind`, `source`) and their own read queries and privileges.
+ */
+const fact_change_js_1 = require("./service/fact-change.js");
+tslib_1.__exportStar(require("./service/fact-change.js"), exports);
+tslib_1.__exportStar(require("./service/fact-change-text.js"), exports);
+tslib_1.__exportStar(require("./service/fact-change-rows.js"), exports);
+tslib_1.__exportStar(require("./service/fact-change-service.js"), exports);
+exports.entities = [fact_change_js_1.FactChange];
+//# sourceMappingURL=index.js.map

package/dist-server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../server/index.ts"],"names":[],"mappings":";;;;AAAA;;;;;;;GAOG;AACH,6DAAqD;AAErD,mEAAwC;AACxC,wEAA6C;AAC7C,wEAA6C;AAC7C,2EAAgD;AAEnC,QAAA,QAAQ,GAAG,CAAC,2BAAU,CAAC,CAAA","sourcesContent":["/*\n * What moved on a recorded fact, field by field (ADR-0124).\n *\n * plant (`fact_changes`) and warehouse (`warehouse_change_records`) each kept the same table, and\n * station asked every product for a function that wrote into it. This package holds the one table, the\n * writer every product and station call, and the helpers that turn two versions of a fact into rows.\n * Products keep their vocabulary (`factKind`, `source`) and their own read queries and privileges.\n */\nimport { FactChange } from './service/fact-change.js'\n\nexport * from './service/fact-change.js'\nexport * from './service/fact-change-text.js'\nexport * from './service/fact-change-rows.js'\nexport * from './service/fact-change-service.js'\n\nexport const entities = [FactChange]\n"]}

package/dist-server/service/fact-change-rows.d.ts

@@ -0,0 +1,45 @@
+import { type MaybeTransactional } from '@things-factory/webhook/writing-transaction';
+import type { FieldChange } from './fact-change-text.js';
+/**
+ * Which rows a change becomes, and when it may be written — judgement only, no storage, so tests run
+ * without a database.
+ */
+export interface FactChangeWhat {
+    /** Which kind of fact — the product's vocabulary (`job-order`, `station-screen-spec`, …). */
+    factKind: string;
+    /** The fact, by name. */
+    factName: string;
+    changes: FieldChange[];
+    at?: Date;
+}
+export interface FactChangeBy {
+    user?: unknown;
+    /** Where the change came from, in the product's own words (plant: `manual` · `twin-command` · `intake`). */
+    source?: string;
+    /** Why. May be empty: empty means nobody wrote one, not that there was no reason. */
+    reason?: string;
+    /** The approval it came through. Who approved is kept by worklist; this points there. */
+    activityInstanceId?: string;
+}
+export interface FactChangeRow extends FieldChange {
+    factKind: string;
+    factName: string;
+    at: Date;
+    source?: string;
+    reason?: string;
+    activityInstanceId?: string;
+    changedBy?: unknown;
+}
+/**
+ * The rows to write. No moved field, no row — a history filled with "nothing happened" is a history
+ * nobody reads.
+ *
+ * A change that does not say which fact and which field moved is refused: a row about nothing can never
+ * be found again and only inflates the count.
+ */
+export declare function factChangeRows(what: FactChangeWhat, by: FactChangeBy, now: Date): FactChangeRow[];
+/**
+ * A change row is written in the transaction that makes the change. Committed on its own, it outlives a
+ * change that then fails, and the history says something happened that did not.
+ */
+export declare function assertFactChangeInTransaction(manager: MaybeTransactional | undefined | null): void;

package/dist-server/service/fact-change-rows.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.factChangeRows = factChangeRows;
+exports.assertFactChangeInTransaction = assertFactChangeInTransaction;
+const refusal_js_1 = require("@things-factory/shell/dist-server/refusal/refusal.js");
+const writing_transaction_1 = require("@things-factory/webhook/writing-transaction");
+const blank = (value) => typeof value !== 'string' || !value.trim();
+/**
+ * The rows to write. No moved field, no row — a history filled with "nothing happened" is a history
+ * nobody reads.
+ *
+ * A change that does not say which fact and which field moved is refused: a row about nothing can never
+ * be found again and only inflates the count.
+ */
+function factChangeRows(what, by, now) {
+    if (!what.changes?.length)
+        return [];
+    if (blank(what.factKind) || blank(what.factName) || what.changes.some(one => blank(one.field))) {
+        throw new refusal_js_1.Refusal('change-names-no-fact', { kind: what.factKind ?? '', name: what.factName ?? '' }, 'a change record has to say which fact and which field moved');
+    }
+    const at = what.at ?? now;
+    return what.changes.map(one => ({
+        factKind: what.factKind,
+        factName: what.factName,
+        field: one.field,
+        ...(one.fromValue !== undefined ? { fromValue: one.fromValue } : {}),
+        ...(one.toValue !== undefined ? { toValue: one.toValue } : {}),
+        at,
+        ...(by.source ? { source: by.source } : {}),
+        ...(by.reason ? { reason: by.reason } : {}),
+        ...(by.activityInstanceId ? { activityInstanceId: by.activityInstanceId } : {}),
+        ...(by.user ? { changedBy: by.user } : {})
+    }));
+}
+/**
+ * A change row is written in the transaction that makes the change. Committed on its own, it outlives a
+ * change that then fails, and the history says something happened that did not.
+ */
+function assertFactChangeInTransaction(manager) {
+    if ((0, writing_transaction_1.isWritingTransaction)(manager))
+        return;
+    throw new refusal_js_1.Refusal('change-record-outside-transaction', {}, 'a change record is written in the transaction that makes the change - on its own it can outlive a change that failed');
+}
+//# sourceMappingURL=fact-change-rows.js.map

package/dist-server/service/fact-change-rows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-change-rows.js","sourceRoot":"","sources":["../../server/service/fact-change-rows.ts"],"names":[],"mappings":";;AA+CA,wCAyBC;AAMD,sEAQC;AAtFD,qFAA8E;AAC9E,qFAA2G;AAqC3G,MAAM,KAAK,GAAG,CAAC,KAAc,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;AAE5E;;;;;;GAMG;AACH,SAAgB,cAAc,CAAC,IAAoB,EAAE,EAAgB,EAAE,GAAS;IAC9E,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM;QAAE,OAAO,EAAE,CAAA;IAEpC,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QAC/F,MAAM,IAAI,oBAAO,CACf,sBAAsB,EACtB,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,IAAI,EAAE,EAAE,EACxD,6DAA6D,CAC9D,CAAA;IACH,CAAC;IAED,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,IAAI,GAAG,CAAA;IAEzB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9B,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,GAAG,CAAC,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,GAAG,CAAC,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,EAAE;QACF,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,GAAG,CAAC,EAAE,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,EAAE,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/E,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3C,CAAC,CAAC,CAAA;AACL,CAAC;AAED;;;GAGG;AACH,SAAgB,6BAA6B,CAAC,OAA8C;IAC1F,IAAI,IAAA,0CAAoB,EAAC,OAAO,CAAC;QAAE,OAAM;IAEzC,MAAM,IAAI,oBAAO,CACf,mCAAmC,EACnC,EAAE,EACF,sHAAsH,CACvH,CAAA;AACH,CAAC","sourcesContent":["import { Refusal } from '@things-factory/shell/dist-server/refusal/refusal.js'\nimport { isWritingTransaction, type MaybeTransactional } from '@things-factory/webhook/writing-transaction'\n\nimport type { FieldChange } from './fact-change-text.js'\n\n/**\n * Which rows a change becomes, and when it may be written — judgement only, no storage, so tests run\n * without a database.\n */\nexport interface FactChangeWhat {\n  /** Which kind of fact — the product's vocabulary (`job-order`, `station-screen-spec`, …). */\n  factKind: string\n  /** The fact, by name. */\n  factName: string\n  changes: FieldChange[]\n  at?: Date\n}\n\nexport interface FactChangeBy {\n  user?: unknown\n  /** Where the change came from, in the product's own words (plant: `manual` · `twin-command` · `intake`). */\n  source?: string\n  /** Why. May be empty: empty means nobody wrote one, not that there was no reason. */\n  reason?: string\n  /** The approval it came through. Who approved is kept by worklist; this points there. */\n  activityInstanceId?: string\n}\n\nexport interface FactChangeRow extends FieldChange {\n  factKind: string\n  factName: string\n  at: Date\n  source?: string\n  reason?: string\n  activityInstanceId?: string\n  changedBy?: unknown\n}\n\nconst blank = (value: unknown) => typeof value !== 'string' || !value.trim()\n\n/**\n * The rows to write. No moved field, no row — a history filled with \"nothing happened\" is a history\n * nobody reads.\n *\n * A change that does not say which fact and which field moved is refused: a row about nothing can never\n * be found again and only inflates the count.\n */\nexport function factChangeRows(what: FactChangeWhat, by: FactChangeBy, now: Date): FactChangeRow[] {\n  if (!what.changes?.length) return []\n\n  if (blank(what.factKind) || blank(what.factName) || what.changes.some(one => blank(one.field))) {\n    throw new Refusal(\n      'change-names-no-fact',\n      { kind: what.factKind ?? '', name: what.factName ?? '' },\n      'a change record has to say which fact and which field moved'\n    )\n  }\n\n  const at = what.at ?? now\n\n  return what.changes.map(one => ({\n    factKind: what.factKind,\n    factName: what.factName,\n    field: one.field,\n    ...(one.fromValue !== undefined ? { fromValue: one.fromValue } : {}),\n    ...(one.toValue !== undefined ? { toValue: one.toValue } : {}),\n    at,\n    ...(by.source ? { source: by.source } : {}),\n    ...(by.reason ? { reason: by.reason } : {}),\n    ...(by.activityInstanceId ? { activityInstanceId: by.activityInstanceId } : {}),\n    ...(by.user ? { changedBy: by.user } : {})\n  }))\n}\n\n/**\n * A change row is written in the transaction that makes the change. Committed on its own, it outlives a\n * change that then fails, and the history says something happened that did not.\n */\nexport function assertFactChangeInTransaction(manager: MaybeTransactional | undefined | null): void {\n  if (isWritingTransaction(manager)) return\n\n  throw new Refusal(\n    'change-record-outside-transaction',\n    {},\n    'a change record is written in the transaction that makes the change - on its own it can outlive a change that failed'\n  )\n}\n"]}

package/dist-server/service/fact-change-service.d.ts

@@ -0,0 +1,17 @@
+import type { EntityManager } from 'typeorm';
+import type { Domain } from '@things-factory/shell';
+import { FactChange } from './fact-change.js';
+import { type FactChangeBy, type FactChangeWhat } from './fact-change-rows.js';
+/**
+ * Writes the fields that moved, inside the caller's transaction. Returns how many rows were written;
+ * an empty change list writes nothing.
+ */
+export declare function recordFactChanges(manager: EntityManager, domain: Domain, what: FactChangeWhat, by?: FactChangeBy): Promise<number>;
+/**
+ * What moved on one fact. The order is the reader's: a panel of recent changes reads newest first, a
+ * history reads in the order things happened.
+ *
+ * There is no door here that reads a whole domain at once: the table only grows. Each product opens its
+ * own query per kind, under that kind's privilege.
+ */
+export declare function readFactChanges(manager: EntityManager, domain: Domain, factKind: string, factName: string, order?: 'newest-first' | 'oldest-first'): Promise<FactChange[]>;

package/dist-server/service/fact-change-service.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordFactChanges = recordFactChanges;
+exports.readFactChanges = readFactChanges;
+const fact_change_js_1 = require("./fact-change.js");
+const fact_change_rows_js_1 = require("./fact-change-rows.js");
+/**
+ * Writes the fields that moved, inside the caller's transaction. Returns how many rows were written;
+ * an empty change list writes nothing.
+ */
+async function recordFactChanges(manager, domain, what, by = {}) {
+    (0, fact_change_rows_js_1.assertFactChangeInTransaction)(manager);
+    const rows = (0, fact_change_rows_js_1.factChangeRows)(what, by, new Date());
+    if (!rows.length)
+        return 0;
+    await manager.getRepository(fact_change_js_1.FactChange).save(rows.map(row => ({ ...row, domain })));
+    return rows.length;
+}
+/**
+ * What moved on one fact. The order is the reader's: a panel of recent changes reads newest first, a
+ * history reads in the order things happened.
+ *
+ * There is no door here that reads a whole domain at once: the table only grows. Each product opens its
+ * own query per kind, under that kind's privilege.
+ */
+async function readFactChanges(manager, domain, factKind, factName, order = 'newest-first') {
+    const direction = order === 'newest-first' ? 'DESC' : 'ASC';
+    return await manager.getRepository(fact_change_js_1.FactChange).find({
+        where: { domain: { id: domain.id }, factKind, factName },
+        relations: { changedBy: true },
+        order: { at: direction, createdAt: direction }
+    });
+}
+//# sourceMappingURL=fact-change-service.js.map

package/dist-server/service/fact-change-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-change-service.js","sourceRoot":"","sources":["../../server/service/fact-change-service.ts"],"names":[],"mappings":";;AAWA,8CAaC;AASD,0CAcC;AA3CD,qDAA6C;AAC7C,+DAA6H;AAE7H;;;GAGG;AACI,KAAK,UAAU,iBAAiB,CACrC,OAAsB,EACtB,MAAc,EACd,IAAoB,EACpB,KAAmB,EAAE;IAErB,IAAA,mDAA6B,EAAC,OAAc,CAAC,CAAA;IAE7C,MAAM,IAAI,GAAG,IAAA,oCAAc,EAAC,IAAI,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,CAAA;IACjD,IAAI,CAAC,IAAI,CAAC,MAAM;QAAE,OAAO,CAAC,CAAA;IAE1B,MAAM,OAAO,CAAC,aAAa,CAAC,2BAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,CAAC,CAAQ,CAAC,CAAA;IAC1F,OAAO,IAAI,CAAC,MAAM,CAAA;AACpB,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,eAAe,CACnC,OAAsB,EACtB,MAAc,EACd,QAAgB,EAChB,QAAgB,EAChB,QAAyC,cAAc;IAEvD,MAAM,SAAS,GAAG,KAAK,KAAK,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAA;IAE3D,OAAO,MAAM,OAAO,CAAC,aAAa,CAAC,2BAAU,CAAC,CAAC,IAAI,CAAC;QAClD,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE;QACxD,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE;QAC9B,KAAK,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE;KAC/C,CAAC,CAAA;AACJ,CAAC","sourcesContent":["import type { EntityManager } from 'typeorm'\n\nimport type { Domain } from '@things-factory/shell'\n\nimport { FactChange } from './fact-change.js'\nimport { assertFactChangeInTransaction, factChangeRows, type FactChangeBy, type FactChangeWhat } from './fact-change-rows.js'\n\n/**\n * Writes the fields that moved, inside the caller's transaction. Returns how many rows were written;\n * an empty change list writes nothing.\n */\nexport async function recordFactChanges(\n  manager: EntityManager,\n  domain: Domain,\n  what: FactChangeWhat,\n  by: FactChangeBy = {}\n): Promise<number> {\n  assertFactChangeInTransaction(manager as any)\n\n  const rows = factChangeRows(what, by, new Date())\n  if (!rows.length) return 0\n\n  await manager.getRepository(FactChange).save(rows.map(row => ({ ...row, domain })) as any)\n  return rows.length\n}\n\n/**\n * What moved on one fact. The order is the reader's: a panel of recent changes reads newest first, a\n * history reads in the order things happened.\n *\n * There is no door here that reads a whole domain at once: the table only grows. Each product opens its\n * own query per kind, under that kind's privilege.\n */\nexport async function readFactChanges(\n  manager: EntityManager,\n  domain: Domain,\n  factKind: string,\n  factName: string,\n  order: 'newest-first' | 'oldest-first' = 'newest-first'\n): Promise<FactChange[]> {\n  const direction = order === 'newest-first' ? 'DESC' : 'ASC'\n\n  return await manager.getRepository(FactChange).find({\n    where: { domain: { id: domain.id }, factKind, factName },\n    relations: { changedBy: true },\n    order: { at: direction, createdAt: direction }\n  })\n}\n"]}

package/dist-server/service/fact-change-text.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Turning field values into the text a change row holds, and picking which fields moved.
+ *
+ * Values are written as text because fields have different types (numbers, times, arrays, open bags)
+ * and the row is for reading, not for computing again — the current value lives on the fact itself.
+ * Times are ISO so a reader in another region knows which instant it was; arrays and bags are JSON so
+ * a reordering shows as a change.
+ *
+ * "No value" and "empty value" are different facts. `asText` keeps `undefined` for none, so the column
+ * stays empty, and writes `''` only when the value really was an empty string.
+ */
+export interface FieldChange {
+    field: string;
+    /** The value before; `undefined` when there was none — not an empty string. */
+    fromValue?: string;
+    /** The value after; `undefined` when it was cleared. */
+    toValue?: string;
+}
+export declare function asText(value: unknown): string | undefined;
+/**
+ * Which of `fields` moved between two versions of a fact.
+ *
+ * The caller names the fields because some move on every save without anyone changing them
+ * (`updatedAt`, stamps); comparing everything would bury the real changes under those.
+ */
+export declare function changedFields(before: Record<string, unknown>, after: Record<string, unknown>, fields: readonly string[]): FieldChange[];
+/**
+ * What an overwrite changes, for rows rewritten in place (a decision taken again, a policy, a
+ * destination). Unlike `changedFields`, an empty string counts as no value here: those forms clear a
+ * field by sending `''`, and clearing is not a change from nothing to nothing.
+ */
+export declare function fieldChanges<T extends Record<string, unknown>>(before: Partial<T> | null | undefined, after: Partial<T>, fields: readonly (keyof T & string)[]): FieldChange[];
+/**
+ * A row as it was, at the moment it is deleted: one change per content column with a value, from that
+ * value to nothing. A deletion is reversible only if what it removed stays readable (ADR-0064 ③).
+ */
+export declare function deletionChanges(snapshot: Record<string, unknown>): FieldChange[];

package/dist-server/service/fact-change-text.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asText = asText;
+exports.changedFields = changedFields;
+exports.fieldChanges = fieldChanges;
+exports.deletionChanges = deletionChanges;
+function asText(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+}
+/**
+ * Which of `fields` moved between two versions of a fact.
+ *
+ * The caller names the fields because some move on every save without anyone changing them
+ * (`updatedAt`, stamps); comparing everything would bury the real changes under those.
+ */
+function changedFields(before, after, fields) {
+    const moved = [];
+    for (const field of fields) {
+        const fromValue = asText(before[field]);
+        const toValue = asText(after[field]);
+        if (fromValue === toValue)
+            continue;
+        moved.push({ field, ...(fromValue !== undefined ? { fromValue } : {}), ...(toValue !== undefined ? { toValue } : {}) });
+    }
+    return moved;
+}
+/**
+ * What an overwrite changes, for rows rewritten in place (a decision taken again, a policy, a
+ * destination). Unlike `changedFields`, an empty string counts as no value here: those forms clear a
+ * field by sending `''`, and clearing is not a change from nothing to nothing.
+ */
+function fieldChanges(before, after, fields) {
+    const text = (value) => asText(value === '' ? undefined : value);
+    return fields
+        .map(field => ({ field, fromValue: text(before?.[field]), toValue: text(after[field]) }))
+        .filter(one => one.fromValue !== one.toValue);
+}
+/**
+ * A row as it was, at the moment it is deleted: one change per content column with a value, from that
+ * value to nothing. A deletion is reversible only if what it removed stays readable (ADR-0064 ③).
+ */
+function deletionChanges(snapshot) {
+    return Object.entries(snapshot)
+        .filter(([, value]) => value !== undefined && value !== null && value !== '')
+        .map(([field, value]) => ({ field, fromValue: asText(value) }));
+}
+//# sourceMappingURL=fact-change-text.js.map

package/dist-server/service/fact-change-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-change-text.js","sourceRoot":"","sources":["../../server/service/fact-change-text.ts"],"names":[],"mappings":";;AAmBA,wBAKC;AAQD,sCAeC;AAOD,oCAUC;AAMD,0CAIC;AAvDD,SAAgB,MAAM,CAAC,KAAc;IACnC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAA;IAC3D,IAAI,KAAK,YAAY,IAAI;QAAE,OAAO,KAAK,CAAC,WAAW,EAAE,CAAA;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;IAC3D,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;AACtB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,aAAa,CAC3B,MAA+B,EAC/B,KAA8B,EAC9B,MAAyB;IAEzB,MAAM,KAAK,GAAkB,EAAE,CAAA;IAE/B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;QACvC,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAA;QACpC,IAAI,SAAS,KAAK,OAAO;YAAE,SAAQ;QACnC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;IACzH,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;GAIG;AACH,SAAgB,YAAY,CAC1B,MAAqC,EACrC,KAAiB,EACjB,MAAqC;IAErC,MAAM,IAAI,GAAG,CAAC,KAAc,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;IAEzE,OAAO,MAAM;SACV,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;SACxF,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,SAAS,KAAK,GAAG,CAAC,OAAO,CAAC,CAAA;AACjD,CAAC;AAED;;;GAGG;AACH,SAAgB,eAAe,CAAC,QAAiC;IAC/D,OAAO,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC;SAC5B,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;SAC5E,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;AACnE,CAAC","sourcesContent":["/**\n * Turning field values into the text a change row holds, and picking which fields moved.\n *\n * Values are written as text because fields have different types (numbers, times, arrays, open bags)\n * and the row is for reading, not for computing again — the current value lives on the fact itself.\n * Times are ISO so a reader in another region knows which instant it was; arrays and bags are JSON so\n * a reordering shows as a change.\n *\n * \"No value\" and \"empty value\" are different facts. `asText` keeps `undefined` for none, so the column\n * stays empty, and writes `''` only when the value really was an empty string.\n */\nexport interface FieldChange {\n  field: string\n  /** The value before; `undefined` when there was none — not an empty string. */\n  fromValue?: string\n  /** The value after; `undefined` when it was cleared. */\n  toValue?: string\n}\n\nexport function asText(value: unknown): string | undefined {\n  if (value === undefined || value === null) return undefined\n  if (value instanceof Date) return value.toISOString()\n  if (typeof value === 'object') return JSON.stringify(value)\n  return String(value)\n}\n\n/**\n * Which of `fields` moved between two versions of a fact.\n *\n * The caller names the fields because some move on every save without anyone changing them\n * (`updatedAt`, stamps); comparing everything would bury the real changes under those.\n */\nexport function changedFields(\n  before: Record<string, unknown>,\n  after: Record<string, unknown>,\n  fields: readonly string[]\n): FieldChange[] {\n  const moved: FieldChange[] = []\n\n  for (const field of fields) {\n    const fromValue = asText(before[field])\n    const toValue = asText(after[field])\n    if (fromValue === toValue) continue\n    moved.push({ field, ...(fromValue !== undefined ? { fromValue } : {}), ...(toValue !== undefined ? { toValue } : {}) })\n  }\n\n  return moved\n}\n\n/**\n * What an overwrite changes, for rows rewritten in place (a decision taken again, a policy, a\n * destination). Unlike `changedFields`, an empty string counts as no value here: those forms clear a\n * field by sending `''`, and clearing is not a change from nothing to nothing.\n */\nexport function fieldChanges<T extends Record<string, unknown>>(\n  before: Partial<T> | null | undefined,\n  after: Partial<T>,\n  fields: readonly (keyof T & string)[]\n): FieldChange[] {\n  const text = (value: unknown) => asText(value === '' ? undefined : value)\n\n  return fields\n    .map(field => ({ field, fromValue: text(before?.[field]), toValue: text(after[field]) }))\n    .filter(one => one.fromValue !== one.toValue)\n}\n\n/**\n * A row as it was, at the moment it is deleted: one change per content column with a value, from that\n * value to nothing. A deletion is reversible only if what it removed stays readable (ADR-0064 ③).\n */\nexport function deletionChanges(snapshot: Record<string, unknown>): FieldChange[] {\n  return Object.entries(snapshot)\n    .filter(([, value]) => value !== undefined && value !== null && value !== '')\n    .map(([field, value]) => ({ field, fromValue: asText(value) }))\n}\n"]}

package/dist-server/service/fact-change.d.ts

@@ -0,0 +1,32 @@
+import { User } from '@things-factory/auth-base';
+import { Domain } from '@things-factory/shell';
+/**
+ * One field of a recorded fact moved — from what, to what, when, who, and through which approval.
+ *
+ * The audit columns a fact carries (`updatedAt`, `updater`) answer only who touched it last; three
+ * changes a day erase the first two. This table keeps each move.
+ *
+ * The fact is addressed by `factKind` + `factName` in the product's vocabulary, so one table serves job
+ * orders, production reports, station screens and anything else without a table per kind (ADR-0124).
+ * Approval details are not copied: `activityInstanceId` points at the worklist record that holds them.
+ */
+export declare class FactChange {
+    readonly id: string;
+    domain?: Domain;
+    domainId?: string;
+    factKind: string;
+    factName: string;
+    field: string;
+    fromValue?: string;
+    toValue?: string;
+    at: Date;
+    /** Where the change came from, in the product's words. Empty when the product does not say. */
+    source?: string;
+    /** Why. Empty means nobody wrote one, not that there was no reason. */
+    reason?: string;
+    activityInstanceId?: string;
+    /** Who changed it. Empty when the system did; `source` then says which. */
+    changedBy?: User;
+    changedById?: string;
+    createdAt?: Date;
+}

package/dist-server/service/fact-change.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FactChange = void 0;
+const tslib_1 = require("tslib");
+const typeorm_1 = require("typeorm");
+const type_graphql_1 = require("type-graphql");
+const auth_base_1 = require("@things-factory/auth-base");
+const shell_1 = require("@things-factory/shell");
+/**
+ * One field of a recorded fact moved — from what, to what, when, who, and through which approval.
+ *
+ * The audit columns a fact carries (`updatedAt`, `updater`) answer only who touched it last; three
+ * changes a day erase the first two. This table keeps each move.
+ *
+ * The fact is addressed by `factKind` + `factName` in the product's vocabulary, so one table serves job
+ * orders, production reports, station screens and anything else without a table per kind (ADR-0124).
+ * Approval details are not copied: `activityInstanceId` points at the worklist record that holds them.
+ */
+let FactChange = class FactChange {
+};
+exports.FactChange = FactChange;
+tslib_1.__decorate([
+    (0, typeorm_1.PrimaryGeneratedColumn)('uuid'),
+    (0, type_graphql_1.Field)(type => type_graphql_1.ID),
+    tslib_1.__metadata("design:type", String)
+], FactChange.prototype, "id", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.ManyToOne)(type => shell_1.Domain),
+    (0, type_graphql_1.Field)(type => shell_1.Domain),
+    tslib_1.__metadata("design:type", shell_1.Domain)
+], FactChange.prototype, "domain", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.RelationId)((change) => change.domain),
+    tslib_1.__metadata("design:type", String)
+], FactChange.prototype, "domainId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'which kind of fact this change belongs to' }),
+    tslib_1.__metadata("design:type", String)
+], FactChange.prototype, "factKind", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'the fact this change belongs to, by name' }),
+    tslib_1.__metadata("design:type", String)
+], FactChange.prototype, "factName", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'which field moved' }),
+    tslib_1.__metadata("design:type", String)
+], FactChange.prototype, "field", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'the value before, as text — empty means it had none' }),
+    tslib_1.__metadata("design:type", String)
+], FactChange.prototype, "fromValue", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'the value after, as text' }),
+    tslib_1.__metadata("design:type", String)
+], FactChange.prototype, "toValue", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'when it moved' }),
+    tslib_1.__metadata("design:type", Date
+    /** Where the change came from, in the product's words. Empty when the product does not say. */
+    )
+], FactChange.prototype, "at", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'varchar', nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: "where this change came from, in the product's words" }),
+    tslib_1.__metadata("design:type", String)
+], FactChange.prototype, "source", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'why — may be empty; empty means nobody wrote one' }),
+    tslib_1.__metadata("design:type", String)
+], FactChange.prototype, "reason", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'the approval this came through' }),
+    tslib_1.__metadata("design:type", String)
+], FactChange.prototype, "activityInstanceId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.ManyToOne)(type => auth_base_1.User, { nullable: true }),
+    (0, type_graphql_1.Field)(type => auth_base_1.User, { nullable: true }),
+    tslib_1.__metadata("design:type", auth_base_1.User)
+], FactChange.prototype, "changedBy", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.RelationId)((change) => change.changedBy),
+    tslib_1.__metadata("design:type", String)
+], FactChange.prototype, "changedById", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.CreateDateColumn)(),
+    (0, type_graphql_1.Field)({ nullable: true }),
+    tslib_1.__metadata("design:type", Date)
+], FactChange.prototype, "createdAt", void 0);
+exports.FactChange = FactChange = tslib_1.__decorate([
+    (0, typeorm_1.Entity)({ name: 'fact_changes' }),
+    (0, typeorm_1.Index)('ix_fact_changes_0', (change) => [change.domain, change.factKind, change.factName, change.at]),
+    (0, type_graphql_1.ObjectType)({ description: 'One recorded change to a fact — what moved, who moved it, and why' })
+], FactChange);
+//# sourceMappingURL=fact-change.js.map

package/dist-server/service/fact-change.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-change.js","sourceRoot":"","sources":["../../server/service/fact-change.ts"],"names":[],"mappings":"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","sourcesContent":["import { Column, CreateDateColumn, Entity, Index, ManyToOne, PrimaryGeneratedColumn, RelationId } from 'typeorm'\nimport { Field, ID, ObjectType } from 'type-graphql'\n\nimport { User } from '@things-factory/auth-base'\nimport { Domain } from '@things-factory/shell'\n\n/**\n * One field of a recorded fact moved — from what, to what, when, who, and through which approval.\n *\n * The audit columns a fact carries (`updatedAt`, `updater`) answer only who touched it last; three\n * changes a day erase the first two. This table keeps each move.\n *\n * The fact is addressed by `factKind` + `factName` in the product's vocabulary, so one table serves job\n * orders, production reports, station screens and anything else without a table per kind (ADR-0124).\n * Approval details are not copied: `activityInstanceId` points at the worklist record that holds them.\n */\n@Entity({ name: 'fact_changes' })\n@Index('ix_fact_changes_0', (change: FactChange) => [change.domain, change.factKind, change.factName, change.at])\n@ObjectType({ description: 'One recorded change to a fact — what moved, who moved it, and why' })\nexport class FactChange {\n  @PrimaryGeneratedColumn('uuid')\n  @Field(type => ID)\n  readonly id: string\n\n  @ManyToOne(type => Domain)\n  @Field(type => Domain)\n  domain?: Domain\n\n  @RelationId((change: FactChange) => change.domain)\n  domainId?: string\n\n  @Column()\n  @Field({ description: 'which kind of fact this change belongs to' })\n  factKind: string\n\n  @Column()\n  @Field({ description: 'the fact this change belongs to, by name' })\n  factName: string\n\n  @Column()\n  @Field({ description: 'which field moved' })\n  field: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'the value before, as text — empty means it had none' })\n  fromValue?: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'the value after, as text' })\n  toValue?: string\n\n  @Column()\n  @Field({ description: 'when it moved' })\n  at: Date\n\n  /** Where the change came from, in the product's words. Empty when the product does not say. */\n  @Column({ type: 'varchar', nullable: true })\n  @Field({ nullable: true, description: \"where this change came from, in the product's words\" })\n  source?: string\n\n  /** Why. Empty means nobody wrote one, not that there was no reason. */\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'why — may be empty; empty means nobody wrote one' })\n  reason?: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'the approval this came through' })\n  activityInstanceId?: string\n\n  /** Who changed it. Empty when the system did; `source` then says which. */\n  @ManyToOne(type => User, { nullable: true })\n  @Field(type => User, { nullable: true })\n  changedBy?: User\n\n  @RelationId((change: FactChange) => change.changedBy)\n  changedById?: string\n\n  @CreateDateColumn()\n  @Field({ nullable: true })\n  createdAt?: Date\n}\n"]}