@operato/ops-contract 0.9.15 → 0.9.17

package/dist/contract.d.ts

@@ -31,6 +31,75 @@ export interface CanonicalEnvelope<T = unknown> {
      * 표준 자리이고, EPCIS 핵심에는 없어 확장으로 갑니다.
      */
     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.**
+     *
+     * ```
+     * 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
+     * ```
+     *
+     * 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.15",
+  "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",