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

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@things-factory/fact-change",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "10.1.142",
+  "main": "dist-server/index.js",
+  "things-factory": true,
+  "license": "MIT",
+  "author": "heartyoh <heartyoh@hatiolab.com>",
+  "description": "What moved on a recorded fact, field by field — from what, to what, who, and through which approval",
+  "publishConfig": {
+    "access": "public",
+    "@things-factory:registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hatiolab/things-factory.git",
+    "directory": "packages/fact-change"
+  },
+  "scripts": {
+    "build": "npm run build:server",
+    "build:server": "npx tsc --p ./server/tsconfig.json",
+    "clean:server": "npx rimraf dist-server",
+    "clean": "npm run clean:server",
+    "test": "npx tsc --p ./server/tsconfig.json && node --import ./test/resolve-ts-siblings.mjs --test test/*.test.ts"
+  },
+  "dependencies": {
+    "@things-factory/auth-base": "^10.1.142",
+    "@things-factory/shell": "^10.1.142",
+    "@things-factory/webhook": "^10.1.142"
+  },
+  "gitHead": "73522201151b0156168b0eeea15f2962cda0bd8f"
+}

package/server/index.ts

@@ -0,0 +1,16 @@
+/*
+ * 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.
+ */
+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 const entities = [FactChange]

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

@@ -0,0 +1,87 @@
+import { Refusal } from '@things-factory/shell/dist-server/refusal/refusal.js'
+import { isWritingTransaction, 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
+}
+
+const blank = (value: unknown) => 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.
+ */
+export function factChangeRows(what: FactChangeWhat, by: FactChangeBy, now: Date): FactChangeRow[] {
+  if (!what.changes?.length) return []
+
+  if (blank(what.factKind) || blank(what.factName) || what.changes.some(one => blank(one.field))) {
+    throw new 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.
+ */
+export function assertFactChangeInTransaction(manager: MaybeTransactional | undefined | null): void {
+  if (isWritingTransaction(manager)) return
+
+  throw new 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'
+  )
+}

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

@@ -0,0 +1,48 @@
+import type { EntityManager } from 'typeorm'
+
+import type { Domain } from '@things-factory/shell'
+
+import { FactChange } from './fact-change.js'
+import { assertFactChangeInTransaction, factChangeRows, 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 async function recordFactChanges(
+  manager: EntityManager,
+  domain: Domain,
+  what: FactChangeWhat,
+  by: FactChangeBy = {}
+): Promise<number> {
+  assertFactChangeInTransaction(manager as any)
+
+  const rows = factChangeRows(what, by, new Date())
+  if (!rows.length) return 0
+
+  await manager.getRepository(FactChange).save(rows.map(row => ({ ...row, domain })) as any)
+  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.
+ */
+export async function readFactChanges(
+  manager: EntityManager,
+  domain: Domain,
+  factKind: string,
+  factName: string,
+  order: 'newest-first' | 'oldest-first' = 'newest-first'
+): Promise<FactChange[]> {
+  const direction = order === 'newest-first' ? 'DESC' : 'ASC'
+
+  return await manager.getRepository(FactChange).find({
+    where: { domain: { id: domain.id }, factKind, factName },
+    relations: { changedBy: true },
+    order: { at: direction, createdAt: direction }
+  })
+}

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

@@ -0,0 +1,75 @@
+/**
+ * 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 function asText(value: unknown): string | undefined {
+  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.
+ */
+export function changedFields(
+  before: Record<string, unknown>,
+  after: Record<string, unknown>,
+  fields: readonly string[]
+): FieldChange[] {
+  const moved: FieldChange[] = []
+
+  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.
+ */
+export function fieldChanges<T extends Record<string, unknown>>(
+  before: Partial<T> | null | undefined,
+  after: Partial<T>,
+  fields: readonly (keyof T & string)[]
+): FieldChange[] {
+  const text = (value: unknown) => 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 ③).
+ */
+export function deletionChanges(snapshot: Record<string, unknown>): FieldChange[] {
+  return Object.entries(snapshot)
+    .filter(([, value]) => value !== undefined && value !== null && value !== '')
+    .map(([field, value]) => ({ field, fromValue: asText(value) }))
+}

package/server/service/fact-change.ts

@@ -0,0 +1,81 @@
+import { Column, CreateDateColumn, Entity, Index, ManyToOne, PrimaryGeneratedColumn, RelationId } from 'typeorm'
+import { Field, ID, ObjectType } from 'type-graphql'
+
+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.
+ */
+@Entity({ name: 'fact_changes' })
+@Index('ix_fact_changes_0', (change: FactChange) => [change.domain, change.factKind, change.factName, change.at])
+@ObjectType({ description: 'One recorded change to a fact — what moved, who moved it, and why' })
+export class FactChange {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID)
+  readonly id: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain)
+  domain?: Domain
+
+  @RelationId((change: FactChange) => change.domain)
+  domainId?: string
+
+  @Column()
+  @Field({ description: 'which kind of fact this change belongs to' })
+  factKind: string
+
+  @Column()
+  @Field({ description: 'the fact this change belongs to, by name' })
+  factName: string
+
+  @Column()
+  @Field({ description: 'which field moved' })
+  field: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'the value before, as text — empty means it had none' })
+  fromValue?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'the value after, as text' })
+  toValue?: string
+
+  @Column()
+  @Field({ description: 'when it moved' })
+  at: Date
+
+  /** Where the change came from, in the product's words. Empty when the product does not say. */
+  @Column({ type: 'varchar', nullable: true })
+  @Field({ nullable: true, description: "where this change came from, in the product's words" })
+  source?: string
+
+  /** Why. Empty means nobody wrote one, not that there was no reason. */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'why — may be empty; empty means nobody wrote one' })
+  reason?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'the approval this came through' })
+  activityInstanceId?: string
+
+  /** Who changed it. Empty when the system did; `source` then says which. */
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true })
+  changedBy?: User
+
+  @RelationId((change: FactChange) => change.changedBy)
+  changedById?: string
+
+  @CreateDateColumn()
+  @Field({ nullable: true })
+  createdAt?: Date
+}

