@operato/ops-contract 0.1.0

package/README.md

@@ -0,0 +1,23 @@
+# @operato/ops-contract
+
+운영 도메인의 **계약** — 사실을 만드는 쪽과 읽는 쪽이 합의해야 하는 것.
+
+```
+EPCIS 2.0 · GS1          물품의 이동과 계보
+ISA-95                   자재 · 설비 · 사람 · 공정
+IEC 61850 · ISO 50001    전기 계통과 성과지표
+```
+
+## 무엇이 여기 있고 무엇이 없나
+
+여기 있는 것은 **타입 · 판별 함수 · 정합 검증 · 어휘 상수**입니다. 인자만 보고 답합니다.
+
+여기 없는 것은 **정책과 엔진**입니다. 그 사실로 무엇을 할지는 `@operato/twin-kernel` 이 정합니다.
+
+## 왜 나뉘어 있나
+
+사실을 **만드는 쪽**(MES · 커넥터)은 계약만 필요하고 엔진은 필요 없습니다. 한 패키지에 두면 레코드
+하나를 만들려고 시뮬레이션 엔진과 네 도메인 커널을 의존 그래프에 올리게 됩니다.
+
+타입만이면 `import type` 으로 피할 수 있지만, **판별 함수는 런타임 함수입니다**(`isEnergyRecord` 계열).
+보내는 쪽이 보내기 전에 스스로 검증하려면 실제로 필요합니다.

package/dist/capability.d.ts

