@operato/twin-kernel 0.6.6 → 0.6.7

package/dist/contract.d.ts

@@ -216,6 +216,45 @@ export declare function testPassedAt(r: TestResult, at?: ISOTime): boolean;
  * 없는 것으로 막지 않는다). 결과가 있으면 그것이 유효한 합격이어야 한다.
  */
 export declare function meetsTests(required: readonly string[], results: readonly TestResult[] | undefined, at?: ISOTime): boolean;
+/**
+ * 자원이 **지금 쓰일 수 있나, 아니면 왜 못 쓰이나** — ISA-95 `PersonnelCapability`/`EquipmentCapability`.
+ *
+ * ── 왜 계약이 이것을 소유해야 하나 ────────────────────────────────────────────
+ * 커널은 배정할 때 이미 이 판정을 한다(교대·고장·보류·유효기간·시험 만료). 그런데 그 규칙이 **엔진 안의
+ * 필터 조건으로만** 있어서, 화면은 같은 판정을 자기 코드로 다시 만들었다(`reasonOf`). 규칙이 두 벌이면
+ * 반드시 갈라진다 — 배정은 막는데 화면은 "가용" 이라 말하는 순간이 온다. 그 어긋남은 조용하다.
+ *
+ * 그래서 **이유까지 계약이 낸다.** 화면·예측·AI 가 같은 낱말로 말하고, 새 이유가 생기면(시험 만료가
+ * 그랬다) 한 곳만 늘어난다.
+ *
+ * ── 이유의 순서가 뜻이다 ──────────────────────────────────────────────────────
+ * 여러 이유가 겹칠 수 있다(폐기한 설비가 고장 상태로 남아 있는 것). **먼저 오는 것을 답한다** —
+ * "이미 모델 밖" 이 "고장" 보다 앞선다(폐기한 설비의 고장은 고칠 일이 아니다).
+ */
+export type CapabilityReason = 
+/** 유효기간 전 — 아직 없는 자원(도입 예정). 기다릴 일이다. */
+'not-yet'
+/** 유효기간 후 — 이미 없는 자원(폐기·퇴사). 지울 일이다. */
+ | 'retired'
+/** 사람이 막았다(`held`) — 지시로 보류. */
+ | 'held'
+/** 고장 — 설비만. 고칠 일이다. */
+ | 'down'
+/** 근무·가동 시간 밖(교대 사이) — 기다리면 돌아온다. */
+ | 'off-shift'
+/** 근무일이 아니다(휴일) — 하루 통째로 쉰다. `off-shift` 와 기다릴 시간이 다르다. */
+ | 'resting'
+/** 요구된 시험의 결과가 만료·불합격 — 자격이 성립하지 않는다(§TestResult). */
+ | 'test-expired'
+/** 지금 다른 일을 하고 있다 — 능력은 있고 여유가 없다. */
+ | 'working'
+/** 쓸 수 있다. */
+ | 'available';
+/** 가용 여부와 그 이유 — `available` 이면 `reason: 'available'`. */
+export interface Capability {
+    available: boolean;
+    reason: CapabilityReason;
+}
 export interface TestSpecification {
     /** 표준 `ID` — 자원의 `testSpecificationIds` 가 이 값을 가리킨다. */
     id: string;
@@ -578,6 +617,28 @@ export declare function offCalendarAt(r: {
     };
     workCalendar?: WorkCalendarEntry[];
 }, ms: number, utcOffsetMinutes?: number): boolean;