package/server/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig-base.json",
+  "compilerOptions": {
+    "strict": false,
+    "module": "commonjs",
+    "outDir": "../dist-server",
+    "baseUrl": "./"
+  },
+  "include": ["./**/*"]
+}

package/test/fact-change-db.test.ts

@@ -0,0 +1,90 @@
+/*
+ * The change log written in a real transaction and read back. It runs on the built output (`dist-server`)
+ * because the entity needs its decorators compiled; `npm test` builds first.
+ */
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+import { after, before, test } from 'node:test'
+
+const req = createRequire(import.meta.url)
+const { NamingStrategy, addDataSource, removeDataSource, entities: shellEntities, Domain } = req('@things-factory/shell')
+const { entities: authEntities } = req('@things-factory/auth-base')
+const factChange = req('../dist-server/index.js')
+const { DataSource } = req('typeorm')
+
+let ds: any
+let domain: any
+
+const withdrawn = (name: string) => ({
+  factKind: 'station-screen-spec',
+  factName: name,
+  changes: [
+    { field: 'name', fromValue: 'dock receiving' },
+    { field: 'controlled', fromValue: 'true' }
+  ]
+})
+
+before(async () => {
+  ds = new DataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    namingStrategy: new NamingStrategy(),
+    entities: [...shellEntities, ...authEntities, ...factChange.entities],
+    logging: false
+  })
+  await ds.initialize()
+  addDataSource('default', ds)
+  domain = await ds.getRepository(Domain).save({ name: 'change-test', subdomain: 'change-test' })
+})
+
+after(async () => {
+  removeDataSource?.('default')
+  if (ds?.isInitialized) await ds.destroy()
+})
+
+test('written inside the transaction that makes the change, one row per field, in the table fact_changes', async () => {
+  await ds.transaction(async (tx: any) => {
+    assert.equal(await factChange.recordFactChanges(tx, domain, withdrawn('board-1'), { activityInstanceId: 'ai-1' }), 2)
+  })
+
+  const tables = await ds.query(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'fact_changes'`)
+  assert.equal(tables.length, 1)
+
+  const rows = await factChange.readFactChanges(ds.manager, domain, 'station-screen-spec', 'board-1', 'oldest-first')
+  assert.deepEqual(rows.map((row: any) => [row.field, row.fromValue, row.activityInstanceId]).sort(), [
+    ['controlled', 'true', 'ai-1'],
+    ['name', 'dock receiving', 'ai-1']
+  ])
+})
+
+test('a change that fails takes its record with it', async () => {
+  await assert.rejects(
+    ds.transaction(async (tx: any) => {
+      await factChange.recordFactChanges(tx, domain, withdrawn('board-2'))
+      throw new Error('the delete after the record failed')
+    })
+  )
+  assert.deepEqual(await factChange.readFactChanges(ds.manager, domain, 'station-screen-spec', 'board-2'), [])
+})
+
+test('outside a transaction nothing is written', async () => {
+  await assert.rejects(
+    factChange.recordFactChanges(ds.manager, domain, withdrawn('board-3')),
+    (error: any) => error?.code === 'change-record-outside-transaction'
+  )
+  assert.deepEqual(await factChange.readFactChanges(ds.manager, domain, 'station-screen-spec', 'board-3'), [])
+})
+
+test('reads newest first unless the reader asks for the order things happened', async () => {
+  const kind = 'job-order'
+  await ds.transaction(async (tx: any) => {
+    await factChange.recordFactChanges(tx, domain, { factKind: kind, factName: 'WO-1', at: new Date('2026-10-01T00:00:00Z'), changes: [{ field: 'priority', fromValue: '1', toValue: '2' }] })
+    await factChange.recordFactChanges(tx, domain, { factKind: kind, factName: 'WO-1', at: new Date('2026-10-02T00:00:00Z'), changes: [{ field: 'priority', fromValue: '2', toValue: '3' }] })
+  })
+
+  const newest = await factChange.readFactChanges(ds.manager, domain, kind, 'WO-1')
+  const oldest = await factChange.readFactChanges(ds.manager, domain, kind, 'WO-1', 'oldest-first')
+  assert.deepEqual(newest.map((row: any) => row.toValue), ['3', '2'])
+  assert.deepEqual(oldest.map((row: any) => row.toValue), ['2', '3'])
+})

package/test/fact-change-rows.test.ts

@@ -0,0 +1,65 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import { Refusal } from '@things-factory/shell/dist-server/refusal/refusal.js'
+
+import { assertFactChangeInTransaction, factChangeRows } from '../server/service/fact-change-rows.js'
+
+/*
+ * Which rows a change becomes, and when it may be written. Ported from operato-warehouse's change-record
+ * tests when the log moved here (ADR-0124).
+ */
+const AT = new Date('2026-09-24T03:00:00.000Z')
+const withdrawn = {
+  factKind: 'station-screen-spec',
+  factName: 'board-7',
+  changes: [
+    { field: 'name', fromValue: 'dock receiving' },
+    { field: 'controlled', fromValue: 'true' }
+  ]
+}
+
+test('each field that moved is one row, with what it was, who moved it, when, and through what', () => {
+  const rows = factChangeRows(withdrawn, { user: { id: 'u-1' }, activityInstanceId: 'ai-9', source: 'manual', reason: 'retired' }, AT)
+
+  assert.deepEqual(
+    rows.map(row => [row.field, row.fromValue, row.toValue, row.at.toISOString(), row.activityInstanceId, row.source, row.reason]),
+    [
+      ['name', 'dock receiving', undefined, AT.toISOString(), 'ai-9', 'manual', 'retired'],
+      ['controlled', 'true', undefined, AT.toISOString(), 'ai-9', 'manual', 'retired']
+    ]
+  )
+  assert.deepEqual(rows[0].changedBy, { id: 'u-1' })
+})
+
+test('a product that keeps no source or reason writes none', () => {
+  const [row] = factChangeRows(withdrawn, {}, AT)
+  assert.equal('source' in row, false)
+  assert.equal('reason' in row, false)
+})
+
+test('the time the change says wins over the time it was written down', () => {
+  const said = new Date('2026-09-20T00:00:00.000Z')
+  assert.equal(factChangeRows({ ...withdrawn, at: said }, {}, AT)[0].at.toISOString(), said.toISOString())
+})
+
+test('nothing moved is nothing written', () => {
+  assert.deepEqual(factChangeRows({ ...withdrawn, changes: [] }, {}, AT), [])
+})
+
+test('a change about no fact is refused rather than written about nothing', () => {
+  for (const what of [{ ...withdrawn, factKind: '' }, { ...withdrawn, factName: ' ' }, { ...withdrawn, changes: [{ field: '' }] }]) {
+    assert.throws(
+      () => factChangeRows(what, {}, AT),
+      (error: unknown) => error instanceof Refusal && error.code === 'change-names-no-fact'
+    )
+  }
+})
+
+test('outside a transaction it refuses: the record and the change it describes go in together', () => {
+  assert.throws(
+    () => assertFactChangeInTransaction({}),
+    (error: unknown) => error instanceof Refusal && error.code === 'change-record-outside-transaction'
+  )
+  assert.doesNotThrow(() => assertFactChangeInTransaction({ queryRunner: { isTransactionActive: true } }))
+})

package/test/fact-change-text.test.ts

@@ -0,0 +1,87 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import { asText, changedFields, deletionChanges, fieldChanges } from '../server/service/fact-change-text.js'
+
+/*
+ * A recorded fact can be corrected, and the history has to say what moved. Ported from operato-plant's
+ * fact-change-diff and deletion-changes tests when the log moved here (ADR-0124).
+ */
+describe('changedFields', () => {
+  it('names only the fields that moved', () => {
+    const moved = changedFields(
+      { goodCount: 100, nonconformingCount: 0, status: 'started' },
+      { goodCount: 98, nonconformingCount: 2, status: 'started' },
+      ['goodCount', 'nonconformingCount', 'status']
+    )
+    assert.deepEqual(moved.map(one => one.field), ['goodCount', 'nonconformingCount'])
+  })
+
+  it('looks only at the fields the caller names, so fields that move on every save stay out', () => {
+    const moved = changedFields(
+      { goodCount: 1, updatedAt: new Date('2026-09-08T00:00:00Z') },
+      { goodCount: 2, updatedAt: new Date('2026-09-08T01:00:00Z') },
+      ['goodCount']
+    )
+    assert.deepEqual(moved.map(one => one.field), ['goodCount'])
+  })
+
+  it('keeps zero apart from absent', () => {
+    const counted = changedFields({ goodCount: undefined }, { goodCount: 0 }, ['goodCount'])
+    assert.equal(counted.length, 1)
+    assert.equal(counted[0].fromValue, undefined)
+    assert.equal(counted[0].toValue, '0')
+  })
+
+  it('counts clearing a value as a change', () => {
+    const cleared = changedFields({ reason: 'jig wear' }, { reason: undefined }, ['reason'])
+    assert.equal(cleared[0].fromValue, 'jig wear')
+    assert.equal(cleared[0].toValue, undefined)
+  })
+
+  it('treats none on both sides as no change', () => {
+    assert.deepEqual(changedFields({ a: undefined }, { a: null }, ['a']), [])
+  })
+
+  it('writes times as ISO, and arrays and bags in their own shape', () => {
+    assert.equal(asText(new Date('2026-09-08T14:05:00Z')), '2026-09-08T14:05:00.000Z')
+    const moved = changedFields(
+      { equipmentNames: ['EQ-A'], materialActual: [{ definitionId: 'M1', quantity: 2 }] },
+      { equipmentNames: ['EQ-B'], materialActual: [{ definitionId: 'M1', quantity: 3 }] },
+      ['equipmentNames', 'materialActual']
+    )
+    assert.equal(moved[0].fromValue, '["EQ-A"]')
+    assert.match(moved[1].toValue!, /"quantity":3/)
+  })
+
+  it('writes nothing for a save that sends the same values again', () => {
+    const same = { goodCount: 24, status: 'completed', endTime: new Date('2026-09-08T10:00:00Z') }
+    assert.deepEqual(changedFields(same, { ...same }, ['goodCount', 'status', 'endTime']), [])
+  })
+})
+
+describe('fieldChanges', () => {
+  it('reads an empty string as no value, so clearing a blank field is no change', () => {
+    assert.deepEqual(fieldChanges({ note: '' }, { note: undefined }, ['note']), [])
+    assert.deepEqual(fieldChanges({ note: 'x' }, { note: '' }, ['note']), [{ field: 'note', fromValue: 'x', toValue: undefined }])
+  })
+
+  it('reads a missing before as nothing', () => {
+    assert.deepEqual(fieldChanges(null, { limit: 3 }, ['limit']), [{ field: 'limit', fromValue: undefined, toValue: '3' }])
+  })
+})
+
+describe('deletionChanges', () => {
+  it('turns a deleted row into one change per filled column, dates and objects as text', () => {
+    const at = new Date('2026-10-03T00:00:00.000Z')
+    assert.deepEqual(
+      deletionChanges({ name: 'HOLIDAY', description: null, appliesTo: '', fromDateTime: at, flow: { steps: [1] }, controlled: false }),
+      [
+        { field: 'name', fromValue: 'HOLIDAY' },
+        { field: 'fromDateTime', fromValue: '2026-10-03T00:00:00.000Z' },
+        { field: 'flow', fromValue: '{"steps":[1]}' },
+        { field: 'controlled', fromValue: 'false' }
+      ]
+    )
+  })
+})

package/test/resolve-ts-siblings.mjs

@@ -0,0 +1,63 @@
+/*
+ * ★ 소스 테스트가 형제 모듈을 부를 수 있게 한다 — **`.js` 로 적힌 상대 경로를 `.ts` 로 되짚는다.**
+ *
+ * ── 무엇이 서고 있었나 (2026-08-22) ─────────────────────────────────────────
+ * 이 패키지의 `npm test` 는 `node --test test/*.test.ts` 로 **소스를 그대로 실행**한다. 그런데 서버
+ * 소스는 tsc 로 빌드되는 코드이므로 상대 import 를 `'./x.js'` 로 적는다(그것이 빌드 산출물에서 맞는
+ * 경로다). 타입만 지우는 실행은 그 `.js` 를 `.ts` 로 바꿔 주지 않는다.
+ *
+ * 그래서 **소스 모듈이 형제 모듈을 값으로 참조하는 순간** 그 모듈 그래프를 부르는 테스트가 전부 선다.
+ * 실측으로 하루에 세 종류가 이 벽에 걸렸다: `identity/namespace.js`(정체성 이름공간) ·
+ * `engine/log.js`(로그 문) · `isa95-coverage.js`(적합성 판정). 늘 같은 오류다.
+ *
+ *   Cannot find module '…/server/identity/namespace.js' imported from '…/templates/wms-unit-load.ts'
+ *
+ * ── 왜 이 방식인가 ──────────────────────────────────────────────────────────
+ * 고르던 길이 둘 있었다.
+ *
+ *  ① 그 테스트들을 **빌드 산출물**(`dist-server`)로 돌린다 — 이 패키지에 전례가 있다. 그러나 테스트마다
+ *     그 배선을 적어야 하고, 걸리는 테스트가 늘 때마다 같은 일을 다시 한다. 그리고 산출물이 낡으면
+ *     **고친 코드가 아닌 것이 돌면서 초록으로 보인다.**
+ *  ② 상수를 쓰는 파일 안으로 옮긴다 — 값 참조가 사라지지만 **정본이 흩어진다.** 그것이 이 상수를 한
+ *     자리에 모은 이유와 정면으로 어긋난다.
+ *
+ * 둘 다 증상을 피하는 것이고, 원인은 **해석 규칙 하나**다. 그래서 규칙을 고친다: 상대 경로 `.js` 가
+ * 없고 같은 이름의 `.ts` 가 있으면 그것을 쓴다. 한 자리에 두므로 걸리는 테스트가 늘어도 할 일이 없다.
+ *
+ * ── 무엇을 하지 않는가 ─────────────────────────────────────────────────────
+ * **패키지 이름(`@things-factory/…`)은 손대지 않는다.** 그것은 의존 패키지의 산출물을 가리키는
+ * 것이고 실제로 `.js` 가 있다. 되짚는 것은 **상대 경로**뿐이고, 그것도 `.ts` 가 실제로 있을 때만이다 —
+ * 없으면 원래 오류가 그대로 난다(없는 것을 지어내지 않는다).
+ *
+ * ── 확장자를 아예 안 적은 것도 같다 (2026-08-30) ────────────────────────────
+ * 이 패키지의 서버 소스는 상대 경로를 확장자 없이 적는다(`'./work-window'`). 타입만 참조하는 동안에는
+ * 그 줄이 지워져 드러나지 않다가, **값을 참조하는 순간** 같은 벽에 걸린다. 규칙 하나로 둘 다 받는다.
+ */
+import { registerHooks } from 'node:module'
+import { existsSync } from 'node:fs'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+registerHooks({
+  resolve(specifier, context, nextResolve) {
+    /* 상대 경로만 본다 — 패키지 이름은 그대로 둔다. */
+    if (!specifier.startsWith('.')) return nextResolve(specifier, context)
+
+    /* `.js` 로 적혔거나 확장자가 없는 것만 되짚는다. 다른 확장자(`.json`·`.css`)는 그 뜻대로 둔다. */
+    const writtenAsJs = specifier.endsWith('.js')
+    const hasOtherExtension = !writtenAsJs && /\.[a-zA-Z0-9]+$/.test(specifier)
+    if (hasOtherExtension) return nextResolve(specifier, context)
+
+    const base = writtenAsJs ? specifier.slice(0, -3) : specifier
+
+    try {
+      return nextResolve(specifier, context)
+    } catch (err) {
+      /* 해석이 실패한 그때만 `.ts` 를 본다 — 성공하는 경로의 뜻을 바꾸지 않는다. */
+      const parent = context?.parentURL
+      if (!parent) throw err
+      const asTs = new URL(base + '.ts', parent)
+      if (!existsSync(fileURLToPath(asTs))) throw err
+      return { url: pathToFileURL(fileURLToPath(asTs)).href, shortCircuit: true, format: 'module-typescript' }
+    }
+  }
+})

package/things-factory.config.js

@@ -0,0 +1 @@
+export default {}