@things-factory/headless-twin 10.1.3 → 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/reference/twin-reference.ts

@@ -1,13 +1,14 @@
 import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm'
 import { ObjectType, Field, ID, Int } from 'type-graphql'
 
-import { Domain, ScalarObject } from '@things-factory/shell'
+import { Domain, ScalarObject, encryptedJsonColumn } from '@things-factory/shell'
 
 /*
  * TwinReference — 테넌트 스코프의 외부 소스 시스템 연결(실 또는 가상). 트윈 인스턴스가 인제스트되는 원천(Face2, ADR-0018).
  * 전역 인메모리 레퍼런스 레지스트리를 대체하는 영속·도메인별·어댑터 기반 엔티티.
  * inbound 전용(구조·상태). 아웃바운드 액추에이션은 command-routing(ActuationAdapter) 소유.
- * connectionConfig/mappingSpec/scopeSpec 는 simple-json(멀티DB 이식 — postgres/mysql/sqlite/mssql/oracle 공통).
+ * mappingSpec/scopeSpec 는 simple-json(멀티DB 이식 — postgres/mysql/sqlite/mssql/oracle 공통).
+ * connectionConfig 는 자격 증명을 담으므로 암호화되는 텍스트 칸이다(칸 주석 참조).
  * 설계 SoT: operato-twin/design/plans/reference-management.md.
  * (CLAUDE.md: 모든 @ObjectType/@Field 는 영문 description 필수.)
  */
@@ -46,8 +47,32 @@ export class TwinReference {
   @Field({ description: "Adapter type registry key (e.g. 'virtual' | 'rest' | 'db' | 'epcis')." })
   adapterType: string
 
-  @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, { nullable: true, description: 'Adapter-specific connection config (endpoint, credentials, params).' })
+  /**
+   * 이 연결에 필요한 값 — **자격 증명이 여기 들어온다. 그래서 저장될 때 암호화된다.**
+   *
+   * ── 왜 표에 두나 (2026-09-09) ─────────────────────────────────────────────
+   * 비밀값은 환경에 두고 이름으로 고르는 것이 원칙이다(§`webhookSecretCandidates`). 그 원칙은
+   * **설치본마다 하나인 키**에 맞는다 — 배포할 때 넣으면 된다.
+   *
+   * 트윈의 연결은 그 모양이 아니다. **사람이 화면에서 연결을 만든다.** 새 공장을 붙이려고 재배포할
+   * 수는 없으므로, 연결마다 다른 이 값은 표에 있어야 한다. 그 자리에서 원칙이 갈린다:
+   *
+   *     설치본마다 하나인 키   환경변수. 이름이 어느 상대 것인지 말한다
+   *     연결마다 다른 값       표. 대신 저장될 때 암호화한다
+   *
+   * ── 무엇을 지키고 무엇을 못 지키나 ────────────────────────────────────────
+   * 저장된 것을 지킨다 — DB 파일 · 백업 · 복제본. 2026-09-09 에 이 칸에서 `hookSecret` 과 접속
+   * 토큰을 명령 두 개로 읽었다.
+   *
+   * **프로세스를 돌릴 수 있는 사람에게서는 못 지킨다** — 그 사람은 키를 갖고 있다. 그리고 값이
+   * 화면으로 나가는 것도 이 칸이 막지 않는다: 내보내는 쪽이 어댑터 스키마의 `secret: true` 를 보고
+   * 가린다(§`reference-resolver` 의 상세 조회). **두 가지가 갈려 있으므로 한쪽만 하면 반쪽이다.**
+   *
+   * 기존 평문 행은 안 깨진다 — 변환기가 암호문 모양이 아닌 값을 알아보고 파싱하며 경고를 남기고,
+   * 다시 저장될 때 암호화된다.
+   */
+  @Column({ nullable: true, ...encryptedJsonColumn() })
+  @Field(type => ScalarObject, { nullable: true, description: 'Adapter-specific connection config (endpoint, credentials, params). Encrypted at rest; secret-declared fields are masked on the way out.' })
   connectionConfig?: any
 
   @Column({ type: 'simple-json', nullable: true })

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/control-capability.test.ts

@@ -90,14 +90,9 @@ test('라우터가 선언을 본다 — 없으면 사유 코드로 거절한다'
   assert.match(src, /'no-source'/, '원본을 모르는 트윈은 구동 대상이 아니다')
 })
 