@@ -0,0 +1,142 @@
+export type CapabilityKey = 'operable' | 'storable' | 'mobile' | 'processable' | 'trackable' | 'switching' | 'metered' | 'curtailable' | 'energyGenerating' | 'energyStoring';
+/** 이동 관측 — Mobile 이 노출. */
+export interface Motion {
+    fromNode: string;
+    toNode: string;
+    startedAtSimMs: number;
+    durationMs: number;
+    progress: number;
+    elapsedMs: number;
+}
+export interface OperableState {
+    status: 'idle' | 'busy' | 'down';
+}
+export interface StorableState {
+    occupancy: number;
+    capacity: number;
+}
+export interface MobileState {
+    location: string;
+    motion?: Motion;
+}
+export interface ProcessableState {
+    output?: {
+        good: number;
+        scrap: number;
+    };
+}
+export interface TrackableState {
+    lifecycle: string;
+    progress?: number;
+    held: boolean;
+}
+/**
+ * 계량 — 이 자원은 **자기 소비를 잰다.**
+ *
+ * `kW` 는 그 계량 주기의 평균이고 순시값이 아니다(순시는 전력 품질의 영역이라 범위 밖).
+ * `kWh` 는 계기 누적값 — 차분은 소비처가 한다(계기 교체·리셋을 우리가 지어내지 않는다).
+ * 값이 오지 않는 계량기는 `0` 이 아니라 **모르는 것**이므로 필드가 없다(선택 필드인 이유).
+ */
+export interface MeteredState {
+    kW?: number;
+    kWh?: number;
+    powerFactor?: number;
+}
+/** 감축 가능 — 줄일 수 있다. `minKW` 는 최소 유지(그 아래로 내리면 공정이 죽는다). */
+export interface CurtailableState {
+    curtailable: boolean;
+    minKW?: number;
+}
+/**
+ * 전기 계측 — 전압(V)·전류(A). 전기를 만들거나 쓰는 어떤 설비에서나 같은 모양이다.
+ *
+ * 발전·저장·개폐 어느 능력에나 붙을 수 있어 따로 둔다. 상별 값은 배열이다(단상이면 원소 하나).
+ */
+export interface ElectricalMeasurementState {
+    dcVoltage?: number;
+    dcCurrent?: number;
+    acVoltage?: number[];
+    acCurrent?: number[];
+}
+/** 발전 — 만든다. 역송(`exportKW`)은 소비의 음수가 아니라 별개 사실이다. */
+export interface GeneratingState extends ElectricalMeasurementState {
+    generatedKW?: number;
+    exportKW?: number;
+    generatedKWh?: number;
+    generatedKWhResetAt?: string;
+    /** 지금 든 적산이 무엇부터 쌓인 것인가 — 원본이 말했을 때만 있다. */
+    generatedKWhSince?: string;
+    /** 되돌아간 판정이 사실인가 짐작인가 — 'declared' 또는 'inferred'. */
+    generatedKWhBasis?: 'declared' | 'inferred';
+    /** 어떤 누적인가 — 원본이 말하지 않으면 'unknown' 이다(칸이 비지 않는다). */
+    generatedKWhAccumulation?: 'lifetime' | 'daily' | 'monthly' | 'billing' | 'unknown';
+    /** 끝난 기간의 발전량(kWh) — 성과지표가 기간당 에너지로 정의된다. */
+    generatedKWhLastPeriod?: number;
+    /** 그 기간이 끝난 시각. */
+    generatedKWhLastPeriodEnd?: string;
+    /** 그 기간에서 처음·마지막으로 관측한 시각 — 기간 경계와 다르면 그만큼 재지 않았다. */
+    generatedKWhLastPeriodObservedFrom?: string;
+    generatedKWhLastPeriodObservedTo?: string;
+}
+/** 저장 — 담고 낸다. 충전과 방전을 나눈다(손실·수명 판단이 둘을 구별해야 한다). */
+export interface StoringState {
+    soc?: number;
+    chargeKW?: number;
+    dischargeKW?: number;
+}
+/**
+ * 개폐 위치 — IEC 61850 `XCBR.Pos`·`XSWI.Pos` 의 넷 값을 그대로 쓴다.
+ *
+ * `intermediate`(과도)와 `bad`(위치 불량)를 **뭉개지 않는다**: 실 계통에서 이 둘은 이중 접점이 서로
+ * 다른 말을 하는 상태이고, 「열림/닫힘」으로 반올림하면 트윈이 없는 확신을 갖는다.
+ */
+export interface SwitchingState {
+    position?: 'open' | 'closed' | 'intermediate' | 'bad';
+}
+/** 능력 관측 계약 메타(발견·검증). ops 없음(원칙 ①). */
+export interface CapabilitySpec {
+    key: CapabilityKey;
+    label: string;
+    semantics: string;
+    /** 관측 상태 필드(데이터 형식). 직교 — 어느 필드도 두 능력에 중복 없음(원칙 ②). */
+    stateFields: string[];
+    /**
+     * 이 능력을 가진 자원이 **받는 명령** — 나가는 사실(`results`)의 짝.
+     *
+     * ── 계약이 반쪽이었다 (2026-08-15) ────────────────────────────────────────
+     * 능력은 「무슨 값을 내보내는가」만 선언하고 있었다. 그런데 저작면이 알아야 할 것이 하나 더 있다:
+     * 「여기에 제어를 붙여도 되는가」. 적을 자리가 없어서 **능력 이름으로 눈치껏** 판단했다 —
+     * `operable` 이면 제어를 권하고 아니면 안 권했다.
+     *
+     * 차단기에서 그 방식이 막혔다. 상태는 보여주고 싶은데 `operable` 을 주면 화면이 우리가 하지 않기로
+     * 한 조작을 권한다. 그래서 능력을 새로 만들었고(`switching`), 능력은 상태 필드로 정의되므로 새
+     * 필드가 필요했는데 마침 표준이 `position` 이라는 이름을 줘서 됐다 — **그건 운이었다.**
+     *
+     * 없던 것은 참/거짓 하나가 아니라 **대칭**이다: 나가는 것은 선언돼 있고 들어오는 것은 없었다.
+     * 명령 어휘(`CMD`)는 이미 능력별로 묶여 있었지만 그 묶임이 **주석에만** 있었다 — 여기로 옮긴다.
+     *
+     * 비어 있다는 것이 곧 「조작하지 않는다」이다. 「명령을 받나」는 이 목록에서 **파생**된다 —
+     * 그래서 형용사를 새로 만들지 않는다.
+     *
+     * 트윈 수준 명령(`attention.ack`·`resource.add`)은 특정 자원의 능력이 아니므로 여기 넣지 않는다.
+     * 모든 명령이 능력에 속해야 한다는 규칙을 만들면 그것이 다음 땜빵이 된다.
+     */
+    commands: string[];
+    /** 교환 데이터 모델 이름. */
+    models?: string[];
+    /** 불변식(모두 준수·신뢰). */
+    invariants?: string[];
+    /** 실행 결과(이벤트) 형식. */
+    results?: string[];
+}
+export declare const CAPABILITIES: Record<CapabilityKey, CapabilitySpec>;
+export declare const CAPABILITY_KEYS: CapabilityKey[];
+/** 능력 집합이 관측 노출하는 상태 필드 합집합(직교이므로 단순 병합). */
+export declare function stateFieldsOf(caps: CapabilityKey[]): string[];
+/**
+ * 능력 집합이 **받는 명령**의 합집합 — `stateFieldsOf` 의 짝.
+ *
+ * 「이 자원에 제어를 붙여도 되는가」는 이 목록이 비었는지로 **파생**한다. 그래서 `controllable` 같은
+ * 형용사를 따로 두지 않는다 — 형용사를 두면 목록과 형용사가 언젠가 어긋나고, 어긋난 쪽이 화면이 된다.
+ */
+export declare function commandsOf(caps: CapabilityKey[]): string[];

