@things-factory/headless-twin 10.1.4 → 10.1.5

package/server/engine/twin-engine.ts

@@ -1013,9 +1013,21 @@ export class TwinEngine {
       this.pruneJournal(domainId).catch(err => twinError('[twin-engine] journal prune failed', err?.message ?? err))
     }, this.RETENTION_SWEEP_MS)
     if (typeof this.retentionTimer?.unref === 'function') this.retentionTimer.unref()
+    /*
+     * 두 상태를 **다른 문장으로** 말한다.
+     *
+     * 앞서는 한 문장에 `${일수 ?? '(도메인 정책)'}일` 로 끼워 넣었고, 기본값이 없는 배포에서
+     * 「(도메인 정책)일」이 찍혔다(2026-09-09 실측). 뜻이 없는 문장이고, 읽는 사람이 **며칠인지
+     * 적혀 있는데 못 읽는 것**으로 오해한다.
+     *
+     * 수가 들어갈 자리에 수가 아닌 것을 끼우면 그 자리는 값이 아니라 구멍이다. 상태가 둘이면
+     * 문장도 둘이다.
+     */
     twinLog(
-      `[twin-engine] journal retention on — ${this.JOURNAL_RETENTION_DAYS ?? '(도메인 정책)'}일 · ` +
-        `${this.RETENTION_SWEEP_MS / 60000}분마다`
+      this.JOURNAL_RETENTION_DAYS
+        ? `[twin-engine] journal retention on — ${this.JOURNAL_RETENTION_DAYS}일 · ${this.RETENTION_SWEEP_MS / 60000}분마다`
+        : `[twin-engine] journal retention on — 보존 기간은 도메인마다 정한다(프로세스 기본값 없음) · ` +
+            `${this.RETENTION_SWEEP_MS / 60000}분마다`
     )
   }
 

package/server/service/twin-event/twin-event-keys.ts