-test('내장 시뮬은 자기가 못 하는 것을 못 한다고 말한다 — 재씨앗은 아직 없다', () => {
-  const src = readFileSync(
-    fileURLToPath(new URL('../../operato-twin/server/board/virtual-adapter.ts', import.meta.url)),
-    'utf-8'
-  )
-  /* §4 이후 이 원본은 둘을 선언한다(`live`·`control`) — 순서가 아니라 **있음**을 본다. */
-  assert.match(src, /capabilities: \[[^\]]*'control'[^\]]*\]/, '구동 능력을 선언한다')
-  assert.match(src, /capabilities: \[[^\]]*'live'[^\]]*\]/, '피드 능력도 선언한다(§4)')
-  assert.match(src, /cannot re-seed itself yet/, '없는 기능을 있는 것처럼 답하지 않는다')
-  assert.match(src, /not-running/, '아직 서지 않은 트윈에는 자극을 지어 싣지 않는다')
-})
+/*
+ * The assertion that read `operato-twin/server/board/virtual-adapter.ts` moved to that
+ * package's own tests when the applications became their own repository — a guard reading a
+ * consumer's source has to live where that source lives, or it scans nothing and says green.
+ * See operato-application/packages/operato-twin/test/virtual-adapter-capability.test.ts.
+ */

package/test/dispatch-after-approval-source.test.ts