+/**
+ * 자원의 **가용 능력을 판정한다** — 하나의 규칙, 하나의 자리.
+ *
+ * 부르는 쪽이 시각과 시간대를 준다(커널은 `now()`·`utcOffsetMinutes`, 호스트는 관측 시각). 주지 않으면
+ * 시각에 달린 판정(유효기간·교대·시험 만료)은 **하지 않는다** — 모르면 판단하지 않는다는 규율이다.
+ *
+ * `requiredTests` 는 부르는 쪽이 등급에서 모아 넘긴다(등급 정의를 아는 것은 부르는 쪽이다).
+ */
+export declare function capabilityOf(r: {
+    status?: string;
+    held?: boolean;
+    window?: {
+        startHour: number;
+        endHour: number;
+    };
+    workCalendar?: WorkCalendarEntry[];
+    testResults?: TestResult[];
+} & EffectivePeriod, ctx?: {
+    at?: ISOTime;
+    utcOffsetMinutes?: number;
+    requiredTests?: readonly string[];
+}): Capability;
 export interface LocationState {
     id: string;
     type: string;

package/dist/contract.js

@@ -517,6 +517,43 @@ export function offCalendarAt(r, ms, utcOffsetMinutes) {
     const h = Math.floor(minute / 60);
     return !(w.startHour <= w.endHour ? h >= w.startHour && h < w.endHour : h >= w.startHour || h < w.endHour);
 }
+/**
+ * 자원의 **가용 능력을 판정한다** — 하나의 규칙, 하나의 자리.
+ *
+ * 부르는 쪽이 시각과 시간대를 준다(커널은 `now()`·`utcOffsetMinutes`, 호스트는 관측 시각). 주지 않으면
+ * 시각에 달린 판정(유효기간·교대·시험 만료)은 **하지 않는다** — 모르면 판단하지 않는다는 규율이다.
+ *
+ * `requiredTests` 는 부르는 쪽이 등급에서 모아 넘긴다(등급 정의를 아는 것은 부르는 쪽이다).
+ */
+export function capabilityOf(r, ctx) {
+    const at = ctx?.at;
+    /* 순서가 뜻이다 — "이미 모델 밖" 이 "고장" 보다 앞선다(폐기한 설비의 고장은 고칠 일이 아니다). */
+    const eff = effectivityAt(r, at);
+    if (eff === 'not-yet')
+        return { available: false, reason: 'not-yet' };
+    if (eff === 'expired')
+        return { available: false, reason: 'retired' };
+    if (r.held)
+        return { available: false, reason: 'held' };
+    if (r.status === 'down')
+        return { available: false, reason: 'down' };
+    if (at) {
+        const ms = Date.parse(at);
+        if (Number.isFinite(ms)) {
+            const why = offCalendarReasonAt(r, ms, ctx?.utcOffsetMinutes);
+            if (why === 'non-working')
+                return { available: false, reason: 'resting' };
+            if (why === 'off-hours')
+                return { available: false, reason: 'off-shift' };
+        }
+    }
+    /* 자격은 **결과가 선언됐을 때만** 제약이다(§meetsTests) — 없는 것으로 막으면 라인이 굶는다. */
+    if (ctx?.requiredTests?.length && !meetsTests(ctx.requiredTests, r.testResults, at))
+        return { available: false, reason: 'test-expired' };
+    if (r.status && r.status !== 'idle' && r.status !== 'available')
+        return { available: false, reason: 'working' };
+    return { available: true, reason: 'available' };
+}
 // ── 운영 델타(비-EPCIS) — State 채널의 나머지 절반 ──────────────────────────
 // EPCIS 이벤트는 재고/위치만 재구성 가능. tasks·equipment·orders 의 운영 상태는
 // 이 델타로 미러한다. envelope.eventType = 'task.status' | 'equipment.status' | 'order.status'.

package/dist/flow-engine.d.ts

@@ -809,7 +809,12 @@ export declare abstract class FlowEngine implements TwinKernel {
      * 판정 규칙은 계약이 소유한다(`meetsTests`) — 여기서 다시 적으면 규칙이 두 곳이 되고, 한쪽이 만료를
      * 조용히 통과시킨다.
      */
-    private qualifiedByTests;
+    /**
+     * 이 사람이 속한 등급들이 **요구하는 시험 목록** — 판정은 계약이 한다(`capabilityOf`).
+     *
+     * 상속을 타고 닫은 등급 전부의 요구를 모은다: 상위 등급이 요구하는 시험도 자격의 조건이다.
+     */
+    private requiredTestsOf;
     private claimPersonnel;
     /**
      * 필요 설비를 고른다 — **인원·자산과 같은 규칙**(등급으로 요구, 부분 확보 없이 전량 아니면 대기).

package/dist/flow-engine.js

@@ -9,7 +9,7 @@
  * 통합 타입은 도메인 필드를 옵셔널로 넓혀(FlowItem.gtin?, FlowOrder.shipmentEpc? 등) 두 도메인을 담는다.
  * (roadmap Phase5 발견 → 추출. [[project_flow_single_base_vision]] FlowLocation 단일 base 방향과 정합.)
  */
-import { OP_EVENT, CMD, locationStatusOf, readBoardEquipment, readBoardLocations, readBoardAssets, classClosure, meetsTests, priorityRank, dueStatusOf, effectivityAt, offCalendarAt, offCalendarReasonAt, minuteOfDayAt, activeShiftAt, subLotIdOf, itemKeyOf } from "./contract.js";
+import { OP_EVENT, CMD, locationStatusOf, readBoardEquipment, readBoardLocations, readBoardAssets, classClosure, capabilityOf, priorityRank, dueStatusOf, effectivityAt, offCalendarAt, offCalendarReasonAt, minuteOfDayAt, activeShiftAt, subLotIdOf, itemKeyOf } from "./contract.js";
 import { ObservedReducer } from "./observed-reducer.js";
 import { transformationEvent, aggregationEvent, objectEvent, parseEpc, DISP, ILMD_ATTR, CBV_BIZSTEP } from "./epcis.js";
 import { parseIsoDuration } from "./iso-duration.js";
@@ -1854,16 +1854,21 @@ export class FlowEngine {
      * 판정 규칙은 계약이 소유한다(`meetsTests`) — 여기서 다시 적으면 규칙이 두 곳이 되고, 한쪽이 만료를
      * 조용히 통과시킨다.
      */
-    qualifiedByTests(p) {
+    /**
+     * 이 사람이 속한 등급들이 **요구하는 시험 목록** — 판정은 계약이 한다(`capabilityOf`).
+     *
+     * 상속을 타고 닫은 등급 전부의 요구를 모은다: 상위 등급이 요구하는 시험도 자격의 조건이다.
+     */
+    requiredTestsOf(p) {
         const defs = this.classDefs.personnel;
         if (!defs?.length)
-            return true;
+            return [];
         const closure = classClosure(p.personnelClassIds, defs, this.now());
         const required = [];
         for (const d of defs)
             if (closure.has(d.id))
                 required.push(...(d.testSpecificationIds ?? []));
-        return meetsTests(required, p.testResults, this.now());
+        return required;
     }
     claimPersonnel(t) {
         const need = this.operationSpecs.get(t.kind)?.personnelSpecification;
@@ -1874,24 +1879,23 @@ export class FlowEngine {
             const want = Math.max(0, Math.floor(req.quantity ?? 0));
             if (!want)
                 continue;
-            const avail = [...this.persons.values()].filter(p => p.status === 'idle' &&
-                !picked.includes(p.id) &&
-                !this.personOffShift(p) &&
-                !this.outOfEffect(p) && // 입사 전·퇴사 후는 이 시각의 모델에 없다
-                /* 자격은 **상속을 타고 닫아** 판정한다 — 사람은 여러 등급에 속할 수 있고(표준), 등급은
-                   다른 등급을 상속한다. "생산직 2명" 요구를 "용접 자격자" 가 만족해야 한다.
-                   유효기간 밖의 등급은 닫힘에서 빠진다(만료된 자격으로 배정되지 않는다). */
-                (req.personnelClass === undefined ||
-                    classClosure(p.personnelClassIds, this.classDefs.personnel, this.now()).has(req.personnelClass)) &&
+            const avail = [...this.persons.values()].filter(p => !picked.includes(p.id) &&
                 /*
-                 * **요구된 시험을 만족하나** — 등급이 요구하고(`testSpecificationIds`) 사람이 결과를 든다
-                 * (`testResults`). 만료·불합격이면 그 자격은 성립하지 않는다.
+                 * **판정은 한 벌이다**(`capabilityOf`). 예전에는 이 자리에 조건을 늘어놓았고 화면은 같은
+                 * 판정을 자기 코드로 다시 만들었다 — 규칙이 두 벌이면 갈라지고, 배정은 막는데 화면은
+                 * "가용" 이라 말하는 순간이 온다(그 어긋남은 조용하다).
                  *
-                 * 결과가 **아예 없으면 막지 않는다**: 없는 것으로 막으면 자격자가 전부 사라져 라인이 영구히
-                 * 굶고, 원본이 결과를 주지 않는 현장에서는 그 제약이 선언되지 않은 것이다("선언한 것만
-                 * 제약이 된다" — 이 커널의 규율).
+                 * 요구된 시험은 등급에서 모아 넘긴다 — 등급 정의를 아는 것은 이쪽이다.
                  */
-                this.qualifiedByTests(p));
+                capabilityOf(p, {
+                    at: this.now(),
+                    utcOffsetMinutes: this.boardDef?.utcOffsetMinutes,
+                    requiredTests: this.requiredTestsOf(p)
+                }).available &&
+                /* 자격은 **상속을 타고 닫아** 판정한다 — 사람은 여러 등급에 속할 수 있고(표준), 등급은
+                   다른 등급을 상속한다. "생산직 2명" 요구를 "용접 자격자" 가 만족해야 한다. */
+                (req.personnelClass === undefined ||
+                    classClosure(p.personnelClassIds, this.classDefs.personnel, this.now()).has(req.personnelClass)));
             if (avail.length < want)
                 return null; // 한 등급이라도 모자라면 시작하지 않는다
             for (let i = 0; i < want; i++)

package/dist-cjs/index.cjs

@@ -73,6 +73,7 @@ __export(index_exports, {
   axisInfo: () => axisInfo,
   axisSource: () => axisSource,
   capabilitiesForType: () => capabilitiesForType,
+  capabilityOf: () => capabilityOf,
   classClosure: () => classClosure,
   compareStates: () => compareStates,
   computeOee: () => computeOee,
@@ -409,6 +410,26 @@ function offCalendarAt(r, ms2, utcOffsetMinutes) {
   const h = Math.floor(minute / 60);
   return !(w.startHour <= w.endHour ? h >= w.startHour && h < w.endHour : h >= w.startHour || h < w.endHour);
 }
+function capabilityOf(r, ctx) {
+  const at = ctx?.at;
+  const eff = effectivityAt(r, at);
+  if (eff === "not-yet") return { available: false, reason: "not-yet" };
+  if (eff === "expired") return { available: false, reason: "retired" };
+  if (r.held) return { available: false, reason: "held" };
+  if (r.status === "down") return { available: false, reason: "down" };
+  if (at) {
+    const ms2 = Date.parse(at);
+    if (Number.isFinite(ms2)) {
+      const why = offCalendarReasonAt(r, ms2, ctx?.utcOffsetMinutes);
+      if (why === "non-working") return { available: false, reason: "resting" };
+      if (why === "off-hours") return { available: false, reason: "off-shift" };
+    }
+  }
+  if (ctx?.requiredTests?.length && !meetsTests(ctx.requiredTests, r.testResults, at))
+    return { available: false, reason: "test-expired" };
+  if (r.status && r.status !== "idle" && r.status !== "available") return { available: false, reason: "working" };
+  return { available: true, reason: "available" };
+}
 var OP_EVENT = {
   task: "task.status",
   equipment: "equipment.status",
@@ -3849,13 +3870,18 @@ var FlowEngine = class {
    * 판정 규칙은 계약이 소유한다(`meetsTests`) — 여기서 다시 적으면 규칙이 두 곳이 되고, 한쪽이 만료를
    * 조용히 통과시킨다.
    */
-  qualifiedByTests(p) {
+  /**
+   * 이 사람이 속한 등급들이 **요구하는 시험 목록** — 판정은 계약이 한다(`capabilityOf`).
+   *
+   * 상속을 타고 닫은 등급 전부의 요구를 모은다: 상위 등급이 요구하는 시험도 자격의 조건이다.
+   */
+  requiredTestsOf(p) {
     const defs = this.classDefs.personnel;
-    if (!defs?.length) return true;
+    if (!defs?.length) return [];
     const closure = classClosure(p.personnelClassIds, defs, this.now());
     const required = [];
     for (const d of defs) if (closure.has(d.id)) required.push(...d.testSpecificationIds ?? []);
-    return meetsTests(required, p.testResults, this.now());
+    return required;
   }
   claimPersonnel(t) {
     const need = this.operationSpecs.get(t.kind)?.personnelSpecification;
@@ -3865,19 +3891,20 @@ var FlowEngine = class {
       const want = Math.max(0, Math.floor(req.quantity ?? 0));
       if (!want) continue;
       const avail = [...this.persons.values()].filter(
-        (p) => p.status === "idle" && !picked.includes(p.id) && !this.personOffShift(p) && !this.outOfEffect(p) && // 입사 전·퇴사 후는 이 시각의 모델에 없다
-        /* 자격은 **상속을 타고 닫아** 판정한다 — 사람은 여러 등급에 속할 수 있고(표준), 등급은
-           다른 등급을 상속한다. "생산직 2명" 요구를 "용접 자격자" 가 만족해야 한다.
-           유효기간 밖의 등급은 닫힘에서 빠진다(만료된 자격으로 배정되지 않는다). */
-        (req.personnelClass === void 0 || classClosure(p.personnelClassIds, this.classDefs.personnel, this.now()).has(req.personnelClass)) && /*
-         * **요구된 시험을 만족하나** — 등급이 요구하고(`testSpecificationIds`) 사람이 결과를 든다
-         * (`testResults`). 만료·불합격이면 그 자격은 성립하지 않는다.
+        (p) => !picked.includes(p.id) && /*
+         * **판정은 한 벌이다**(`capabilityOf`). 예전에는 이 자리에 조건을 늘어놓았고 화면은 같은
+         * 판정을 자기 코드로 다시 만들었다 — 규칙이 두 벌이면 갈라지고, 배정은 막는데 화면은
+         * "가용" 이라 말하는 순간이 온다(그 어긋남은 조용하다).
          *
-         * 결과가 **아예 없으면 막지 않는다**: 없는 것으로 막으면 자격자가 전부 사라져 라인이 영구히
-         * 굶고, 원본이 결과를 주지 않는 현장에서는 그 제약이 선언되지 않은 것이다("선언한 것만
-         * 제약이 된다" — 이 커널의 규율).
+         * 요구된 시험은 등급에서 모아 넘긴다 — 등급 정의를 아는 것은 이쪽이다.
          */
-        this.qualifiedByTests(p)
+        capabilityOf(p, {
+          at: this.now(),
+          utcOffsetMinutes: this.boardDef?.utcOffsetMinutes,
+          requiredTests: this.requiredTestsOf(p)
+        }).available && /* 자격은 **상속을 타고 닫아** 판정한다 — 사람은 여러 등급에 속할 수 있고(표준), 등급은
+           다른 등급을 상속한다. "생산직 2명" 요구를 "용접 자격자" 가 만족해야 한다. */
+        (req.personnelClass === void 0 || classClosure(p.personnelClassIds, this.classDefs.personnel, this.now()).has(req.personnelClass))
       );
       if (avail.length < want) return null;
       for (let i = 0; i < want; i++) picked.push(avail[i].id);
@@ -5159,6 +5186,7 @@ function retiredVocabularyIn(line) {
   axisInfo,
   axisSource,
   capabilitiesForType,
+  capabilityOf,
   classClosure,
   compareStates,
   computeOee,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/twin-kernel",
-  "version": "0.6.6",
+  "version": "0.6.7",
   "type": "module",
   "description": "Twin Domain Kernel — framework-agnostic, zero-dep (domain + sim + 3-channel contract). WMS/YMS/MES, EPCIS 2.0 · ISA-95.",
   "publishConfig": {