package/dist/capability.js

@@ -0,0 +1,127 @@
+/*
+ * 능력(capability) = 관측 계약(observable contract). 사상 토대: design/plans/capability-contract.md.
+ *
+ * 원칙 ① 관측만 — state(데이터형식)+models+invariants+results 만 계약. ops/구현은 없음(커널·씬 각 시뮬 자유).
+ *        "교환되는 것"을 계약하고 "계산하는 법"은 계약하지 않는다(결정성 지옥 회피·공유 가능성 핵심).
+ * 원칙 ② 직교·조합 — 교차 관심사 status 는 Operable 하나에만(중복 제거). 엔티티는 능력 *조합*.
+ * 원칙 ③ 작은 코어 + 열린 확장(무방언) — 도메인이 능력 선언, 코어는 발명 안 함.
+ * 원칙 ④ 능력 ⟂ standardClass — 다른 축, 파생 없음.
+ *
+ * things-scene 정합: 이건 "의도(intent)" 계층(관측). 씬 기제 믹스(Capacity/Transferable/CarrierLine …)가
+ * 이 의도를 *실현*한다 — 공유 계약은 관측(계층 B)뿐, 기제 methods(계층 A)는 공유 안 함.
+ * ⚠ Mobile ≠ Transferable: Mobile=자원 자신이 이동, Transferable=자리가 아이템 이동(씬 기제).
+ */
+/*
+ * `label` 은 **언어 중립 i18n 키**(`twin.capability.<key>`) — 사람 언어는 표현계층이 렌더한다(L2).
+ * 타입/시스템 라벨(domain-catalog)이 먼저 이 규약으로 옮겨졌고, 능력 라벨만 사람 말로 남아
+ * 영어 화면에 한글이 새고 있었다. `semantics` 는 설계 문서용 산문이므로 대상이 아니다.
+ */
+export const CAPABILITIES = {
+    operable: {
+        key: 'operable', label: 'twin.capability.operable', semantics: '능동 자원의 운영 상태(유휴/가동/고장). status 교차 관심사를 여기 하나로.',
+        commands: ['resource.hold', 'resource.resume', 'resource.down', 'resource.repair', 'resource.reset-metrics'],
+        stateFields: ['status'], results: ['statusChanged']
+    },
+    storable: {
+        key: 'storable', label: 'twin.capability.storable', semantics: '아이템을 보유하는 위치 — 점유/용량. (씬 기제: Capacity)',
+        commands: [],
+        stateFields: ['occupancy', 'capacity'], invariants: ['0 <= occupancy <= capacity (capacity>0)'], results: ['occupancyChanged']
+    },
+    mobile: {
+        key: 'mobile', label: 'twin.capability.mobile', semantics: '자원 자신이 자리 간 이동. Transferable(아이템 이동)과 다름. (씬 기제: CarrierLine)',
+        commands: [],
+        stateFields: ['location', 'motion'], models: ['Motion'], results: ['moved', 'motionTick']
+    },
+    processable: {
+        key: 'processable', label: 'twin.capability.processable', semantics: '변환/가공 수행 — 산출(양품/불량). 운영 status 는 Operable 조합. progress 방출은 후속.',
+        commands: [],
+        stateFields: ['output'], results: ['completed']
+    },
+    /*
+     * ── 「위치를 읽는다」 ≠ 「조작할 수 있다」 (2026-08-14) ─────────────────────
+     * 차단기는 이 둘이 갈리는 자리다. 상태를 읽어 계통 구성을 알지만 **우리는 조작하지 않는다**
+     * (안전 계통은 범위 밖: profiles/ems.md §1). 그런데 능력을 `operable` 로 주면 저작면이 그 설비에
+     * **제어 컴포넌트를 권한다** — 화면이 우리가 하지 않기로 한 것을 하라고 부추긴다.
+     *
+     * 그래서 개폐 기기의 관측을 따로 세운다. 이름을 `observable` 로 하지 않은 이유: 그러면 상태 필드가
+     * `status` 여야 하고 그건 `operable` 의 것이다(원칙 ② 직교). 없는 필드를 지어내는 대신 **표준이 주는
+     * 이름**을 쓴다 — 개폐 기기의 관측은 `Pos`(위치)다.
+     *
+     * `operable` 은 그대로 「명령을 받는 능동 자원」의 자리로 남는다.
+     */
+    switching: {
+        key: 'switching', label: 'twin.capability.switching', semantics: '회로를 열고 닫는 기기의 **위치를 읽는다** — 우리는 조작하지 않는다(명령 없음). IEC 61850 XCBR/XSWI Pos.',
+        commands: [],
+        stateFields: ['position'], models: ['SwitchingState'], results: ['positionChanged']
+    },
+    trackable: {
+        key: 'trackable', label: 'twin.capability.trackable', semantics: '오더/아이템 생애 추적 — 생애단계(도메인 라벨, 무방언)·진행·보류.',
+        commands: ['order.hold', 'order.resume', 'order.release'],
+        stateFields: ['lifecycle', 'progress', 'held'], results: ['lifecycleChanged']
+    },
+    /*
+     * ── 에너지 능력 넷 ──────────────────────────────────────────────────────
+     * 상태 필드는 기존 능력과 **직교**한다(원칙 ②) — 어느 필드도 두 능력에 겹치지 않는다.
+     * 계량은 `operable`(가동 상태)과도 직교한다: 도는 것과 재는 것은 다른 사실이고, 멈춘 설비도
+     * 대기전력을 쓴다.
+     */
+    metered: {
+        key: 'metered', label: 'twin.capability.metered', semantics: '자기 소비를 잰다 — 유효전력·누적량·역률. 값이 없으면 모르는 것이다(0 이 아니다).',
+        commands: [],
+        stateFields: ['kW', 'kWh', 'powerFactor'], models: ['MeteredState'], results: ['measured']
+    },
+    curtailable: {
+        key: 'curtailable', label: 'twin.capability.curtailable', semantics: '줄일 수 있다 — 최소 유지 아래로는 내리지 않는다. 판정만 하고 집행은 사람과 그 시스템의 몫이다.',
+        commands: [],
+        stateFields: ['curtailable', 'minKW'], models: ['CurtailableState'], invariants: ['minKW >= 0'], results: ['drSuggested']
+    },
+    energyGenerating: {
+        key: 'energyGenerating', label: 'twin.capability.energyGenerating', semantics: '전기를 만든다 — 역송은 소비의 음수가 아니라 별개 사실이다.',
+        commands: [],
+        /*
+         * ── 적산을 더한다 (2026-08-26) ─────────────────────────────────────────────
+         * 이 능력이 순시 출력만 선언하고 있었다. 그래서 「지금 발전 중」은 말하고 「얼마나 발전했나」는 말할
+         * 수 없었다 — 사건 이름(`energy.generated`)과 설계 문서에는 처음부터 있던 사실이다.
+         *
+         * 계량 능력(`metered`)이 `kW` 와 `kWh` 를 함께 선언한 것과 같은 짝이다. 적산은 발전 설비의 보편적
+         * 사실이고(태양광·열병합·디젤), 그것이 없으면 성능비·발전시간 같은 성과를 아무도 셀 수 없다.
+         */
+        stateFields: ['generatedKW', 'exportKW', 'generatedKWh', 'generatedKWhResetAt', 'generatedKWhSince', 'generatedKWhBasis', 'generatedKWhAccumulation', 'generatedKWhLastPeriod', 'generatedKWhLastPeriodEnd', 'generatedKWhLastPeriodObservedFrom', 'generatedKWhLastPeriodObservedTo', 'dcVoltage', 'dcCurrent', 'acVoltage', 'acCurrent'], models: ['GeneratingState'], results: ['generated']
+    },
+    /*
+     * ── 왜 `storing` 이 아니라 `energyStoring` 인가 (2026-08-15) ────────────────
+     * 같은 카탈로그에 `storable`(물건을 담는 자리)이 있다. 전기를 담는 것과 물건을 담는 것이 한 글자
+     * 차이로 붙어 있어서, 컴포넌트를 만들 때 `twin-storage` 를 피해 `twin-storage-energy` 로 도망쳤다 —
+     * 한 이름을 두 번 피해 갔다면 그 이름이 틀린 것이다.
+     *
+     * 도메인(EMS)이 아니라 **양(에너지)** 을 이름에 넣는다. 그래서 MES 트윈 안의 디젤 발전기도 그대로
+     * `energyGenerating` 이다 — 능력은 도메인이 아니라 관측의 면이다(방언 없음).
+     */
+    energyStoring: {
+        key: 'energyStoring', label: 'twin.capability.energyStoring', semantics: '담고 낸다 — 충전과 방전을 나눈다(손실·수명 판단이 둘을 구별해야 한다).',
+        commands: [],
+        stateFields: ['soc', 'chargeKW', 'dischargeKW'], models: ['StoringState'], invariants: ['0 <= soc <= 100'], results: ['stored', 'discharged']
+    }
+};
+export const CAPABILITY_KEYS = ['operable', 'storable', 'mobile', 'processable', 'trackable', 'switching', 'metered', 'curtailable', 'energyGenerating', 'energyStoring'];
+/** 능력 집합이 관측 노출하는 상태 필드 합집합(직교이므로 단순 병합). */
+export function stateFieldsOf(caps) {
+    const out = new Set();
+    for (const c of caps)
+        for (const f of CAPABILITIES[c]?.stateFields ?? [])
+            out.add(f);
+    return [...out];
+}
+/**
+ * 능력 집합이 **받는 명령**의 합집합 — `stateFieldsOf` 의 짝.
+ *
+ * 「이 자원에 제어를 붙여도 되는가」는 이 목록이 비었는지로 **파생**한다. 그래서 `controllable` 같은
+ * 형용사를 따로 두지 않는다 — 형용사를 두면 목록과 형용사가 언젠가 어긋나고, 어긋난 쪽이 화면이 된다.
+ */
+export function commandsOf(caps) {
+    const out = new Set();
+    for (const c of caps)
+        for (const cmd of CAPABILITIES[c]?.commands ?? [])
+            out.add(cmd);
+    return [...out];
+}

