@operato/ops-contract 0.9.16 → 0.9.17

package/dist/contract.d.ts

@@ -32,38 +32,72 @@ export interface CanonicalEnvelope<T = unknown> {
      */
     description?: string;
     /**
-     * **이 사실이 실제로 일어난 것인가** — 보내는 쪽만 답할 수 있다.
+     * **Whether this fact actually happened** — only the sending side can answer.
+     *
+     * ── Why this exists (measured 2026-09-09) ─────────────────────────────────
+     * The twin's journal held 1,134 rows, every one of them produced by a generator, and nothing
+     * in it said so. The screens compute yield and utilisation from those rows and had no way to
+     * mention it.
+     *
+     * The only signal was the sender's naming convention — `SIM-`, `WO-SIM-` — and the column that
+     * convention reaches was empty on half the rows: **558 of 1,134 were recognisable.** A
+     * convention belongs to whoever writes it, and a receiver that depends on one is wrong the day
+     * it changes.
+     *
+     * ── Why the twin does not judge this itself ───────────────────────────────
+     * **It has nothing to judge from.** A generator arrives through the same door, in the same
+     * shape, as a real system. What the twin knows is which connection a fact came through;
+     * whether that connection reads a factory or invents one is knowable only at that end.
+     *
+     * So this is a declaration: the side that invents says it invents.
+     *
+     * ── Absent is not `actual` ────────────────────────────────────────────────
+     * Empty means **not declared**, which is not "it happened". Reading the two as the same thing
+     * is the defect: a generator that omits the field has its output counted as production, and
+     * nothing says so.
+     *
+     * Nor is every real source required to declare `actual` — that adds a line to each connector
+     * and makes the ones that forget look fabricated. **Only the exception is declared**, and a
+     * reader distinguishes three states: declared simulated, declared actual, not declared.
+     *
+     * ── The kernel does not decide anything on this ───────────────────────────
+     * It carries it. Whether performance figures exclude simulated facts is **the reader's**
+     * decision; excluding them in the kernel would erase the answer of whoever ran a simulation
+     * to predict something.
+     *
+     * ── Why the envelope ──────────────────────────────────────────────────────
+     * The same reason as `description` — it is a fact **about a past event**, not about current
+     * state. And it does not go inside the EPCIS event: the standard has no such field, and
+     * inventing a name in there would take that event outside the standard. The envelope is ours,
+     * and the journal keeps the envelope as it arrived.
+     *
+     * ── ⚠ Do not put lineage in this field ───────────────────────────────────
+     * `provenance` normally means a chain. In art it is the record of ownership; in computing it
+     * is the record of **who, which system, and which activity produced a piece of data**
+     * (W3C PROV). The word was chosen because its purpose matches this one: telling the genuine
+     * from the forged.
+     *
+     * **But this field is one bit of that chain** — it answers "did it happen" and nothing else.
+     * The name promises a chain and hands over a flag, which leaves exactly one risk: that someone
+     * later reasons "it is called provenance, so the lineage goes here". Then this field becomes
+     * the home of a different concept, and code already splitting performance figures on it
+     * receives a value whose shape changed (ADR-0041 — a name fitting is not the same as a place
+     * fitting).
+     *
+     * So do not widen it. **Open a new place.**
      *
-     * ── 왜 필요한가 (2026-09-09 실측) ─────────────────────────────────────────
-     * 트윈 저널 1,134건이 전부 발생기가 만든 실적이었고, **저널에 그렇다고 말하는 자리가 없었다.**
-     * 화면의 성과·수율·가동률이 그 수로 계산되는데, 화면이 그 사실을 말할 방법이 없다.
-     *
-     * 가릴 수 있는 단서가 이름 규약뿐이었다 — 발생기가 `SIM-`·`WO-SIM-` 을 붙인다. 그런데 그 규약이
-     * 닿는 칸(`order_id`)이 절반은 비어 있어서 **1,134 중 558 만 갈렸다.** 규약은 보내는 쪽의 것이고,
-     * 받는 쪽이 그것에 기대면 규약이 바뀌는 날 조용히 틀린다.
-     *
-     * ── 왜 트윈이 스스로 판정하지 않나 ────────────────────────────────────────
-     * **판정할 근거가 없다.** 발생기는 실 시스템과 같은 문으로, 같은 모양으로 보낸다. 트윈이 아는 것은
-     * 「어느 연결로 들어왔나」까지이고, 그 연결이 실 공장을 읽는지 지어내는지는 그쪽만 안다.
-     *
-     * 그래서 이 값은 **선언**이다. 지어내는 쪽이 지어낸다고 말한다.
-     *
-     * ── 없음은 `actual` 이 아니다 ─────────────────────────────────────────────
-     * 비어 있으면 **선언되지 않았다**는 뜻이고, 「실제로 일어났다」가 아니다. 둘을 같게 읽으면 발생기가
-     * 이 칸을 잊는 순간 그 수가 실적으로 계산되고, 아무것도 그렇다고 말하지 않는다.
-     *
-     * 모든 실 원본에 `actual` 을 요구하지도 않는다 — 그러면 붙는 쪽마다 한 줄이 늘고, 잊은 곳이
-     * 「지어낸 것」으로 보인다. **선언하는 것은 예외뿐**이고, 읽는 쪽은 셋을 구별해 말한다:
-     * 지어낸 것 · 실제라고 선언된 것 · 선언되지 않은 것.
-     *
-     * ── 커널은 이 값으로 판단하지 않는다 ──────────────────────────────────────
-     * 나르기만 한다. 성과 계산에서 지어낸 것을 뺄지는 **읽는 쪽의 결정**이고, 커널이 미리 빼면
-     * 시뮬레이션으로 무엇을 예측하려던 사람의 답이 사라진다.
+     * ```
+     * did it happen                      this field
+     * which connection did it arrive on  a separate place — none yet; the twin knows this, it is
+     *                                    not a declaration
+     * when did we learn it (late?)       a separate axis — that is backfill, and a backfilled
+     *                                    fact is not simulated
+     * is the value correct               a separate axis — `rejected` and `errors` answer it
+     * ```
      *
-     * ── 왜 봉투인가 ───────────────────────────────────────────────────────────
-     * `description` 과 같은 이유다 — **지난 사건에 대한 사실**이고 지금 상태에 대한 사실이 아니다.
-     * 그리고 EPCIS 사건 안에 넣지 않는다: 표준에 그 칸이 없고, 이름을 지어 넣으면 그 사건이 표준을
-     * 벗어난다. 봉투는 우리 것이고, 지난 기록에는 봉투가 그대로 남는다.
+     * Adding a value follows the same discipline. If a third one seems necessary, ask first
+     * whether it answers "did it happen" — usually it does not, and then it is one of the rows
+     * above.
      */
     provenance?: 'actual' | 'simulated';
     data: T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/ops-contract",
-  "version": "0.9.16",
+  "version": "0.9.17",
   "description": "Operations domain contract — the standard vocabulary that producers and readers agree on (EPCIS 2.0/GS1, ISA-95, IEC 61850/ISO 50001). Types, guards, validation. No state, no engine.",
   "type": "module",
   "main": "./dist-cjs/index.cjs",