@things-factory/headless-twin 10.0.12 → 10.0.13

package/dist-server/engine/stage-path.d.ts

@@ -0,0 +1,83 @@
+export type StageId = 'structure' | 'live' | 'forecast' | 'closed-loop';
+/** 판정에 쓰는 사실. `null` = **계측되지 않았다**(0 이 아니다). */
+export interface StageEvidence {
+    /** 이 트윈이 든 자리 수. */
+    locationCount: number;
+    /** 자리에 놓인 물품 수(비직렬 수량 물품 포함 — 식품·화학은 개수가 아니라 총량으로 온다). */
+    itemCount: number;
+    /**
+     * 마스터를 옮기며 **못 옮긴 값의 수**. `null` = 세지 않았다.
+     *
+     * 0 이면 통과이고 n 이어도 통과다 — 이 판정이 요구하는 것은 「없다」가 아니라 **「말할 수 있다」**다.
+     * 못 옮긴 값을 세지 않은 구조 인제스트는 도크를 랙으로 바꿔 놓고도 조용히 성공한다.
+     */
+    masterWarnings: number | null;
+    /**
+     * 이 축이 이 트윈에 **해당하나**. 레퍼런스 없이 템플릿으로 세운 트윈에는 옮겨 온 마스터가 없으므로
+     * 「못 옮긴 값」을 물을 대상이 아니다 — 그걸 미측정으로 접으면 영원히 배선을 기다린다.
+     */
+    masterWarningsApplicable?: boolean;
+    /** 인제스트 누적 건수. */
+    liveIngestTotal: number;
+    /** **반출(remove)을 접은 누적 건수.** `null` = 계측되지 않음. 0 = 세었으나 없었다(→ 스냅샷 의심). */
+    removalsObserved: number | null;
+    /** 이 트윈에서 예측이 한 번이라도 돌았나. */
+    forecastRan: boolean;
+    /** 선언 적재량 — `declared`/`total`. `null` = 알 수 없음. */
+    specCoverage: {
+        declared: number;
+        total: number;
+    } | null;
+    /**
+     * 이 트윈이 **무엇인가** — 시뮬레이션은 원천에서 받는 것이 없다.
+     *
+     * 시뮬에 라이브를 요구하면 영원히 빨갛고, 그 빨강은 결함이 아니다. 도입 단계는 **연결된 트윈**의
+     * 축이므로 시뮬은 라이브 이후를 「해당 없음」으로 말한다(달성으로도, 미측정으로도 접지 않는다).
+     */
+    subject?: 'live' | 'sim';
+    /** 피드 성격 — `snapshot-poll` 이면 반출 0 은 「아직」이 아니라 **구조적으로 불가**다. */
+    feed?: 'push' | 'delta-poll' | 'snapshot-poll' | 'none' | 'unknown';
+    /** 원본이 **선언∩구현**으로 액추에이션 능력을 갖나(`capabilitiesOf`). */
+    actuateCapability: boolean;
+    /** 내 명령의 효과가 인바운드로 **상관되어** 돌아온 누적 건수. `null` = 계측되지 않음. */
+    correlatedEffectObserved: number | null;
+}
+export interface StageVerdict {
+    id: StageId;
+    achieved: boolean;
+    /** 아직 아닌 이유 — 언어중립 코드(화면이 옮긴다). 달성이면 빈 배열. */
+    blockedBy: string[];
+    /** 판정할 수 없었던 신호 — **배선되지 않은 계측**. 있으면 달성이 아니다. */
+    unmeasured: string[];
+}
+export interface StagePath {
+    stages: StageVerdict[];
+    /** 지금 서 있는 칸 — 연속으로 달성된 마지막 단계. 하나도 없으면 `null`. */
+    reached: StageId | null;
+    /**
+     * 다음 한 걸음 — 사람이 오늘 할 수 있는 일 하나. 없으면(전부 달성) `null`.
+     * 「무엇이 부족한지」의 목록이 아니라 **다음 하나**다. 목록은 사람을 멈추게 한다.
+     */
+    next: {
+        stage: StageId;
+        blockedBy: string[];
+        unmeasured: string[];
+    } | null;
+}
+/**
+ * 증거로 단계를 판정한다.
+ *
+ * **단계는 앞선 단계를 전제한다**(구조 없이 라이브를 달성했다고 말할 수 없다). 앞이 막히면 뒤는
+ * 자기 조건을 따지지 않고 `prerequisite` 으로 막는다 — 뒤 단계의 조건을 나열하면 사람이 순서를
+ * 건너뛴다.
+ */
+export declare function assessStagePath(e: StageEvidence): StagePath;
+/**
+ * 이 단계에 이르지 못했다면 **쓰지 않기로 한 말**.
+ *
+ * 근거 수준 규율(`connector-developer-guide` §8)을 판정과 같은 자리에 둔다. 문장이 문서에만 있으면
+ * 제안서를 쓰는 사람이 그 문서를 읽지 않는다. 값이 되면 화면이 그 자리에서 말할 수 있다.
+ */
+export declare const CLAIM_GATE: Record<StageId, string>;
+/** 아직 쓸 수 없는 주장들 — 도달하지 못한 단계의 게이트 전부. */
+export declare function forbiddenClaims(path: StagePath): string[];