@@ -26,6 +26,8 @@ export interface TwinEventKeys {
   bizTransaction?: string
   locationId?: string
   moverId?: string
+  /** `'actual'`, `'simulated'`, or absent — absent means not declared, which is not `actual`. */
+  provenance?: string
 }
 
 /*
@@ -168,7 +170,33 @@ export function actionOf(envelope: any): string | undefined {
   return a === 'ADD' || a === 'OBSERVE' || a === 'DELETE' ? a : undefined
 }
 
-/** 한 이벤트에서 승격 키 전부 — 기록 경로가 이 함수 하나만 부른다. */
+/**
+ * **Whether the sender declared this fact as having actually happened** — the envelope's
+ * `provenance`, promoted to a column.
+ *
+ * ── Why it is an indexed column (2026-09-09) ──────────────────────────────
+ * The journal held 1,134 rows, all of them generator output, and there was nowhere to ask about
+ * it. While the declaration sits inside `payload`, none of the five drivers can answer "count
+ * these without the invented ones" — the same reason `action` was promoted.
+ *
+ * ── Only the two declared values are taken ────────────────────────────────
+ * Anything that is not `actual` or `simulated` becomes `undefined`. A source's stray value does
+ * not reach the index (the discipline in `actionOf`).
+ *
+ * **`undefined` means "not declared", not "it happened".** A reader has to distinguish three
+ * states — declared simulated, declared actual, not declared. Folding the last two together
+ * means a generator that omits the field has its output counted as production.
+ */
+export function provenanceOf(envelope: any): string | undefined {
+  /*
+   * Read from the envelope only. `data` is where the source system writes, and a source that
+   * could declare its own facts actual would make this no longer the connecting side's statement.
+   */
+  const p = envelope?.provenance
+  return p === 'actual' || p === 'simulated' ? p : undefined
+}
+
+/** Every promoted key for one event — the write path calls this function and nothing else. */
 export function twinEventKeys(envelope: any): TwinEventKeys {
   return {
     action: actionOf(envelope),
@@ -177,6 +205,7 @@ export function twinEventKeys(envelope: any): TwinEventKeys {
     orderId: clip(orderOf(envelope), 'orderId'),
     bizTransaction: clip(bizTransactionOf(envelope), 'bizTransaction'),
     locationId: clip(locationOf(envelope), 'locationId'),
-    moverId: clip(equipmentIdOf(envelope), 'moverId')
+    moverId: clip(equipmentIdOf(envelope), 'moverId'),
+    provenance: provenanceOf(envelope)
   }
 }

package/server/service/twin-event/twin-event.ts

@@ -202,6 +202,44 @@ export class TwinEvent {
   @Field({ nullable: true, description: 'Equipment identifier carried by operational deltas, promoted from the payload so one machine history can be asked for on the server. The column keeps the legacy name `moverId`: the journal is append-only history and mixing two names for the same fact across time is worse than an outdated name. Renaming belongs with event-schema versioning.' })
   moverId?: string
 
+  /**
+   * **Whether the sender declared this fact as having actually happened** — the envelope's
+   * `provenance`, promoted here.
+   *
+   * ── Why a column (measured 2026-09-09) ──────────────────────────────────
+   * This table held 1,134 rows, all of them generator output, and **there was nowhere to ask
+   * about it**:
+   *
+   * ```
+   * select count(*) from twin_events                      1134
+   * select count(*) where payload like '%SIM-%'           1134
+   * select count(*) where order_id like 'WO-SIM-%'         558   <- half of them
+   * ```
+   *
+   * The only signal was the sender's naming convention (`SIM-`), and the column that convention
+   * reaches was empty on half the rows. While it sits inside `payload`, none of the five drivers
+   * can answer "count these without the invented ones" — the same reason `action` was promoted.
+   *
+   * ── Three states, kept apart ────────────────────────────────────────────
+   * ```
+   * 'simulated'   the sender said it was invented
+   * 'actual'      the sender said it happened
+   * null          **not declared** — which is not `actual`
+   * ```
+   *
+   * Folding the last two together means a generator that omits the declaration has its output
+   * counted as production, and nothing says so. Hence no default: an absent declaration is not
+   * disguised as a valid-looking value (the discipline of `structureRev` and `lastWarningCount`).
+   *
+   * ── No index ────────────────────────────────────────────────────────────
+   * Three possible values is low cardinality within one twin — the judgement already made for
+   * `bizStep` and `locationId`. Performance folds arrive already narrowed by domain, instance and
+   * time, so filtering after that is cheap.
+   */
+  @Column({ length: 16, nullable: true })
+  @Field({ nullable: true, description: 'Whether the sending side declared this fact as actually having happened. Either "actual" or "simulated"; null means it was not declared, which is not the same as actual — a generator that omits it must not be counted as production.' })
+  provenance?: string
+
   @Column({ type: 'simple-json', nullable: true })
   @Field(type => ScalarObject, { nullable: true, description: 'Raw canonical envelope (EPCIS event or operational delta) as JSON.' })
   payload?: any

package/test/provenance-promotion.test.ts

@@ -0,0 +1,99 @@
+/*
+ * Whether a fact was declared as having actually happened, promoted out of the payload.
+ *
+ * ── What this was for (measured 2026-09-09) ───────────────────────────────
+ * The twin's journal held 1,134 rows and every one of them was produced by a generator. There
+ * was no way to ask:
+ *
+ *     select count(*) from twin_events                        1134
+ *     select count(*) where payload like '%SIM-%'             1134
+ *     select count(*) where order_id like 'WO-SIM-%'           558   ← half of them
+ *
+ * The only signal was a naming convention on the sending side (`SIM-`, `WO-SIM-`), and the
+ * column that convention reaches was empty on half the rows. Meanwhile the screens compute
+ * yield and utilisation from those rows and cannot say what they are made of.
+ *
+ * ── The property that matters is the absent case ──────────────────────────
+ * `null` means the sender did not declare, which is **not** "it actually happened". Reading
+ * those two as the same thing is the whole defect: a generator that omits the field has its
+ * output counted as production, and nothing says so.
+ *
+ * So most of what is asserted here is about absence, not about the two declared values.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { provenanceOf, twinEventKeys } from '../server/service/twin-event/twin-event-keys.js'
+
+const envelope = (over: Record<string, unknown> = {}) => ({
+  eventId: 'e1',
+  eventType: 'task.status',
+  eventTime: '2026-09-09T02:00:00.000Z',
+  tenantId: 't1',
+  data: { taskId: 'SIM-ECU-0001-01', status: 'completed' },
+  ...over
+})
+
+test('★ a fact declared simulated says so in a column, not only inside the payload', () => {
+  assert.equal(provenanceOf(envelope({ provenance: 'simulated' })), 'simulated')
+  assert.equal(twinEventKeys(envelope({ provenance: 'simulated' })).provenance, 'simulated')
+})
+
+test('a fact declared actual says that', () => {
+  assert.equal(provenanceOf(envelope({ provenance: 'actual' })), 'actual')
+})
+
+test('★ no declaration is not a declaration of actual — this is the defect being fixed', () => {
+  /*
+   * The payload here carries `SIM-…` in its task id, which is exactly how the 1,134 rows were
+   * recognisable by hand. The column still says nothing, because the sender said nothing. That
+   * is correct: the twin does not judge, it records what it was told.
+   *
+   * A reader has to distinguish three states. If it folds the last two together, a generator
+   * that forgets the field is counted as production.
+   */
+  assert.equal(provenanceOf(envelope()), undefined)
+  assert.equal(twinEventKeys(envelope()).provenance, undefined)
+
+  assert.notEqual(provenanceOf(envelope()), 'actual', 'absent must never resolve to actual')
+})
+
+test('a value the source made up does not reach the index', () => {
+  /*
+   * Same discipline as `actionOf`, which takes only ADD · OBSERVE · DELETE. A column with three
+   * possible values stops being answerable the moment a fourth arrives from a source we do not
+   * control.
+   */
+  for (const bogus of ['ACTUAL', 'Simulated', 'fake', 'true', '', 'sim', 1, true, null, {}]) {
+    assert.equal(provenanceOf(envelope({ provenance: bogus })), undefined, `${JSON.stringify(bogus)} reached the column`)
+  }
+})
+
+test('the declaration is read from the envelope, not from the source data', () => {
+  /*
+   * `data` is where the source system writes. If this were read from there, a source could
+   * declare its own facts actual by writing a key, and the declaration would no longer be the
+   * connecting side's statement. The envelope is ours.
+   */
+  const sneaky = envelope({ data: { taskId: 'x', provenance: 'actual' } })
+  assert.equal(provenanceOf(sneaky), undefined, 'a value inside data was promoted')
+})
+
+test('promoting it does not disturb the keys already promoted', () => {
+  /*
+   * This function is the write path's only promotion point, so adding one key is checked
+   * together with not disturbing the others.
+   */
+  const full = twinEventKeys(
+    envelope({
+      provenance: 'simulated',
+      data: { action: 'OBSERVE', bizStep: 'commissioning', epcList: ['urn:epc:id:sgtin:1.2.3'], orderId: 'WO-1' }
+    })
+  )
+
+  assert.equal(full.action, 'OBSERVE')
+  assert.equal(full.bizStep, 'commissioning')
+  assert.equal(full.epc, 'urn:epc:id:sgtin:1.2.3')
+  assert.equal(full.orderId, 'WO-1')
+  assert.equal(full.provenance, 'simulated')
+})