package/dist/capacity.d.ts

@@ -0,0 +1,99 @@
+import { type WorkCalendarEntry } from './contract.ts';
+import type { OperationDef } from './domain-definition.ts';
+/** 제약이 걸린 축 — 무엇을 늘려야 하는지가 여기서 갈린다. */
+export type CapacityAxis = 'equipment' | 'personnel' | 'asset' | 'location';
+export interface CapacityRequirement {
+    axis: CapacityAxis;
+    /** 요구 등급/종류(설비 kind · 인원 class · 자산 class · 자리 type). */
+    className: string;
+    /** 작업 한 건이 동시에 잡는 수. */
+    quantity: number;
+    /** 실제로 있는 수. */
+    available: number;
+    /** 가동률 — 설비만 mtbf/mttr 에서 나온다. 나머지는 1(모델 없음). */
+    availability: number;
+    /** 이 요구만 놓고 봤을 때 시간당 낼 수 있는 대수. */
+    perHour: number;
+}
+export interface OperationCapacity {
+    operation: string;
+    cycleHours: number;
+    /** 이 공정이 시간당 낼 수 있는 대수 = 요구들 중 가장 낮은 것. */
+    perHour: number;
+    /** 하류 수율까지 물린 소요량. */
+    requiredPerHour: number;
+    ok: boolean;
+    /** 이 공정을 묶고 있는 요구(가장 낮은 것). 요구가 하나도 없으면 없다. */
+    constraint?: CapacityRequirement;
+    requirements: CapacityRequirement[];
+}
+export interface CapacityAnalysis {
+    /** 근무 캘린더를 실제로 샘플링해서 얻는다 — 규칙을 다시 적지 않는다. */
+    workingHoursPerWeek: number;
+    workingDaysPerWeek: number;
+    demandPerHour: number;
+    operations: OperationCapacity[];
+    /** 라인 전체를 묶고 있는 공정과 축. 공정이 없으면 없다. */
+    bottleneck?: {
+        operation: string;
+        axis?: CapacityAxis;
+        className?: string;
+    };
+    /** 이 공장의 상한(하루). */
+    maxUnitsPerDay: number;
+    ok: boolean;
+}
+export interface CapacityInput {
+    operations: readonly OperationDef[];
+    /** 라우트 순서 — 수율을 거슬러 올릴 때 쓴다. 없으면 `operations` 순서를 쓴다. */
+    route?: readonly string[];
+    equipment?: readonly {
+        kind: string;
+        mtbfMs?: number;
+        mttrMs?: number;
+    }[];
+    persons?: readonly {
+        personnelClassIds?: readonly string[];
+    }[];
+    assets?: readonly {
+        assetClassIds?: readonly string[];
+    }[];
+    locations?: readonly {
+        type?: string;
+        capacity?: number;
+    }[];
+    calendar?: readonly WorkCalendarEntry[];
+    /**
+     * 가용 시간을 샘플링할 기준 주의 시작(월요일 00:00, ms).
+     *
+     * **공휴일이 없는 평상주를 골라야 한다** — 공휴일은 연간 가용량을 따로 깎지, 이 공장의 평상시
+     * 상한을 정하지 않는다. 기본값을 두지 않는 이유: 커널이 임의의 주를 고르면 그 주에 공휴일이
+     * 들어 있을 때 상한이 조용히 낮아진다.
+     */
+    sampleWeekStartMs: number;
+    utcOffsetMinutes?: number;
+    /** 하루 몇 대를 낼 것인가 — 선언된 수요. */
+    unitsPerDay: number;
+}
+/** ISO 8601 기간 → 시간. 명세가 쓰는 표기 그대로 읽는다(`PT1H40M`). */
+export declare function isoDurationHours(iso: string | undefined): number;
+/**
+ * 근무 캘린더에서 **가용 시간과 조업일**을 읽는다 — 1분 간격 샘플링.
+ *
+ * 교대·휴게·비근무 규칙을 여기 다시 적지 않는다. 규칙은 `inWorkCalendarAt` 한 곳에만 있고, 이 함수는
+ * 그것에 묻기만 한다. 두 벌이 되면 달력을 고칠 때 한쪽만 고쳐져 어긋난다.
+ *
+ * 캘린더가 없으면 **종일 가동**으로 본다(7일 × 24h) — 제약이 없는 것이 아니라 **선언되지 않은** 것이고,
+ * 선언이 없으면 커널은 멈출 이유를 모른다.
+ */
+export declare function workingTimeOfWeek(calendar: readonly WorkCalendarEntry[] | undefined, weekStartMs: number, utcOffsetMinutes?: number): {
+    hoursPerWeek: number;
+    daysPerWeek: number;
+};
+/**
+ * 이 공장이 선언된 물량을 낼 수 있는가 — 공정마다, 자원 축마다.
+ *
+ * 순수 함수다. 커널 상태를 읽지 않고 넘겨받은 것만 본다 — 그래야 "이 설비를 두 대 더 놓으면?" 을
+ * 실행해 보지 않고 물을 수 있다(what-if 의 가장 싼 형태).
+ */
+export declare function analyzeCapacity(input: CapacityInput): CapacityAnalysis;