@@ -0,0 +1,81 @@
+/*
+ * Two properties of the dispatch that follows an approval, guarded by reading its source.
+ *
+ * ── Why source and not behaviour ───────────────────────────────────────────
+ * `dispatchAfterApproval` runs outside the request, touches the database and reaches an
+ * adapter that talks to a factory. It cannot be exercised here. What can be guarded is the
+ * shape of the two decisions that make it safe, and both are visible in the text.
+ *
+ * ── Why the guard lives here now (2026-09-08) ──────────────────────────────
+ * These two assertions were in `operato-twin/test/actuation-gate-walk.test.ts`, reading
+ * `../../headless-twin/server/…`. The applications then moved to the operato-application
+ * repository and that relative path left this repository — three checks failed with ENOENT.
+ *
+ * The subject of both is a file in *this* package, so this is where they belong. The half that
+ * guards the app's own callback (that approval, and only approval, calls dispatch) stays with
+ * the app. A guard reads its own repository; when it has to read across one, the seam is in
+ * the wrong place.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+
+import { guardFile } from './guard-roots.js'
+
+const PLACE = '../server/service/actuation/dispatch-after-approval.ts'
+
+/** The source with comments removed — a term inside a comment is not a use of it. */
+function sourceOf(): string {
+  return readFileSync(guardFile(import.meta.url, PLACE), 'utf8')
+}
+
+function withoutComments(src: string): string {
+  return src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '')
+}
+
+test('dispatch does not run inside the approval transaction', () => {
+  /*
+   * Approval happens inside the worklist's transaction. Sending a request to the factory from
+   * inside it means a rollback cannot take the request back: the plant keeps the work order
+   * and our ledger has the approval undone. What went out over the network was never in the
+   * transaction's care.
+   *
+   * A transaction-bound store is passed the transaction — `databaseCommandStore(tx)`. An
+   * unbound one takes no argument. So the argument list is the property.
+   */
+  const src = withoutComments(sourceOf())
+
+  assert.match(src, /databaseCommandStore\(\)/, 'dispatch uses a transaction-bound store')
+  assert.doesNotMatch(src, /databaseCommandStore\(\s*[a-zA-Z]/, 'dispatch is being handed a transaction store')
+})
+
+test('a failed dispatch does not undo the approval, and does not take the process down', () => {
+  /*
+   * This runs outside the request, in `setImmediate`. A throw there is an unhandled rejection
+   * and the server exits — one undelivered actuation would stop everything else.
+   *
+   * The approval also has to survive an adapter that is down. That is the whole reason
+   * approving and dispatching are two steps, and it is a measured property, not a wish:
+   * command `67f8765a` was dispatched successfully later, on the same approval.
+   */
+  const src = sourceOf()
+
+  assert.match(src, /catch\s*\(/, 'nothing catches a failed dispatch')
+  assert.doesNotMatch(
+    withoutComments(src),
+    /\bthrow\b/,
+    'the dispatch path throws — outside a request that ends the process'
+  )
+})
+
+test('this guard reads the real file, so a wrong path is red and not green', () => {
+  /*
+   * The two checks above fail when a pattern stops matching. They would also "pass" against an
+   * empty string, so the path itself has to be guarded — that is exactly how these assertions
+   * left this repository unnoticed in the first place.
+   */
+  const src = sourceOf()
+
+  assert.ok(src.length > 1000, `the dispatch source is ${src.length} chars — the path is wrong`)
+  assert.match(src, /dispatchAfterApproval/, 'the file read is not the one this guard names')
+})

package/test/guard-roots.ts

@@ -0,0 +1,76 @@
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+/*
+ * ═══════════════════════════════════════════════════════════════════════════
+ * Where the source-reading guards look, and what happens when a place is gone.
+ *
+ * ── Why this exists (2026-09-08) ───────────────────────────────────────────
+ * Four guards in this package read the *consumer's* source as well as their own, because the
+ * defects they catch are committed by callers: a caller that fills a kernel kind with a
+ * literal, a caller that reads the journal without saying it is folding, a caller that
+ * ingests without writing to the ledger.
+ *
+ * The applications then moved to their own repository, and `../../operato-twin/server` stopped
+ * existing. Two of the four failed with ENOENT. **The other two passed** — their directory
+ * walker swallows a missing root:
+ *
+ *     try { entries = readdirSync(dir) } catch { … }
+ *
+ * So half of each of those guards was scanning nothing and reporting green. A guard that
+ * quietly stops guarding is worse than one that fails, because the failure is the only signal
+ * that it was ever load-bearing.
+ *
+ * ── So a missing root is an error, not a skip ──────────────────────────────
+ * `guardRoots` refuses to hand back a root that is not there. The message says which place is
+ * gone and what to do about it, because the answer is not "delete the root" — the code being
+ * guarded still exists, it is just in another repository now, and the guard has to follow it
+ * there.
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+
+/**
+ * Resolve the places a guard scans, and fail loudly if any of them is missing.
+ *
+ * @param base    `import.meta.url` of the calling test.
+ * @param places  Paths relative to that test file.
+ */
+export function guardRoots(base: string, places: readonly string[]): string[] {
+  const missing: string[] = []
+  const roots = places.map(place => {
+    const path = fileURLToPath(new URL(place, base))
+    if (!existsSync(path)) missing.push(place)
+    return path
+  })
+
+  if (missing.length) {
+    throw new Error(
+      `guard root missing: ${missing.join(' · ')}\n` +
+        'This guard reads a consumer\'s source, and that source is no longer at this path.\n' +
+        'The applications moved to the operato-application repository (ADR-0041 era). Move the\n' +
+        'consumer half of this guard there rather than deleting the root — a root removed here\n' +
+        'is a rule that stops being checked, and nothing will say so.'
+    )
+  }
+
+  return roots
+}
+
+/**
+ * Resolve one file a guard reads, and fail loudly if it is gone.
+ *
+ * Same reason as above, for the guards that read a single named file rather than walking a
+ * tree. `readFileSync` would already throw here — this only replaces `ENOENT: no such file`
+ * with a sentence that says what to do.
+ */
+export function guardFile(base: string, place: string): string {
+  const path = fileURLToPath(new URL(place, base))
+  if (!existsSync(path)) {
+    throw new Error(
+      `guard file missing: ${place}\n` +
+        'This guard reads a consumer\'s source. That file moved to the operato-application\n' +
+        'repository — move this assertion there rather than deleting it.'
+    )
+  }
+  return path
+}

package/test/ingest-health-wiring.test.ts

@@ -14,11 +14,10 @@ import assert from 'node:assert/strict'
 import { readFileSync, readdirSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 
+import { guardRoots } from './guard-roots.ts'
+
 /** 훑는 곳 — 이 저장소에서 인제스트를 부를 수 있는 층 둘. */
-const ROOTS = [
-  new URL('../server', import.meta.url).pathname,
-  new URL('../../operato-twin/server', import.meta.url).pathname
-]
+const ROOTS = guardRoots(import.meta.url, ['../server'])
 
 /** 인제스트를 여는 함수 이름. 이 이름이 나오는 자리가 곧 유입 경로다. */
 const INGEST_CALL = 'ingestCanonicalRecords('

package/test/journal-read-discipline.test.ts

@@ -24,11 +24,10 @@ import assert from 'node:assert/strict'
 import { readFileSync, readdirSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 
+import { guardRoots } from './guard-roots.ts'
+
 /** 훑는 곳 — 저널을 읽을 수 있는 층 둘. */
-const ROOTS = [
-  new URL('../server', import.meta.url).pathname,
-  new URL('../../operato-twin/server', import.meta.url).pathname
-]
+const ROOTS = guardRoots(import.meta.url, ['../server'])
 
 const READ = 'getRepository(TwinEvent)'
 /** 폴드라고 밝히는 표식. 이유를 함께 적는 것이 이 표식의 값이다. */

package/test/kernel-kind-guard.test.ts

@@ -25,6 +25,8 @@ import assert from 'node:assert/strict'
 import { readdirSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 
+import { guardRoots } from './guard-roots.ts'
+
 const ENGINE = new URL('../server/engine/twin-engine.ts', import.meta.url).pathname
 const MUTATION = new URL('../server/service/twin-lifecycle/twin-lifecycle-mutation.ts', import.meta.url).pathname
 
@@ -34,7 +36,7 @@ const MUTATION = new URL('../server/service/twin-lifecycle/twin-lifecycle-mutati
  * `det.kind ?? 'wms'` 로 **엔진이 오류를 내기 전에 먼저 값을 정하고** 있었다. 커넥터 spec 도 마찬가지였다.
  * 그래서 두 패키지의 서버 코드를 함께 훑는다.
  */
-const ROOTS = [new URL('../server', import.meta.url).pathname, new URL('../../operato-twin/server', import.meta.url).pathname]
+const ROOTS = guardRoots(import.meta.url, ['../server'])
 
 /**
  * 코드만 본다 — 주석은 **과거를 설명하느라 옛 코드를 그대로 인용한다**(바로 위 머리말이 그렇다).

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')
+})

package/test/rejection-carries-event-id.test.ts

@@ -0,0 +1,101 @@
+/*
+ * A refusal has to name which envelope was refused.
+ *
+ * ── What this catches, and why the existing test did not (2026-09-08) ──────
+ * `rejectedForCaller` pairs a refused record with its envelope by **object identity** — value
+ * comparison would let two identically shaped records take each other's id. Its own test
+ * hands the same object to both sides, so it passes and proves the pairing works.
+ *
+ * It does not prove anything about the real path, because in between
+ * `ingestCanonicalRecords` builds `{ ...r, eventTime, sourceType }` — **a new object**. The
+ * refusal then carries that copy, the copy is not in the identity map, and the response comes
+ * back as `{ record, errors }` with no `eventId`:
+ *
+ *     sent   {"eventId":"probe-eventid-check-001","record":{"kind":"transformation"}}
+ *     back   rejected: [{ record: {kind:"transformation", sourceType:"twin"}, errors:[…] }]
+ *
+ * The sending side cannot mark the row that was refused, so it cannot settle the batch and
+ * its queue stops moving — measured on the plant side as 719 envelopes pending with nothing
+ * lost and nothing advancing.
+ *
+ * So this test walks the seam the way a real envelope does: through the ingest that makes the
+ * copy, then through the pairing. That is the step a pure test of either half cannot take.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { ingestCanonicalRecords } from '../server/engine/canonical-ingest.js'
+import { rejectedForCaller } from '../server/service/reference/hook-rejected.js'
+
+const AT = '2026-09-08T02:00:00.000Z'
+
+/** A transformation the kernel refuses — no inputs, no outputs, no bizStep. */
+const REFUSED = { kind: 'transformation' } as any
+
+test('a refusal names the envelope it came from, after ingest has copied the record', () => {
+  /* The envelope as the hook holds it: the record object, and the id that identifies its row. */
+  const items = [{ record: REFUSED, eventId: 'evt-refused-1' }]
+
+  const result = ingestCanonicalRecords(
+    items.map(i => i.record),
+    'test-domain',
+    AT
+  ) as any
+
+  assert.equal(result.rejected.length, 1, 'the kernel refuses this record')
+
+  const forCaller = rejectedForCaller(result.rejected, items)
+
+  assert.deepEqual(
+    forCaller.map((r: any) => r.eventId),
+    ['evt-refused-1'],
+    'the refusal carries the envelope id — without it the sender cannot mark the row'
+  )
+})
+
+test('two refused records of the same shape keep their own ids', () => {
+  /*
+   * This is why the pairing is by identity and not by value. Both records look the same, and
+   * value comparison would hand the first id to both — the sender would mark one row twice
+   * and leave the other pending forever.
+   */
+  const a = { kind: 'transformation' } as any
+  const b = { kind: 'transformation' } as any
+  const items = [
+    { record: a, eventId: 'evt-a' },
+    { record: b, eventId: 'evt-b' }
+  ]
+
+  const result = ingestCanonicalRecords(
+    items.map(i => i.record),
+    'test-domain',
+    AT
+  ) as any
+  const forCaller = rejectedForCaller(result.rejected, items)
+
+  assert.deepEqual(
+    forCaller.map((r: any) => r.eventId).sort(),
+    ['evt-a', 'evt-b'],
+    'each refusal keeps its own id'
+  )
+})
+
+test('an envelope with no id still says what was refused', () => {
+  /*
+   * A connector that does not number its envelopes gets the record back instead. An empty id
+   * would be worse than none: the sender would look for a row, find nothing, and treat the
+   * batch as understood.
+   */
+  const items = [{ record: REFUSED }]
+
+  const result = ingestCanonicalRecords(
+    items.map(i => i.record),
+    'test-domain',
+    AT
+  ) as any
+  const forCaller = rejectedForCaller(result.rejected, items) as any[]
+
+  assert.equal(forCaller.length, 1)
+  assert.equal('eventId' in forCaller[0], false, 'no id is sent rather than an empty one')
+  assert.ok('record' in forCaller[0], 'the record is sent so a person can see what was dropped')
+})