package/dist-server/engine/stage-path.js

@@ -0,0 +1,118 @@
+"use strict";
+/*
+ * 단계 판정 — **가벼운 성공을 최종 성공으로 잇는 길을, 사람의 체크가 아니라 증거로 센다.**
+ *
+ * ── 왜 이 모듈이 있나 ───────────────────────────────────────────────────────
+ * 트윈 도입은 「구조 → 라이브 → 예측 → 폐루프」로 간다. 그런데 이 진행을 **체크리스트**로 관리하면
+ * 사람이 체크하는 순간 참이 된다. 실제로 가장 자주 건너뛰어지는 자리가 구조 다음이다 — 구조가 서면
+ * 화면이 그럴듯해지므로 「실시간」이라고 말해 버리고, 되풀어 읽는 스냅샷이 그 말을 뒷받침하지 못한다.
+ *
+ * 그래서 단계를 **판정식**으로 둔다. 각 단계는 시스템이 이미 내놓는 사실로만 판정되고, 선언으로
+ * 위조할 수 없다. 특히:
+ *
+ *  · **반출 관측**이 라이브의 판별식이다. 스냅샷을 되풀어 읽는 방식은 **원리적으로** 반출을 낼 수 없다
+ *    (사라진 것은 그냥 없어질 뿐이라 `OBSERVE` 만 남는다). 그러므로 「반출을 한 번이라도 접었는가」는
+ *    진짜 delta 의 증거이고, 폴링을 실시간이라 부르는 것을 막는다.
+ *  · **선언 적재량**이 예측의 판별식이다. 커널 기본값으로 돌아간 예측도 숫자를 내므로, 화면만 보면
+ *    구별되지 않는다. 그 숫자가 무엇 위에 섰는지는 `specCoverage` 만 안다.
+ *
+ * ── 이 모듈의 정수: 「모른다」를 「아니다」로도 「그렇다」로도 바꾸지 않는다 ──────────────
+ * 계측되지 않은 신호는 `null` 로 온다. `null` 은 0 이 아니다. 계측되지 않았으면 그 단계는 **달성이
+ * 아니고**, 그 사실을 `unmeasured` 로 말한다 — 신호를 배선하지 않은 채 단계를 주장할 길을 남기지
+ * 않는다. (0 으로 대체하면 「반출 0건」과 「반출을 세지 않았다」가 같아진다.)
+ *
+ * 순수 함수다(프레임워크·DB 무의존) — 증거 수집은 호출자 몫이다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLAIM_GATE = void 0;
+exports.assessStagePath = assessStagePath;
+exports.forbiddenClaims = forbiddenClaims;
+const ORDER = ['structure', 'live', 'forecast', 'closed-loop'];
+/**
+ * 증거로 단계를 판정한다.
+ *
+ * **단계는 앞선 단계를 전제한다**(구조 없이 라이브를 달성했다고 말할 수 없다). 앞이 막히면 뒤는
+ * 자기 조건을 따지지 않고 `prerequisite` 으로 막는다 — 뒤 단계의 조건을 나열하면 사람이 순서를
+ * 건너뛴다.
+ */
+function assessStagePath(e) {
+    const stages = [];
+    let prereqOk = true;
+    for (const id of ORDER) {
+        const blockedBy = [];
+        const unmeasured = [];
+        if (!prereqOk) {
+            blockedBy.push('prerequisite');
+        }
+        else if (id === 'structure') {
+            if (!(e.locationCount > 0))
+                blockedBy.push('no-locations');
+            if (!(e.itemCount > 0))
+                blockedBy.push('no-items');
+            if (e.masterWarningsApplicable !== false && e.masterWarnings === null)
+                unmeasured.push('master-warnings');
+        }
+        else if (id === 'live') {
+            if (e.subject === 'sim')
+                blockedBy.push('subject-is-simulation');
+            else {
+                if (!(e.liveIngestTotal > 0))
+                    blockedBy.push('no-ingest');
+                if (e.removalsObserved === null)
+                    unmeasured.push('removals');
+                /*
+                 * 세었는데 없다. 이유가 둘이고 **처방이 정반대**다: 스냅샷을 되풀어 읽는 방식이면 더 기다려도
+                 * 오지 않으므로 방식을 바꿔야 하고, 그 밖이면 아직 반출이 일어나지 않은 것일 수 있다.
+                 */
+                else if (e.removalsObserved === 0)
+                    blockedBy.push(e.feed === 'snapshot-poll' ? 'snapshot-only-feed' : 'no-removal-observed');
+            }
+        }
+        else if (id === 'forecast') {
+            if (!e.forecastRan)
+                blockedBy.push('no-forecast-run');
+            if (e.specCoverage === null)
+                unmeasured.push('spec-coverage');
+            /* 선언이 0 이면 예측은 커널 기본값 위에 섰다 — 숫자는 나오지만 이 현장의 숫자가 아니다. */
+            else if (!(e.specCoverage.declared > 0))
+                blockedBy.push('declarations-empty');
+        }
+        else {
+            if (!e.actuateCapability)
+                blockedBy.push('no-actuate-capability');
+            if (e.correlatedEffectObserved === null)
+                unmeasured.push('correlated-effect');
+            /* 접수만으로는 폐루프가 아니다 — 효과가 관측으로 돌아와야 닫힌다. */
+            else if (!(e.correlatedEffectObserved > 0))
+                blockedBy.push('effect-not-observed');
+        }
+        const achieved = blockedBy.length === 0 && unmeasured.length === 0;
+        stages.push({ id, achieved, blockedBy, unmeasured });
+        if (!achieved)
+            prereqOk = false;
+    }
+    const achievedIds = stages.filter(s => s.achieved).map(s => s.id);
+    const firstUnmet = stages.find(s => !s.achieved);
+    return {
+        stages,
+        reached: achievedIds.length ? achievedIds[achievedIds.length - 1] : null,
+        next: firstUnmet ? { stage: firstUnmet.id, blockedBy: firstUnmet.blockedBy, unmeasured: firstUnmet.unmeasured } : null
+    };
+}
+/**
+ * 이 단계에 이르지 못했다면 **쓰지 않기로 한 말**.
+ *
+ * 근거 수준 규율(`connector-developer-guide` §8)을 판정과 같은 자리에 둔다. 문장이 문서에만 있으면
+ * 제안서를 쓰는 사람이 그 문서를 읽지 않는다. 값이 되면 화면이 그 자리에서 말할 수 있다.
+ */
+exports.CLAIM_GATE = {
+    structure: 'claim.structure-synced',
+    live: 'claim.realtime',
+    forecast: 'claim.prediction',
+    'closed-loop': 'claim.automatic-control'
+};
+/** 아직 쓸 수 없는 주장들 — 도달하지 못한 단계의 게이트 전부. */
+function forbiddenClaims(path) {
+    return path.stages.filter(s => !s.achieved).map(s => exports.CLAIM_GATE[s.id]);
+}
+//# sourceMappingURL=stage-path.js.map