package/dist/capacity.js

@@ -0,0 +1,172 @@
+/*
+ * 용량 분석 — **실행해 보기 전에 "이 공장이 그 물량을 낼 수 있는가" 에 답한다.**
+ *
+ * ── 왜 커널인가 ──────────────────────────────────────────────────────────────
+ * 이 계산을 처음에는 레퍼런스 마스터 옆에서 손으로 했다(Rosarito). 그러다 두 가지를 알았다.
+ *
+ * 첫째, **입력이 전부 커널에 있다.** 공정 명세(소요·셋업·수율)·설비와 그 신뢰도·인원·물리자산·자리·
+ * 근무 캘린더. 바깥에서 계산하면 그 값을 옮겨 적게 되고, 한쪽만 고치는 순간 "충분하다" 가 조용히
+ * 거짓이 된다.
+ *
+ * 둘째, **손계산은 설비만 셌다.** 표준 공정 명세는 네 축으로 자원을 요구한다(설비·인원·물리자산·자재)
+ * — 그리고 현장에서 가장 자주 모자라는 것은 사람이다. 설비만 세는 계산은 "용접 자격자가 2명뿐이라
+ * 로봇 6대가 논다" 를 구조적으로 못 본다. 네 축을 다 보는 자리는 커널뿐이다.
+ *
+ * ── 이것이 시뮬레이션과 다른 점 ─────────────────────────────────────────────
+ * 시뮬레이션은 **실행해 봐야** 답이 나오고, 변동·고장·줄서기가 섞인 결과를 준다. 이 계산은 **정상상태
+ * 상한**이다 — 모든 것이 계획대로 흘렀을 때의 상한. 둘은 서로를 대체하지 않는다:
+ *   - 상한이 수요보다 낮으면 **시뮬레이션을 돌릴 필요가 없다.** 무슨 짓을 해도 못 낸다.
+ *   - 상한이 충분한데 시뮬레이션이 못 내면 그것은 **흐름의 문제**다(줄서기·배치·변동).
+ *
+ * 그래서 이 계산은 진단이 아니라 **분류**다. 어느 쪽 문제인지부터 갈라 준다.
+ *
+ * ── 재지 않는 것 ─────────────────────────────────────────────────────────────
+ * 자재는 여기서 제약으로 세지 않는다. 자재는 **보충되는 것**이라 대수처럼 고정 공급이 아니고,
+ * 부족은 조달 문제이지 용량 문제가 아니다(자재 부족은 `work-backlog` 가 흐름에서 잡는다).
+ * 인원·자산에는 신뢰도 모델이 없다 — 가동률 1로 본다(설비만 mtbf/mttr 를 갖는다).
+ */
+import { inWorkCalendarAt } from "./contract.js";
+/** ISO 8601 기간 → 시간. 명세가 쓰는 표기 그대로 읽는다(`PT1H40M`). */
+export function isoDurationHours(iso) {
+    if (!iso)
+        return 0;
+    const m = /^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:([\d.]+)S)?)?$/.exec(iso);
+    if (!m)
+        throw new Error(`기간 표기를 읽을 수 없다: ${iso}`);
+    return Number(m[1] ?? 0) * 24 + Number(m[2] ?? 0) + Number(m[3] ?? 0) / 60 + Number(m[4] ?? 0) / 3600;
+}
+function paramOf(op, id) {
+    return op.parameters?.find(p => p.id === id)?.value;
+}
+/**
+ * 근무 캘린더에서 **가용 시간과 조업일**을 읽는다 — 1분 간격 샘플링.
+ *
+ * 교대·휴게·비근무 규칙을 여기 다시 적지 않는다. 규칙은 `inWorkCalendarAt` 한 곳에만 있고, 이 함수는
+ * 그것에 묻기만 한다. 두 벌이 되면 달력을 고칠 때 한쪽만 고쳐져 어긋난다.
+ *
+ * 캘린더가 없으면 **종일 가동**으로 본다(7일 × 24h) — 제약이 없는 것이 아니라 **선언되지 않은** 것이고,
+ * 선언이 없으면 커널은 멈출 이유를 모른다.
+ */
+export function workingTimeOfWeek(calendar, weekStartMs, utcOffsetMinutes) {
+    if (!calendar?.length)
+        return { hoursPerWeek: 7 * 24, daysPerWeek: 7 };
+    let minutes = 0;
+    const touched = new Set();
+    for (let m = 0; m < 7 * 24 * 60; m++) {
+        if (!inWorkCalendarAt(calendar, weekStartMs + m * 60_000, utcOffsetMinutes))
+            continue;
+        minutes++;
+        touched.add(Math.floor((m + (utcOffsetMinutes ?? 0)) / (24 * 60)));
+    }
+    /*
+     * 조업일은 **선언이 말하는 것**이지 타임라인이 번진 자국이 아니다.
+     *
+     * 야간 교대는 자정을 넘는다 — 금요일 밤에 시작한 교대는 토요일 새벽에 끝난다. 샘플링한 분을
+     * 날짜로 세면 월~금 3교대가 **6일**로 나오고, 그러면 주간 수요가 20% 부풀어 필요 없는 설비를
+     * 사라고 답한다. 교대는 "월~금에 **시작한다**" 고 선언돼 있고(`daysOfWeek`), 그것이 조업일이다.
+     *
+     * 요일 선언이 아예 없는 달력(절대 구간만 쓰는 경우)에서는 셀 근거가 없으므로 번진 자국을 쓴다.
+     */
+    const declared = new Set();
+    for (const e of calendar)
+        if (e.entryType !== 'non-working')
+            for (const d of e.daysOfWeek ?? [])
+                declared.add(d);
+    return { hoursPerWeek: minutes / 60, daysPerWeek: declared.size || touched.size };
+}
+function availabilityOf(records) {
+    /* 신뢰도를 선언하지 않은 설비는 고장 없음이다(계약의 규칙) — 1 로 센다. */
+    const ratios = records.map(r => (r.mtbfMs && r.mttrMs ? r.mtbfMs / (r.mtbfMs + r.mttrMs) : 1));
+    return ratios.length ? ratios.reduce((a, b) => a + b, 0) / ratios.length : 1;
+}
+/**
+ * 이 공장이 선언된 물량을 낼 수 있는가 — 공정마다, 자원 축마다.
+ *
+ * 순수 함수다. 커널 상태를 읽지 않고 넘겨받은 것만 본다 — 그래야 "이 설비를 두 대 더 놓으면?" 을
+ * 실행해 보지 않고 물을 수 있다(what-if 의 가장 싼 형태).
+ */
+export function analyzeCapacity(input) {
+    const { hoursPerWeek, daysPerWeek } = workingTimeOfWeek(input.calendar, input.sampleWeekStartMs, input.utcOffsetMinutes);
+    /*
+     * 수요는 **가동 시간당**이다. 하루 50대는 쉬는 시간에는 안 나오므로 168시간으로 나누면 안 된다 —
+     * 그렇게 나누면 필요한 대수가 실제보다 적게 나오고, 공장은 매주 조금씩 밀린다.
+     */
+    const demandPerHour = hoursPerWeek > 0 ? (input.unitsPerDay * daysPerWeek) / hoursPerWeek : 0;
+    /* 축별 공급 — 등급 이름으로 센다. 사람은 자격을 여럿 가질 수 있어 등급 간 합이 인원수를 넘는다
+       (같은 사람이 두 줄에 선다). 동시에 두 공정을 하지는 못하므로 이 계산은 **낙관적**이다. */
+    const equipmentByKind = new Map();
+    for (const e of input.equipment ?? []) {
+        const list = equipmentByKind.get(e.kind) ?? [];
+        list.push(e);
+        equipmentByKind.set(e.kind, list);
+    }
+    const countByClass = (rows, field) => {
+        const out = new Map();
+        for (const r of rows ?? [])
+            for (const c of r[field] ?? [])
+                out.set(c, (out.get(c) ?? 0) + 1);
+        return out;
+    };
+    const personsByClass = countByClass(input.persons, 'personnelClassIds');
+    const assetsByClass = countByClass(input.assets, 'assetClassIds');
+    const slotsByLocationType = new Map();
+    for (const l of input.locations ?? [])
+        if (l.type)
+            slotsByLocationType.set(l.type, (slotsByLocationType.get(l.type) ?? 0) + Math.max(l.capacity ?? 1, 1));
+    const order = input.route?.length
+        ? input.route.map(k => input.operations.find(o => o.key === k)).filter((o) => !!o)
+        : [...input.operations];
+    /* 하류 수율을 거슬러 올라가며 소요량을 부풀린다 — 도장에서 5% 를 잃으면 그 앞은 더 만들어야 한다. */
+    let downstream = 1;
+    const reversed = [];
+    for (const op of [...order].reverse()) {
+        const cycleHours = isoDurationHours(op.duration) + isoDurationHours(paramOf(op, 'setupDuration'));
+        downstream *= Number(paramOf(op, 'yield') ?? 1);
+        const requiredPerHour = downstream > 0 ? demandPerHour / downstream : Infinity;
+        const requirements = [];
+        const add = (axis, className, quantity, available, availability) => {
+            const q = Math.max(quantity, 1);
+            requirements.push({
+                axis, className, quantity: q, available, availability,
+                perHour: cycleHours > 0 ? (Math.floor(available / q) / cycleHours) * availability : Infinity
+            });
+        };
+        /* 설비 — 표준 EquipmentSpecification(등급+대수). 그것이 없으면 예전 표기(resourceType 한 대). */
+        const equipSpecs = op.equipmentSpecification?.length
+            ? op.equipmentSpecification.map(s => ({ className: s.equipmentClass ?? op.resourceType ?? '', quantity: s.quantity }))
+            : op.resourceType ? [{ className: op.resourceType, quantity: 1 }] : [];
+        for (const s of equipSpecs) {
+            if (!s.className)
+                continue;
+            const records = equipmentByKind.get(s.className) ?? [];
+            add('equipment', s.className, s.quantity, records.length, availabilityOf(records));
+        }
+        for (const s of op.personnelSpecification ?? [])
+            if (s.personnelClass)
+                add('personnel', s.personnelClass, s.quantity, personsByClass.get(s.personnelClass) ?? 0, 1);
+        for (const s of op.physicalAssetSpecification ?? [])
+            if (s.assetClass)
+                add('asset', s.assetClass, s.quantity, assetsByClass.get(s.assetClass) ?? 0, 1);
+        if (op.locationType)
+            add('location', op.locationType, 1, slotsByLocationType.get(op.locationType) ?? 0, 1);
+        /* 공정의 능력 = 요구들 중 가장 낮은 것. 전량 확보 규칙이라 하나만 모자라도 그만큼만 처리된다. */
+        const constraint = requirements.length ? requirements.reduce((a, b) => (a.perHour <= b.perHour ? a : b)) : undefined;
+        const perHour = constraint ? constraint.perHour : Infinity;
+        reversed.push({ operation: op.key, cycleHours, perHour, requiredPerHour, ok: perHour >= requiredPerHour, constraint, requirements });
+    }
+    const operations = reversed.reverse();
+    /* 병목 = 여유가 가장 적은 공정. 라인 전체의 상한은 그 공정이 정한다. */
+    const tightest = operations.length
+        ? operations.reduce((a, b) => (a.perHour / a.requiredPerHour <= b.perHour / b.requiredPerHour ? a : b))
+        : undefined;
+    const headroom = operations.length ? Math.min(...operations.map(o => o.perHour / o.requiredPerHour)) : Infinity;
+    return {
+        workingHoursPerWeek: hoursPerWeek,
+        workingDaysPerWeek: daysPerWeek,
+        demandPerHour,
+        operations,
+        ...(tightest ? { bottleneck: { operation: tightest.operation, axis: tightest.constraint?.axis, className: tightest.constraint?.className } } : {}),
+        maxUnitsPerDay: input.unitsPerDay * headroom,
+        ok: operations.every(o => o.ok)
+    };
+}