@things-factory/headless-twin 10.1.3 → 10.1.4

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

package/test/secrets-at-rest.test.ts

@@ -0,0 +1,135 @@
+/*
+ * A column that can hold a credential has to be encrypted at rest.
+ *
+ * ── What this catches, and what it cost to find by hand (2026-09-09) ──────
+ * `TwinReference.connectionConfig` was a plain `simple-json` column holding a signing secret
+ * and a live access token. Two shell commands read both:
+ *
+ *     sqlite3 -readonly db.sqlite "select connection_config from twin_references"
+ *     {"endpoint":"…","hookSecret":"dev-only-localhost-hook-2026","token":"eyJhbGciOi…"}
+ *
+ * The read path was already guarded — the detail resolver masks fields an adapter declares
+ * `secret: true`. So the leak was not on the way out, it was the stored bytes: the database
+ * file, its backups, its replicas. **Two different protections, and having one reads exactly
+ * like having both.**
+ *
+ * ── Why a guard and not a review habit ────────────────────────────────────
+ * The framework has had the pieces for a while — `encryptJsonTransformer` and
+ * `longTextColumn` — and nothing used them together. Two packages imported the transformer and
+ * left it commented out. A rule that depends on someone remembering two exports is a rule that
+ * holds until the next new column.
+ *
+ * So the rule is measured instead: any column whose name says it can carry a credential must
+ * carry an encrypting transformer. New entities are covered the day they are written.
+ *
+ * ── What this does not claim ──────────────────────────────────────────────
+ * Encryption at rest does not protect a value from anyone who can run this process — that
+ * person holds the key. It protects the stored copy, which is a different set of people.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+
+const SERVER = fileURLToPath(new URL('../server', import.meta.url))
+
+/**
+ * 이름이 「자격 증명이 들 수 있다」고 말하는 칸.
+ *
+ * 이름으로 판정하는 것의 한계를 적어 둔다 — `connectionConfig` 처럼 **이름이 비밀을 말하지 않는**
+ * 칸이 실제로 비밀을 담고 있었다. 그래서 그 이름을 목록에 넣는다. 새 칸이 같은 부류이면 여기 더한다.
+ */
+const CREDENTIAL_NAMES = /^(secret|token|password|passwd|apiKey|credential|credentials|privateKey|connectionConfig)\??$/i
+
+/** 암호화를 붙이는 방법 — 둘 중 하나면 된다(shell 이 내놓는 것). */
+const ENCRYPTED = /encryptedJsonColumn\(\)|encryptTransformer|encryptJsonTransformer/
+
+function entityFiles(dir: string, out: string[] = []): string[] {
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name)
+    if (statSync(full).isDirectory()) {
+      entityFiles(full, out)
+      continue
+    }
+    if (!full.endsWith('.ts') || full.endsWith('.d.ts')) continue
+    const src = readFileSync(full, 'utf-8')
+    if (src.includes('@Entity(')) out.push(full)
+  }
+  return out
+}
+
+/** 한 파일에서 `@Column` 선언과 그것이 붙은 속성 이름의 짝. */
+function columnsOf(src: string): { property: string; declaration: string; line: number }[] {
+  const lines = src.split('\n')
+  const out: { property: string; declaration: string; line: number }[] = []
+
+  for (let i = 0; i < lines.length; i++) {
+    if (!/^\s*@Column\(/.test(lines[i])) continue
+
+    /* 선언이 여러 줄일 수 있다 — 괄호가 닫힐 때까지 모은다. */
+    let declaration = ''
+    let depth = 0
+    let j = i
+    do {
+      declaration += lines[j]
+      for (const ch of lines[j]) {
+        if (ch === '(') depth++
+        else if (ch === ')') depth--
+      }
+      j++
+    } while (depth > 0 && j < lines.length && j - i < 12)
+
+    /* 데코레이터 다음의 첫 속성 줄 — 사이에 @Field 등이 끼어든다. */
+    for (let k = j; k < Math.min(j + 6, lines.length); k++) {
+      const m = /^\s{2}(?:readonly\s+)?([A-Za-z_][A-Za-z0-9_]*)\??\s*[:!]/.exec(lines[k])
+      if (m) {
+        out.push({ property: m[1], declaration, line: i + 1 })
+        break
+      }
+    }
+  }
+  return out
+}
+
+test('★ a column that can hold a credential is encrypted at rest', () => {
+  const offenders: string[] = []
+  let examined = 0
+
+  for (const file of entityFiles(SERVER)) {
+    const src = readFileSync(file, 'utf-8')
+    for (const column of columnsOf(src)) {
+      examined++
+      if (!CREDENTIAL_NAMES.test(column.property)) continue
+      if (ENCRYPTED.test(column.declaration)) continue
+      offenders.push(`${file.slice(SERVER.length + 1)}:${column.line}  ${column.property}`)
+    }
+  }
+
+  assert.ok(examined > 40, `본 칸이 ${examined}개다 — 찾는 방법이 깨졌다`)
+  assert.deepEqual(
+    offenders,
+    [],
+    'these columns can hold a credential and are stored in the clear:\n  ' +
+      offenders.join('\n  ') +
+      '\nAdd ...encryptedJsonColumn() (json) or transformer: encryptTransformer (string) from @things-factory/shell.\n' +
+      'Note the column type has to change with it — encryptedJsonColumn() carries both, which is why it exists.'
+  )
+})
+
+test('this guard reads real entities, so a broken scan is red and not green', () => {
+  /*
+   * 위 검사는 위반이 없으면 통과한다. **아무것도 못 읽어도** 통과하므로, 읽었다는 사실을 따로 잰다 —
+   * 오늘 이 저장소의 다른 검사가 견준 것이 0인데 초록이던 부류가 넷이었다.
+   */
+  const files = entityFiles(SERVER)
+  assert.ok(files.length > 10, `엔티티 파일이 ${files.length}개다 — 순회가 깨졌다`)
+
+  const reference = files.find(f => f.endsWith('twin-reference.ts'))
+  assert.ok(reference, 'twin-reference.ts 를 못 찾았다 — 이 검사가 생긴 이유가 그 파일이다')
+
+  const found = columnsOf(readFileSync(reference!, 'utf-8'))
+  const config = found.find(c => c.property === 'connectionConfig')
+  assert.ok(config, 'connectionConfig 칸을 못 읽었다 — 짝짓기가 깨졌다')
+  assert.match(config!.declaration, ENCRYPTED, 'connectionConfig 가 암호화되어 있지 않다')
+})