package/dist-server/engine/stage-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-path.js","sourceRoot":"","sources":["../../server/engine/stage-path.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 단계 판정 — **가벼운 성공을 최종 성공으로 잇는 길을, 사람의 체크가 아니라 증거로 센다.**\n *\n * ── 왜 이 모듈이 있나 ───────────────────────────────────────────────────────\n * 트윈 도입은 「구조 → 라이브 → 예측 → 폐루프」로 간다. 그런데 이 진행을 **체크리스트**로 관리하면\n * 사람이 체크하는 순간 참이 된다. 실제로 가장 자주 건너뛰어지는 자리가 구조 다음이다 — 구조가 서면\n * 화면이 그럴듯해지므로 「실시간」이라고 말해 버리고, 되풀어 읽는 스냅샷이 그 말을 뒷받침하지 못한다.\n *\n * 그래서 단계를 **판정식**으로 둔다. 각 단계는 시스템이 이미 내놓는 사실로만 판정되고, 선언으로\n * 위조할 수 없다. 특히:\n *\n *  · **반출 관측**이 라이브의 판별식이다. 스냅샷을 되풀어 읽는 방식은 **원리적으로** 반출을 낼 수 없다\n *    (사라진 것은 그냥 없어질 뿐이라 `OBSERVE` 만 남는다). 그러므로 「반출을 한 번이라도 접었는가」는\n *    진짜 delta 의 증거이고, 폴링을 실시간이라 부르는 것을 막는다.\n *  · **선언 적재량**이 예측의 판별식이다. 커널 기본값으로 돌아간 예측도 숫자를 내므로, 화면만 보면\n *    구별되지 않는다. 그 숫자가 무엇 위에 섰는지는 `specCoverage` 만 안다.\n *\n * ── 이 모듈의 정수: 「모른다」를 「아니다」로도 「그렇다」로도 바꾸지 않는다 ──────────────\n * 계측되지 않은 신호는 `null` 로 온다. `null` 은 0 이 아니다. 계측되지 않았으면 그 단계는 **달성이\n * 아니고**, 그 사실을 `unmeasured` 로 말한다 — 신호를 배선하지 않은 채 단계를 주장할 길을 남기지\n * 않는다. (0 으로 대체하면 「반출 0건」과 「반출을 세지 않았다」가 같아진다.)\n *\n * 순수 함수다(프레임워크·DB 무의존) — 증거 수집은 호출자 몫이다.\n */\n\nexport type StageId = 'structure' | 'live' | 'forecast' | 'closed-loop'\n\n/** 판정에 쓰는 사실. `null` = **계측되지 않았다**(0 이 아니다). */\nexport interface StageEvidence {\n  /* ── S1 구조 ── */\n  /** 이 트윈이 든 자리 수. */\n  locationCount: number\n  /** 자리에 놓인 물품 수(비직렬 수량 물품 포함 — 식품·화학은 개수가 아니라 총량으로 온다). */\n  itemCount: number\n  /**\n   * 마스터를 옮기며 **못 옮긴 값의 수**. `null` = 세지 않았다.\n   *\n   * 0 이면 통과이고 n 이어도 통과다 — 이 판정이 요구하는 것은 「없다」가 아니라 **「말할 수 있다」**다.\n   * 못 옮긴 값을 세지 않은 구조 인제스트는 도크를 랙으로 바꿔 놓고도 조용히 성공한다.\n   */\n  masterWarnings: number | null\n  /**\n   * 이 축이 이 트윈에 **해당하나**. 레퍼런스 없이 템플릿으로 세운 트윈에는 옮겨 온 마스터가 없으므로\n   * 「못 옮긴 값」을 물을 대상이 아니다 — 그걸 미측정으로 접으면 영원히 배선을 기다린다.\n   */\n  masterWarningsApplicable?: boolean\n\n  /* ── S2 라이브 ── */\n  /** 인제스트 누적 건수. */\n  liveIngestTotal: number\n  /** **반출(remove)을 접은 누적 건수.** `null` = 계측되지 않음. 0 = 세었으나 없었다(→ 스냅샷 의심). */\n  removalsObserved: number | null\n\n  /* ── S3 예측 ── */\n  /** 이 트윈에서 예측이 한 번이라도 돌았나. */\n  forecastRan: boolean\n  /** 선언 적재량 — `declared`/`total`. `null` = 알 수 없음. */\n  specCoverage: { declared: number; total: number } | null\n\n  /* ── S4 폐루프 ── */\n  /**\n   * 이 트윈이 **무엇인가** — 시뮬레이션은 원천에서 받는 것이 없다.\n   *\n   * 시뮬에 라이브를 요구하면 영원히 빨갛고, 그 빨강은 결함이 아니다. 도입 단계는 **연결된 트윈**의\n   * 축이므로 시뮬은 라이브 이후를 「해당 없음」으로 말한다(달성으로도, 미측정으로도 접지 않는다).\n   */\n  subject?: 'live' | 'sim'\n  /** 피드 성격 — `snapshot-poll` 이면 반출 0 은 「아직」이 아니라 **구조적으로 불가**다. */\n  feed?: 'push' | 'delta-poll' | 'snapshot-poll' | 'none' | 'unknown'\n  /** 원본이 **선언∩구현**으로 액추에이션 능력을 갖나(`capabilitiesOf`). */\n  actuateCapability: boolean\n  /** 내 명령의 효과가 인바운드로 **상관되어** 돌아온 누적 건수. `null` = 계측되지 않음. */\n  correlatedEffectObserved: number | null\n}\n\nexport interface StageVerdict {\n  id: StageId\n  achieved: boolean\n  /** 아직 아닌 이유 — 언어중립 코드(화면이 옮긴다). 달성이면 빈 배열. */\n  blockedBy: string[]\n  /** 판정할 수 없었던 신호 — **배선되지 않은 계측**. 있으면 달성이 아니다. */\n  unmeasured: string[]\n}\n\nexport interface StagePath {\n  stages: StageVerdict[]\n  /** 지금 서 있는 칸 — 연속으로 달성된 마지막 단계. 하나도 없으면 `null`. */\n  reached: StageId | null\n  /**\n   * 다음 한 걸음 — 사람이 오늘 할 수 있는 일 하나. 없으면(전부 달성) `null`.\n   * 「무엇이 부족한지」의 목록이 아니라 **다음 하나**다. 목록은 사람을 멈추게 한다.\n   */\n  next: { stage: StageId; blockedBy: string[]; unmeasured: string[] } | null\n}\n\nconst ORDER: StageId[] = ['structure', 'live', 'forecast', 'closed-loop']\n\n/**\n * 증거로 단계를 판정한다.\n *\n * **단계는 앞선 단계를 전제한다**(구조 없이 라이브를 달성했다고 말할 수 없다). 앞이 막히면 뒤는\n * 자기 조건을 따지지 않고 `prerequisite` 으로 막는다 — 뒤 단계의 조건을 나열하면 사람이 순서를\n * 건너뛴다.\n */\nexport function assessStagePath(e: StageEvidence): StagePath {\n  const stages: StageVerdict[] = []\n  let prereqOk = true\n\n  for (const id of ORDER) {\n    const blockedBy: string[] = []\n    const unmeasured: string[] = []\n\n    if (!prereqOk) {\n      blockedBy.push('prerequisite')\n    } else if (id === 'structure') {\n      if (!(e.locationCount > 0)) blockedBy.push('no-locations')\n      if (!(e.itemCount > 0)) blockedBy.push('no-items')\n      if (e.masterWarningsApplicable !== false && e.masterWarnings === null) unmeasured.push('master-warnings')\n    } else if (id === 'live') {\n      if (e.subject === 'sim') blockedBy.push('subject-is-simulation')\n      else {\n        if (!(e.liveIngestTotal > 0)) blockedBy.push('no-ingest')\n        if (e.removalsObserved === null) unmeasured.push('removals')\n        /*\n         * 세었는데 없다. 이유가 둘이고 **처방이 정반대**다: 스냅샷을 되풀어 읽는 방식이면 더 기다려도\n         * 오지 않으므로 방식을 바꿔야 하고, 그 밖이면 아직 반출이 일어나지 않은 것일 수 있다.\n         */\n        else if (e.removalsObserved === 0) blockedBy.push(e.feed === 'snapshot-poll' ? 'snapshot-only-feed' : 'no-removal-observed')\n      }\n    } else if (id === 'forecast') {\n      if (!e.forecastRan) blockedBy.push('no-forecast-run')\n      if (e.specCoverage === null) unmeasured.push('spec-coverage')\n      /* 선언이 0 이면 예측은 커널 기본값 위에 섰다 — 숫자는 나오지만 이 현장의 숫자가 아니다. */\n      else if (!(e.specCoverage.declared > 0)) blockedBy.push('declarations-empty')\n    } else {\n      if (!e.actuateCapability) blockedBy.push('no-actuate-capability')\n      if (e.correlatedEffectObserved === null) unmeasured.push('correlated-effect')\n      /* 접수만으로는 폐루프가 아니다 — 효과가 관측으로 돌아와야 닫힌다. */\n      else if (!(e.correlatedEffectObserved > 0)) blockedBy.push('effect-not-observed')\n    }\n\n    const achieved = blockedBy.length === 0 && unmeasured.length === 0\n    stages.push({ id, achieved, blockedBy, unmeasured })\n    if (!achieved) prereqOk = false\n  }\n\n  const achievedIds = stages.filter(s => s.achieved).map(s => s.id)\n  const firstUnmet = stages.find(s => !s.achieved)\n  return {\n    stages,\n    reached: achievedIds.length ? achievedIds[achievedIds.length - 1] : null,\n    next: firstUnmet ? { stage: firstUnmet.id, blockedBy: firstUnmet.blockedBy, unmeasured: firstUnmet.unmeasured } : null\n  }\n}\n\n/**\n * 이 단계에 이르지 못했다면 **쓰지 않기로 한 말**.\n *\n * 근거 수준 규율(`connector-developer-guide` §8)을 판정과 같은 자리에 둔다. 문장이 문서에만 있으면\n * 제안서를 쓰는 사람이 그 문서를 읽지 않는다. 값이 되면 화면이 그 자리에서 말할 수 있다.\n */\nexport const CLAIM_GATE: Record<StageId, string> = {\n  structure: 'claim.structure-synced',\n  live: 'claim.realtime',\n  forecast: 'claim.prediction',\n  'closed-loop': 'claim.automatic-control'\n}\n\n/** 아직 쓸 수 없는 주장들 — 도달하지 못한 단계의 게이트 전부. */\nexport function forbiddenClaims(path: StagePath): string[] {\n  return path.stages.filter(s => !s.achieved).map(s => CLAIM_GATE[s.id])\n}\n"]}