@operato/twin-kernel 0.11.11 → 0.11.14

package/dist/counterfactual.d.ts

@@ -26,6 +26,11 @@ export declare class TwinHistory {
 }
 export interface CounterfactualResult {
     atSimMs: number;
+    /**
+     * **실제로 돌린 만큼**이다 — 청한 만큼이 아니다(ADR-0042 ⑤). 예산에 잘리면 여기가 짧아지고,
+     * 그 사실은 소비처가 본문에 적는다. 조용히 덜 돌리고 청한 값을 적는 것이 이 칸이 막는 일이다.
+     */
+    horizonMs: number;
     withAlt: StateSnapshot;
     baseline: StateSnapshot;
     effect: StateDivergence;
@@ -35,6 +40,38 @@ export interface CounterfactualOptions {
     horizonMs: number;
     tickMs?: number;
 }
+/**
+ * 사람이 기다리는 자리에서 돌릴 때의 양보·예산 — 미리보기(ADR-0042 ⑤).
+ *
+ * 양보 간격은 호스트 예측 경로와 같은 25 틱이 기본이다. 틱마다 양보하면 양보가 비용이 되고, 라이브 틱
+ * 간격보다 길게 붙잡으면 그 사이 트윈들이 한 박자씩 밀린다(headless-twin 예측 리졸버의 실측 주석).
+ */
+export interface CounterfactualBreath {
+    /** 몇 틱마다 한 번 내주나. @default 25 */
+    every?: number;
+    /** 내주는 방법 — 보통 `setImmediate` 한 번. */
+    breathe: () => Promise<void>;
+    /** 벽시계 예산(ms). 넘으면 **두 분기를 같은 시각에서** 멈추고 `horizonMs` 에 돌린 만큼을 적는다. */
+    budgetMs?: number;
+    /** 벽시계 — 시험이 바꿔 낀다. @default performance.now */
+    now?: () => number;
+}
+/**
+ * 반사실 — **base 의 지금**에서 두 분기를 시뮬레이션해 대안의 효과를 잰다.
+ *   withAlt = base + 대안 → +H  /  baseline = base 그대로 → +H  /  effect = 둘의 발산.
+ *
+ * base 는 live 커널이어도 된다(그 경우가 ADR-0042 의 미리보기다) — fork 만 하고 base 는 건드리지 않는다.
+ * 미리보기와 「과거 T 에 그랬다면」이 **같은 몸통**을 쓰는 것이 결정 ① 이다: 미리 본 것과 적용된 것이
+ * 갈리는 날을 막는다.
+ */
+export declare function counterfactualFrom(base: CounterfactualTwin, opts: CounterfactualOptions): CounterfactualResult;
+/**
+ * 같은 반사실을 **양보하며** 돌린다 — 요청 하나 안에서 사람이 기다리는 미리보기용.
+ *
+ * 몸통은 `counterfactualFrom` 과 같다(`pairedTicks`). 다른 것은 `every` 틱마다 `breathe()` 를 기다리는 것과,
+ * `budgetMs` 를 넘으면 그 자리에서 멈추는 것뿐이다. 멈춘 사실은 `horizonMs` 가 청한 값보다 작은 것으로 드러난다.
+ */
+export declare function counterfactualFromAsync(base: CounterfactualTwin, opts: CounterfactualOptions, breath: CounterfactualBreath): Promise<CounterfactualResult>;
 /**
  * 반사실: history 의 시각 T 상태에서 두 분기를 시뮬레이션해 대안의 효과를 잰다.
  *   withAlt = T 상태 + 대안 → T+H  /  baseline = T 상태 그대로 → T+H  /  effect = 둘의 발산.

package/dist/counterfactual.js

@@ -42,6 +42,70 @@ export class TwinHistory {
         return t;
     }
 }
+const BREATH_EVERY = 25;
+const TICK_GUARD = 1_000_000;
+/**
+ * 두 분기를 **한 틱씩 번갈아** 돌린다 — 그래서 어느 순간에 멈춰도 둘은 같은 시각에 서 있고, 비교가 성립한다.
+ * 둘을 따로 끝까지 돌리면 예산에 잘릴 때 한쪽만 앞서 간다.
+ */
+function* pairedTicks(withAlt, baseline, target, step) {
+    let guard = 0;
+    while (clockOf(withAlt) < target && guard++ < TICK_GUARD) {
+        withAlt.tick(step);
+        baseline.tick(step);
+        yield guard;
+    }
+}
+/** base 에서 두 분기를 낸다. 대안은 withAlt 에만 들어간다. base 자체는 건드리지 않는다. */
+function branch(base, opts) {
+    const withAlt = base.fork();
+    opts.alternative(withAlt);
+    const baseline = base.fork();
+    return { withAlt, baseline };
+}
+function settle(atSimMs, withAlt, baseline) {
+    const a = withAlt.getSnapshot();
+    const b = baseline.getSnapshot();
+    return { atSimMs, horizonMs: Math.min(a.simClockMs, b.simClockMs) - atSimMs, withAlt: a, baseline: b, effect: compareStates(a, b) };
+}
+/**
+ * 반사실 — **base 의 지금**에서 두 분기를 시뮬레이션해 대안의 효과를 잰다.
+ *   withAlt = base + 대안 → +H  /  baseline = base 그대로 → +H  /  effect = 둘의 발산.
+ *
+ * base 는 live 커널이어도 된다(그 경우가 ADR-0042 의 미리보기다) — fork 만 하고 base 는 건드리지 않는다.
+ * 미리보기와 「과거 T 에 그랬다면」이 **같은 몸통**을 쓰는 것이 결정 ① 이다: 미리 본 것과 적용된 것이
+ * 갈리는 날을 막는다.
+ */
+export function counterfactualFrom(base, opts) {
+    const atSimMs = clockOf(base);
+    const step = opts.tickMs ?? 1000;
+    const { withAlt, baseline } = branch(base, opts);
+    for (const _ of pairedTicks(withAlt, baseline, atSimMs + opts.horizonMs, step)) {
+        /* 끝까지 — 양보 없이. 결정적이다. */
+    }
+    return settle(atSimMs, withAlt, baseline);
+}
+/**
+ * 같은 반사실을 **양보하며** 돌린다 — 요청 하나 안에서 사람이 기다리는 미리보기용.
+ *
+ * 몸통은 `counterfactualFrom` 과 같다(`pairedTicks`). 다른 것은 `every` 틱마다 `breathe()` 를 기다리는 것과,
+ * `budgetMs` 를 넘으면 그 자리에서 멈추는 것뿐이다. 멈춘 사실은 `horizonMs` 가 청한 값보다 작은 것으로 드러난다.
+ */
+export async function counterfactualFromAsync(base, opts, breath) {
+    const atSimMs = clockOf(base);
+    const step = opts.tickMs ?? 1000;
+    const every = breath.every ?? BREATH_EVERY;
+    const now = breath.now ?? (() => performance.now());
+    const started = now();
+    const { withAlt, baseline } = branch(base, opts);
+    for (const n of pairedTicks(withAlt, baseline, atSimMs + opts.horizonMs, step)) {
+        if (breath.budgetMs !== undefined && now() - started >= breath.budgetMs)
+            break;
+        if (n % every === 0)
+            await breath.breathe();
+    }
+    return settle(atSimMs, withAlt, baseline);
+}
 /**
  * 반사실: history 의 시각 T 상태에서 두 분기를 시뮬레이션해 대안의 효과를 잰다.
  *   withAlt = T 상태 + 대안 → T+H  /  baseline = T 상태 그대로 → T+H  /  effect = 둘의 발산.
@@ -50,14 +114,5 @@ export function counterfactualAt(history, atSimMs, opts) {
     const base = history.at(atSimMs);
     if (!base)
         return undefined;
-    const step = opts.tickMs ?? 1000;
-    const target = atSimMs + opts.horizonMs;
-    const withAlt = base.fork();
-    opts.alternative(withAlt);
-    const baseline = base.fork();
-    const run = (t) => { let g = 0; while (clockOf(t) < target && g++ < 1_000_000)
-        t.tick(step); };
-    run(withAlt);
-    run(baseline);
-    return { atSimMs, withAlt: withAlt.getSnapshot(), baseline: baseline.getSnapshot(), effect: compareStates(withAlt.getSnapshot(), baseline.getSnapshot()) };
+    return counterfactualFrom(base, opts);
 }

package/dist/flow-engine.d.ts

@@ -1,4 +1,4 @@
-import type { MaterialActual, TestResult, ISOTime, MaterialQuantity, WorkCalendarEntry, EffectivePeriod, Effectivity, OffCalendarReason, ResourceProperty, ResourceClassDef, MaterialDefinition, Attention, TwinModelDef, CanonicalEnvelope, Command, CommandAck, EventHandler, EquipmentMotion, AssetState, GeneratorSpec, InterventionOutcome, OrderState, PersonState, ScenarioControl, ScenarioOverride, StateSnapshot, TwinKernel, Unsubscribe, LocationState, ItemState, EquipmentState, OrderStatusDelta, TaskState, TaskStatus, StructureShift, IdentityGroundingView, IdentityDeclaration, TestSpecificationCriterion, LocationObservation } from '@operato/ops-contract';
+import type { MaterialActual, TestResult, ISOTime, MaterialQuantity, WorkCalendarEntry, EffectivePeriod, Effectivity, OffCalendarReason, ResourceProperty, ResourceClassDef, MaterialDefinition, Attention, TwinModelDef, CanonicalEnvelope, Command, CommandAck, EventHandler, EquipmentMotion, AssetState, GeneratorSpec, InterventionOutcome, OrderState, PersonState, ScenarioControl, ScenarioOverride, StateSnapshot, TwinKernel, Unsubscribe, LocationState, ItemState, EquipmentState, OrderStatusDelta, TaskState, TaskStatus, StructureShift, IdentityGroundingView, IdentityDeclaration, TestSpecificationCriterion, LocationObservation, DispositionFact } from '@operato/ops-contract';
 import { type RatedUsage, type UsedUsage } from '@operato/ops-contract';
 import type { VocabularyElement } from '@operato/ops-contract';
 import type { ReducerCheckpoint } from './observed-reducer.ts';
@@ -46,6 +46,13 @@ export interface FlowItem {
     ilmd?: Record<string, unknown>;
     /** 선언된 모든 수량 — 표준 `MaterialLot.Quantity`(복수). 관측에서 온 물품이 여러 단위를 들 수 있다. */
     quantities?: MaterialQuantity[];
+    /**
+     * 로트의 두 표준 칸 — ISA-95 `Disposition`(`nonconformance`) · `Status`(`status`). 관측 모드에서 리듀서가
+     * 앉힌 것을 `settleObserved` 가 옮기고 `itemState` 가 스냅샷에 낸다. 둘 중 하나가 빠지면 리듀서에는 있는데
+     * 화면에는 없는 칸이 된다(2026-09-16 에 둘 다 그랬다).
+     */
+    nonconformance?: DispositionFact;
+    status?: string;
 }
 /** 물리 자산 — 반복사용(팔레트·랙·용기). 설비도 물품도 아니다(GRAI vs SSCC 구분은 계약 주석 참조). */
 export interface FlowAsset extends EffectivePeriod {

package/dist/flow-engine.js

@@ -1034,7 +1034,14 @@ export class FlowEngine {
                 ...(it.subLotId ? { subLotId: it.subLotId } : {}),
                 ...(it.definitionId ? { definitionId: it.definitionId } : {}),
                 gtin: it.gtin, qty: it.qty ?? 1, uom: it.uom, ...(it.quantities?.length ? { quantities: it.quantities } : {}),
-                parent: it.parent, carriedBy: it.carriedBy, expiry: it.expiry, ilmd: it.ilmd
+                parent: it.parent, carriedBy: it.carriedBy, expiry: it.expiry, ilmd: it.ilmd,
+                /*
+                 * 로트의 두 표준 칸 — ISA-95 `Disposition`(`nonconformance`)과 `Status`(`status`). 이 복사가 칸을 하나씩
+                 * 옮기는 자리라, 여기 없는 칸은 리듀서에 앉았어도 **스냅샷에 나오지 않는다**(2026-09-16 에 `status` 를
+                 * 넣다가 `nonconformance` 도 여기서 빠져 있던 것을 찾았다 — 자리는 있고 길이 없는 부류). 있을 때만 옮긴다.
+                 */
+                ...(it.nonconformance ? { nonconformance: it.nonconformance } : {}),
+                ...(it.status ? { status: it.status } : {})
             });
         }
         for (const m of snap.equipment) {
@@ -1467,15 +1474,23 @@ export class FlowEngine {
     }
     dispatchInner(cmd) {
         const ok = () => ({ commandId: cmd.commandId, accepted: true });
-        // 거절 사유 = 언어 중립 코드 + 원시 파라미터. error 는 영어 폴백(로그·개발자용).
-        const fail = (errorCode, errorParams) => ({ commandId: cmd.commandId, accepted: false, errorCode, errorParams, error: errorCode });
+        /*
+         * 거절 사유 = 언어 중립 코드 + 원시 파라미터 + 영어 문장.
+         *
+         * `error` 는 **문장**이어야 한다 — 코드 문자열을 다시 넣지 않는다. 화면은 모르는 코드를 만나면 `error` 를
+         * 그대로 내는데(ADR-0042 ③, 매핑 표 없음), 그 자리에 코드가 들어 있으면 사람이 `kind-required` 같은 날
+         * 코드를 본다. 그리고 「무엇이 없었나」를 말하는 코드(`*-not-found`)는 그 무엇을 params 에 싣는다 — 다음에
+         * 할 일(다시 고르기)은 없었던 것의 이름을 알아야 할 수 있다.
+         */
+        const fail = (errorCode, error, errorParams) => ({ commandId: cmd.commandId, accepted: false, errorCode, errorParams, error });
+        const noEquipment = (resourceId) => fail('resource-not-found', `no equipment with id "${resourceId}" in this twin`, { resourceId });
         switch (cmd.type) {
             case CMD.orderHold:
             case CMD.orderResume: {
                 const orderId = cmd.args?.orderId;
                 const order = orderId ? this.orders.get(orderId) : undefined;
                 if (!order)
-                    return fail('order-not-found', { orderId: orderId ?? '' });
+                    return fail('order-not-found', `no order with id "${orderId ?? ''}" in this twin`, { orderId: orderId ?? '' });
                 order.held = cmd.type === CMD.orderHold;
                 this.emitOrder(order);
                 return ok();
@@ -1496,9 +1511,10 @@ export class FlowEngine {
             // Operable 코어 — 자원(설비·설비) 제어. capability-keyed(resourceId), 모든 operable 자원 공통.
             case CMD.resourceHold:
             case CMD.resourceResume: {
-                const m = this.equipment.get(cmd.args?.resourceId ?? '');
+                const resourceId = cmd.args?.resourceId ?? '';
+                const m = this.equipment.get(resourceId);
                 if (!m)
-                    return fail('resource-not-found');
+                    return noEquipment(resourceId);
                 m.held = cmd.type === CMD.resourceHold; // 계획 정지 → 배정 스킵
                 this.emitEquipment(m);
                 return ok();
@@ -1507,7 +1523,7 @@ export class FlowEngine {
                 const a = cmd.args;
                 const m = this.equipment.get(a?.resourceId ?? '');
                 if (!m)
-                    return fail('resource-not-found');
+                    return noEquipment(a?.resourceId ?? '');
                 if (m.status !== 'down') {
                     m.status = 'down'; // 비계획 고장 주입 — 기존 고장 machinery(processFailures)가 downMs 누적·수리 처리
                     m.repairUntilMs = this.clockMs + (Number(a?.durationMs) || m.mttrMs || 60_000);
@@ -1516,9 +1532,10 @@ export class FlowEngine {
                 return ok();
             }
             case CMD.resourceRepair: {
-                const m = this.equipment.get(cmd.args?.resourceId ?? '');
+                const resourceId = cmd.args?.resourceId ?? '';
+                const m = this.equipment.get(resourceId);
                 if (!m)
-                    return fail('resource-not-found');
+                    return noEquipment(resourceId);
                 if (m.status === 'down') {
                     m.status = m.taskId ? 'busy' : 'idle'; // 진행중 task 있으면 재개(고장모델 수리 로직과 동형)
                     m.repairUntilMs = undefined;
@@ -1529,9 +1546,10 @@ export class FlowEngine {
                 return ok();
             }
             case CMD.resourceResetMetrics: {
-                const m = this.equipment.get(cmd.args?.resourceId ?? '');
+                const resourceId = cmd.args?.resourceId ?? '';
+                const m = this.equipment.get(resourceId);
                 if (!m)
-                    return fail('resource-not-found');
+                    return noEquipment(resourceId);
                 m.runMs = 0;
                 m.setupMs = 0;
                 m.downMs = 0;
@@ -1547,9 +1565,9 @@ export class FlowEngine {
                 // 새 설비는 즉시 배정 대상(다음 tick). 유일 id 생성(충돌 회피). 좌표/persistence 는 호스트 몫(커널=위상만).
                 const a = cmd.args;
                 if (!a?.kind)
-                    return fail('kind-required');
+                    return fail('kind-required', 'resource.add needs args.kind');
                 if (!a?.homeLocation || !this.locations.has(a.homeLocation))
-                    return fail('home-location-not-found', { homeLocation: a?.homeLocation ?? '' });
+                    return fail('home-location-not-found', `no location "${a?.homeLocation ?? ''}" to use as home`, { homeLocation: a?.homeLocation ?? '' });
                 const count = Math.max(1, Math.min(50, Number(a.count) || 1));
                 let seq = this.equipment.size;
                 for (let i = 0; i < count; i++) {
@@ -1569,7 +1587,7 @@ export class FlowEngine {
     }
     /** 도메인 커맨드 처리(order.release 등). 기본은 거절 — 도메인이 override. */
     handleCommand(cmd) {
-        return { commandId: cmd.commandId, accepted: false, errorCode: 'unknown-command', errorParams: { type: cmd.type }, error: `unknown-command: ${cmd.type}` };
+        return { commandId: cmd.commandId, accepted: false, errorCode: 'unknown-command', errorParams: { type: cmd.type }, error: `no command of type "${cmd.type}"` };
     }
     scenario = {
         load: (def) => {
@@ -3858,7 +3876,10 @@ export class FlowEngine {
             ...(i.uom ? { uom: i.uom } : {}),
             ...(i.quantities?.length ? { quantities: i.quantities } : {}),
             ...(i.expiry !== undefined ? { expiry: i.expiry } : {}),
-            ...(i.ilmd ? { ilmd: i.ilmd } : {})
+            ...(i.ilmd ? { ilmd: i.ilmd } : {}),
+            /* 로트의 두 표준 칸(§FlowItem) — 여기서 빠지면 리듀서·엔진에는 있고 스냅샷에는 없다. */
+            ...(i.nonconformance ? { nonconformance: i.nonconformance } : {}),
+            ...(i.status ? { status: i.status } : {})
         };
     }
     /**

package/dist/observed-reducer.d.ts

@@ -12,6 +12,8 @@ interface ProjItem {
     disposition?: string;
     /** ISA-95 의 부적합 처분 — 사람이 정한 결정. 로트 전체의 사실이라 부분마다 같은 값이 앉는다. */
     nonconformance?: DispositionFact;
+    /** ISA-95 `MaterialLot.Status` — `nonconformance` 와 다른 칸(§계약 `ItemState.status`). 마지막 하나만. */
+    status?: string;
     parent?: string;
     qty?: number;
     uom?: string;

package/dist/observed-reducer.js

@@ -566,6 +566,27 @@ export class ObservedReducer {
                     part.nonconformance = { ...d };
                 break;
             }
+            case OP_EVENT.materialLot: {
+                /*
+                 * **로트 상태** — ISA-95 `MaterialLot.Status`. 출하 승인이 이 길로 온다(§계약 `OP_EVENT.materialLot`).
+                 * 처분과 같은 좁힘이다: 대상을 가리켜 들어오고, 그 이름을 가진 부분 모두에 앉는다. **물품을 지어내지
+                 * 않는다** — 모르는 로트의 상태는 `unhandled` 로 세어서 낸다.
+                 */
+                const d = e.data;
+                if (!d?.lotId || !d?.status)
+                    break;
+                if (this.stale(`material-lot:${d.lotId}`, e))
+                    return;
+                /* `lotId` 는 표준 `MaterialLotID` — 값은 로트의 식별자, 즉 여기서 `epc` 로 든 것과 같다. */
+                const parts = [...this.items.values()].filter(i => i.epc === d.lotId);
+                if (!parts.length) {
+                    this.noteUnhandled(e, `${OP_EVENT.materialLot}:unknown-lot`);
+                    break;
+                }
+                for (const part of parts)
+                    part.status = d.status;
+                break;
+            }
             case OP_EVENT.observation: {
                 /*
                  * **자리의 물리 관측** — 속성마다 마지막 값 하나만 든다(§`LocationState.observations`).

package/dist-cjs/index.cjs

@@ -40,6 +40,8 @@ __export(index_exports, {
   compareStates: () => compareStates,
   constantDuration: () => constantDuration,
   counterfactualAt: () => counterfactualAt,
+  counterfactualFrom: () => counterfactualFrom,
+  counterfactualFromAsync: () => counterfactualFromAsync,
   demandWindowStart: () => demandWindowStart,
   deriveAttentions: () => deriveAttentions,
   electricityCost: () => electricityCost,
@@ -650,6 +652,23 @@ var OP_EVENT = {
    * 이것은 **결정**이다. 누가·언제·왜 그렇게 정했는지의 자리는 그쪽에 없다.
    */
   disposition: "nonconformance.disposition",
+  /**
+   * **로트 상태** — ISA-95 `MaterialLot.Status`(B2MML-Material.xsd). 「이 로트가 지금 어떤 것이냐」의 결정.
+   *
+   * ── `nonconformance.disposition` 과 다른 사실이다 (2026-09-16) ──────────────
+   * 그것은 표준 `Disposition` — **부적합을 어떻게 처리하나**(재작업·특채·폐기). 이것은 표준 `Status` — 적합한
+   * 로트에도 붙는 상태(released · quarantine · on-hold …). 출하 승인(batch release)이 이 축이다. 처분에 실으면
+   * 정상 출하가 전부 부적합 이력이 된다 — 진짜 term 을 틀린 뜻으로 쓰는 것이 자리가 없는 것보다 나쁘다.
+   *
+   * ── 낱말은 열려 있다 ──────────────────────────────────────────────────────
+   * 오더 상태와 같은 규율 — 커널이 이 낱말로 무엇을 계산하지 않으므로 닫을 근거가 없다. 도메인이 소유한다.
+   *
+   * ── 출발과 다른 사실이다 ─────────────────────────────────────────────────
+   * 승인은 자재를 움직이지 않는다. 자재가 트윈 밖으로 나가는 것은 EPCIS `shipping` 사건이다. 둘을 한 사건으로
+   * 접지 않는다 — 승인됐는데 안 나간 배치가 트윈이 보여야 할 상태다.
+   */
+  materialLot: "material-lot.status",
+  // 레코드: { lotId(표준 MaterialLotID = ItemState.epc 의 값), status, decidedBy?, reason?, decidedAt? }
   /**
    * **이 목록이 전부다** — 연결된 시스템이 현재 목록을 한 바퀴 다 보낸 뒤 그것을 알린다.
    *
@@ -2038,6 +2057,23 @@ var SPECS = {
     },
     enums: { decision: DISPOSITION_DECISION }
   },
+  /*
+   * **로트 상태** — ISA-95 `MaterialLot.Status`. 출하 승인(batch release)이 들어오는 문(§`OP_EVENT.materialLot`).
+   *
+   * `disposition`(subjectId + decision) 과 필드가 겹치지 않는다 — 여기는 `lotId` + `status`. 정체 이름이 표준
+   * `MaterialLotID` 인 이유가 하나 더 있다: 이 문은 `epc` 를 든 레코드를 EPCIS 어휘로 보고 받지 않는다
+   * (§`operationalKindOf`). 값은 로트의 식별자(`ItemState.epc` 와 같은 값)다. 상태 낱말은 열려 있어 enum 이
+   * 없다(오더 상태와 같은 규율). 로트 전체의 사실이므로 부분(`subLotId`)은 받지 않는다 — 부분마다 다른 상태가
+   * 필요해지면 그것은 다른 사실이다.
+   */
+  "material-lot": {
+    eventType: OP_EVENT.materialLot,
+    match: ["lotId", "status"],
+    matchOrder: 85,
+    identity: "lotId",
+    required: ["lotId", "status"],
+    fields: { lotId: "string", status: "string", decidedBy: "string", reason: "string", decidedAt: "string", recordTime: "string" }
+  },
   test: {
     eventType: OP_EVENT.test,
     match: ["testableObjectId"],
@@ -2190,11 +2226,11 @@ function computeOee(c, nowMs) {
     missing.push("planned-run-time-per-item");
   else if (c.runMs <= 0)
     missing.push("actual-production-time");
-  const performance = c.plannedRunTimePerItemMs != null && c.runMs > 0 ? Math.min(1, c.plannedRunTimePerItemMs * produced / c.runMs) : void 0;
-  const overall = availability != null && performance != null && quality != null ? availability * performance * quality : void 0;
+  const performance2 = c.plannedRunTimePerItemMs != null && c.runMs > 0 ? Math.min(1, c.plannedRunTimePerItemMs * produced / c.runMs) : void 0;
+  const overall = availability != null && performance2 != null && quality != null ? availability * performance2 * quality : void 0;
   return {
     ...availability != null ? { availability } : {},
-    ...performance != null ? { performance } : {},
+    ...performance2 != null ? { performance: performance2 } : {},
     ...quality != null ? { quality } : {},
     ...overall != null ? { overall } : {},
     ...missing.length ? { missing } : {},
@@ -2258,21 +2294,52 @@ var TwinHistory = class {
     return t;
   }
 };
-function counterfactualAt(history, atSimMs, opts) {
-  const base = history.at(atSimMs);
-  if (!base) return void 0;
-  const step = opts.tickMs ?? 1e3;
-  const target = atSimMs + opts.horizonMs;
+var BREATH_EVERY = 25;
+var TICK_GUARD = 1e6;
+function* pairedTicks(withAlt, baseline, target, step) {
+  let guard = 0;
+  while (clockOf(withAlt) < target && guard++ < TICK_GUARD) {
+    withAlt.tick(step);
+    baseline.tick(step);
+    yield guard;
+  }
+}
+function branch(base, opts) {
   const withAlt = base.fork();
   opts.alternative(withAlt);
   const baseline = base.fork();
-  const run = (t) => {
-    let g = 0;
-    while (clockOf(t) < target && g++ < 1e6) t.tick(step);
-  };
-  run(withAlt);
-  run(baseline);
-  return { atSimMs, withAlt: withAlt.getSnapshot(), baseline: baseline.getSnapshot(), effect: compareStates(withAlt.getSnapshot(), baseline.getSnapshot()) };
+  return { withAlt, baseline };
+}
+function settle(atSimMs, withAlt, baseline) {
+  const a = withAlt.getSnapshot();
+  const b = baseline.getSnapshot();
+  return { atSimMs, horizonMs: Math.min(a.simClockMs, b.simClockMs) - atSimMs, withAlt: a, baseline: b, effect: compareStates(a, b) };
+}
+function counterfactualFrom(base, opts) {
+  const atSimMs = clockOf(base);
+  const step = opts.tickMs ?? 1e3;
+  const { withAlt, baseline } = branch(base, opts);
+  for (const _ of pairedTicks(withAlt, baseline, atSimMs + opts.horizonMs, step)) {
+  }
+  return settle(atSimMs, withAlt, baseline);
+}
+async function counterfactualFromAsync(base, opts, breath) {
+  const atSimMs = clockOf(base);
+  const step = opts.tickMs ?? 1e3;
+  const every = breath.every ?? BREATH_EVERY;
+  const now = breath.now ?? (() => performance.now());
+  const started = now();
+  const { withAlt, baseline } = branch(base, opts);
+  for (const n of pairedTicks(withAlt, baseline, atSimMs + opts.horizonMs, step)) {
+    if (breath.budgetMs !== void 0 && now() - started >= breath.budgetMs) break;
+    if (n % every === 0) await breath.breathe();
+  }
+  return settle(atSimMs, withAlt, baseline);
+}
+function counterfactualAt(history, atSimMs, opts) {
+  const base = history.at(atSimMs);
+  if (!base) return void 0;
+  return counterfactualFrom(base, opts);
 }
 
 // src/forecast.ts
@@ -2849,6 +2916,18 @@ var ObservedReducer = class {
         for (const part of parts) part.nonconformance = { ...d };
         break;
       }
+      case OP_EVENT.materialLot: {
+        const d = e.data;
+        if (!d?.lotId || !d?.status) break;
+        if (this.stale(`material-lot:${d.lotId}`, e)) return;
+        const parts = [...this.items.values()].filter((i) => i.epc === d.lotId);
+        if (!parts.length) {
+          this.noteUnhandled(e, `${OP_EVENT.materialLot}:unknown-lot`);
+          break;
+        }
+        for (const part of parts) part.status = d.status;
+        break;
+      }
       case OP_EVENT.observation: {
         const d = e.data;
         if (!d?.locationId || !d?.propertyId) break;
@@ -4285,7 +4364,14 @@ var FlowEngine = class {
         parent: it.parent,
         carriedBy: it.carriedBy,
         expiry: it.expiry,
-        ilmd: it.ilmd
+        ilmd: it.ilmd,
+        /*
+         * 로트의 두 표준 칸 — ISA-95 `Disposition`(`nonconformance`)과 `Status`(`status`). 이 복사가 칸을 하나씩
+         * 옮기는 자리라, 여기 없는 칸은 리듀서에 앉았어도 **스냅샷에 나오지 않는다**(2026-09-16 에 `status` 를
+         * 넣다가 `nonconformance` 도 여기서 빠져 있던 것을 찾았다 — 자리는 있고 길이 없는 부류). 있을 때만 옮긴다.
+         */
+        ...it.nonconformance ? { nonconformance: it.nonconformance } : {},
+        ...it.status ? { status: it.status } : {}
       });
     }
     for (const m of snap.equipment) {
@@ -4616,13 +4702,14 @@ var FlowEngine = class {
   }
   dispatchInner(cmd) {
     const ok = () => ({ commandId: cmd.commandId, accepted: true });
-    const fail = (errorCode, errorParams) => ({ commandId: cmd.commandId, accepted: false, errorCode, errorParams, error: errorCode });
+    const fail = (errorCode, error, errorParams) => ({ commandId: cmd.commandId, accepted: false, errorCode, errorParams, error });
+    const noEquipment = (resourceId) => fail("resource-not-found", `no equipment with id "${resourceId}" in this twin`, { resourceId });
     switch (cmd.type) {
       case CMD.orderHold:
       case CMD.orderResume: {
         const orderId = cmd.args?.orderId;
         const order = orderId ? this.orders.get(orderId) : void 0;
-        if (!order) return fail("order-not-found", { orderId: orderId ?? "" });
+        if (!order) return fail("order-not-found", `no order with id "${orderId ?? ""}" in this twin`, { orderId: orderId ?? "" });
         order.held = cmd.type === CMD.orderHold;
         this.emitOrder(order);
         return ok();
@@ -4638,8 +4725,9 @@ var FlowEngine = class {
       // Operable 코어 — 자원(설비·설비) 제어. capability-keyed(resourceId), 모든 operable 자원 공통.
       case CMD.resourceHold:
       case CMD.resourceResume: {
-        const m = this.equipment.get(cmd.args?.resourceId ?? "");
-        if (!m) return fail("resource-not-found");
+        const resourceId = cmd.args?.resourceId ?? "";
+        const m = this.equipment.get(resourceId);
+        if (!m) return noEquipment(resourceId);
         m.held = cmd.type === CMD.resourceHold;
         this.emitEquipment(m);
         return ok();
@@ -4647,7 +4735,7 @@ var FlowEngine = class {
       case CMD.resourceDown: {
         const a = cmd.args;
         const m = this.equipment.get(a?.resourceId ?? "");
-        if (!m) return fail("resource-not-found");
+        if (!m) return noEquipment(a?.resourceId ?? "");
         if (m.status !== "down") {
           m.status = "down";
           m.repairUntilMs = this.clockMs + (Number(a?.durationMs) || m.mttrMs || 6e4);
@@ -4656,8 +4744,9 @@ var FlowEngine = class {
         return ok();
       }
       case CMD.resourceRepair: {
-        const m = this.equipment.get(cmd.args?.resourceId ?? "");
-        if (!m) return fail("resource-not-found");
+        const resourceId = cmd.args?.resourceId ?? "";
+        const m = this.equipment.get(resourceId);
+        if (!m) return noEquipment(resourceId);
         if (m.status === "down") {
           m.status = m.taskId ? "busy" : "idle";
           m.repairUntilMs = void 0;
@@ -4667,8 +4756,9 @@ var FlowEngine = class {
         return ok();
       }
       case CMD.resourceResetMetrics: {
-        const m = this.equipment.get(cmd.args?.resourceId ?? "");
-        if (!m) return fail("resource-not-found");
+        const resourceId = cmd.args?.resourceId ?? "";
+        const m = this.equipment.get(resourceId);
+        if (!m) return noEquipment(resourceId);
         m.runMs = 0;
         m.setupMs = 0;
         m.downMs = 0;
@@ -4681,8 +4771,8 @@ var FlowEngine = class {
       }
       case CMD.resourceAdd: {
         const a = cmd.args;
-        if (!a?.kind) return fail("kind-required");
-        if (!a?.homeLocation || !this.locations.has(a.homeLocation)) return fail("home-location-not-found", { homeLocation: a?.homeLocation ?? "" });
+        if (!a?.kind) return fail("kind-required", "resource.add needs args.kind");
+        if (!a?.homeLocation || !this.locations.has(a.homeLocation)) return fail("home-location-not-found", `no location "${a?.homeLocation ?? ""}" to use as home`, { homeLocation: a?.homeLocation ?? "" });
         const count = Math.max(1, Math.min(50, Number(a.count) || 1));
         let seq = this.equipment.size;
         for (let i = 0; i < count; i++) {
@@ -4700,7 +4790,7 @@ var FlowEngine = class {
   }
   /** 도메인 커맨드 처리(order.release 등). 기본은 거절 — 도메인이 override. */
   handleCommand(cmd) {
-    return { commandId: cmd.commandId, accepted: false, errorCode: "unknown-command", errorParams: { type: cmd.type }, error: `unknown-command: ${cmd.type}` };
+    return { commandId: cmd.commandId, accepted: false, errorCode: "unknown-command", errorParams: { type: cmd.type }, error: `no command of type "${cmd.type}"` };
   }
   scenario = {
     load: (def) => {
@@ -6688,7 +6778,10 @@ var FlowEngine = class {
       ...i.uom ? { uom: i.uom } : {},
       ...i.quantities?.length ? { quantities: i.quantities } : {},
       ...i.expiry !== void 0 ? { expiry: i.expiry } : {},
-      ...i.ilmd ? { ilmd: i.ilmd } : {}
+      ...i.ilmd ? { ilmd: i.ilmd } : {},
+      /* 로트의 두 표준 칸(§FlowItem) — 여기서 빠지면 리듀서·엔진에는 있고 스냅샷에는 없다. */
+      ...i.nonconformance ? { nonconformance: i.nonconformance } : {},
+      ...i.status ? { status: i.status } : {}
     };
   }
   /**
@@ -9858,6 +9951,8 @@ function electricityCost(input) {
   compareStates,
   constantDuration,
   counterfactualAt,
+  counterfactualFrom,
+  counterfactualFromAsync,
   demandWindowStart,
   deriveAttentions,
   electricityCost,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/twin-kernel",
-  "version": "0.11.11",
+  "version": "0.11.14",
   "type": "module",
   "description": "Twin Domain Kernel — framework-agnostic, zero-dep (domain + sim + 3-channel contract). WMS/YMS/MES, EPCIS 2.0 · ISA-95.",
   "publishConfig": {
@@ -28,6 +28,6 @@
     "test": "node --test test/*.test.ts"
   },
   "dependencies": {
-    "@operato/ops-contract": "^0.9.19"
+    "@operato/ops-contract": "^0.9.22"
   }
 }