@things-factory/headless-twin 10.0.19 → 10.1.0

package/dist-server/service/actuation/retry-plan.d.ts

@@ -0,0 +1,63 @@
+/** 어댑터가 답하는 세 갈래. 비어 있으면 **말하지 않은 것**이고, `never` 가 아니다. */
+export type RetryOutlook = 'again' | 'after-fix' | 'never';
+export declare function isRetryOutlook(v: unknown): v is RetryOutlook;
+/**
+ * `again` 의 물러섬 — 30초 · 2분 · 10분, 그다음 접는다.
+ *
+ * 첫 값이 일꾼의 주기와 같다(§`RULE_PERIOD_MS`). 새 박자를 만들지 않는다.
+ */
+export declare const AGAIN_BACKOFF_MS: readonly [30000, 120000, 600000];
+/**
+ * `after-fix` 는 **10분마다 계속** 본다 — 접지 않는다(머리말).
+ *
+ * 사람이 설정을 고치는 것을 기다리는 간격이다. 짧게 두면 헛되고, 길게 두면 고쳐 놓고 기다린다.
+ */
+export declare const AFTER_FIX_PERIOD_MS = 600000;
+/** 왜 집지 않는가 — 목록이 「고칠 것」과 「우리 쪽을 보지 말 것」을 갈라 보이게 한다. */
+export type SkipReason = 
+/** 종착이거나 넘길 수 없는 상태다. */
+'not-dispatchable'
+/** 아직 물러섬이 끝나지 않았다 — 다음 기회를 기다린다. */
+ | 'backing-off'
+/** 어댑터가 「영원히 안 된다」고 답했다 — 사람이 **새 조치**를 내야 한다. 우리 쪽에 고칠 것이 없다. */
+ | 'never'
+/** `again` 을 세 번 다 썼다 — 사람이 봐야 한다. */
+ | 'attempts-spent'
+/** 어댑터가 다시 될 일인지 말하지 않았다 — 모르는 것을 재시도로 밀지 않는다. */
+ | 'outlook-unknown'
+/** 재시도인데 커넥터가 멱등을 선언하지 않았다 — 두 건이 설 위험을 우리가 지지 않는다. */
+ | 'not-idempotent';
+export interface RetryDecision {
+    /** 지금 넘길 것인가. */
+    take: boolean;
+    /** 안 넘기면 왜 — 목록이 그대로 보인다. */
+    skip?: SkipReason;
+    /** 넘길 것이면 이번이 몇 번째 시도인가(첫 시도가 1). */
+    attempt?: number;
+    /** 이번 시도가 실패하면 다음은 언제인가(ISO). 없으면 더 안 본다. */
+    nextAttemptAt?: string;
+}
+export interface RetryInput {
+    /** 지금 상태 — `approved` 는 첫 시도, `failed` 는 재시도. */
+    state: string;
+    /** 넘길 수 있는 상태인가 — 상태 기계가 답한다(`nextCommandState(state,'dispatch')`). */
+    dispatchable: boolean;
+    /** 어댑터가 지난 실패에 답한 갈래. 첫 시도에는 없다. */
+    retry?: string;
+    /** 지금까지 몇 번 넘겨 봤나. 없으면 0. */
+    attempts?: number;
+    /** 다음에 볼 시각(ISO). 없으면 지금 봐도 된다. */
+    nextAttemptAt?: string;
+    /** 이 커넥터가 두 번 보내도 지시가 하나인가 — **선언만 참으로 읽는다.** */
+    idempotent?: boolean;
+    /** 지금(ms). */
+    nowMs: number;
+}
+/**
+ * 이 조치를 지금 넘길 것인가.
+ *
+ * **모르면 넘기지 않는다.** 어댑터가 갈래를 말하지 않았거나 멱등을 선언하지 않았으면 재시도하지
+ * 않고 목록에 남긴다 — 오늘 커널의 다른 축에서 지킨 것과 같은 규율이다(정격 사용량·품질 계수기·
+ * 조용한 시각: 모르면 단언하지 않는다).
+ */
+export declare function retryDecisionOf(input: RetryInput): RetryDecision;

package/dist-server/service/actuation/retry-plan.js

@@ -0,0 +1,99 @@
+"use strict";
+/*
+ * **다시 넘길 것인가, 언제인가** — 일꾼이 묻는 것 하나.
+ *
+ * ── 왜 순수한가 ─────────────────────────────────────────────────────────────
+ * 일꾼의 판단이 전부 여기 있다. DB 도 어댑터도 시계도 보지 않는다 — 시각은 받는다. 그래서 「10분
+ * 뒤에 다시」 같은 규칙을 기다리지 않고 값만 바꿔 가며 잴 수 있다.
+ *
+ * ── 세 갈래는 어댑터가 답한다 ───────────────────────────────────────────────
+ * 실패가 다 같지 않다. 2026-09-02 에 둘을 겪었다 — 저쪽 인증 정보가 없어 503(고치면 됨)이었고,
+ * `ITEM-1` 은 400(고쳐도 이 조치로는 안 됨)이었다. 답만 보면 구별되지 않았다.
+ *
+ *   again       그대로 다시 해 볼 만하다      못 닿았거나 저쪽이 잠깐 흔들렸다
+ *   after-fix   사람이 고친 뒤 그대로 나간다   설정 문제
+ *   never       이 조치로는 영원히 안 된다     지시 내용이 틀렸다
+ *
+ * 가르는 자리는 **「조치를 다시 낼 필요가 있나」**다(인티그레이션 레인 판단).
+ *
+ * ── `after-fix` 를 횟수로 접지 않는다 ───────────────────────────────────────
+ * 이것이 이 파일에서 가장 중요한 결정이다. `after-fix` 는 **재시도가 아니라 기다리는 것**이다.
+ * 두드려서 풀릴 일이 아니고, 사람이 설정을 고치는 순간 다음 주기에 나가면 된다.
+ *
+ * 횟수로 접으면 **사람이 고쳐 놓고도 다시 손으로 눌러야** 한다. 2026-09-02 사고가 정확히 그
+ * 모양이었다 — 저쪽이 고쳐진 뒤 사람이 손으로 다시 넘겨서 나갔다.
+ *
+ * `again` 만 접는다. 끝없이 두드리는 것은 소음이고, 짧게 세 번 해서 안 되면 망이 흔들린 것이
+ * 아니라 다른 것이다 — 그때는 사람이 봐야 한다.
+ *
+ * ── 멱등이 첫 시도와 재시도를 가른다 ────────────────────────────────────────
+ *   approved → 넘김    **첫 시도**다. 멱등 선언이 없어도 한다 — 한 번뿐이라 위험이 없다
+ *   failed → 넘김      **재시도**다. 두 번 보내도 지시가 하나라고 선언한 커넥터만 한다
+ *
+ * 선언하지 않은 커넥터의 실패는 목록에 남는다. 사람이 저쪽 상태를 보고 결정해야 한다 — 우리가
+ * 「아마 괜찮겠지」로 두 번 보내면 현장에 지시가 두 건 선다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AFTER_FIX_PERIOD_MS = exports.AGAIN_BACKOFF_MS = void 0;
+exports.isRetryOutlook = isRetryOutlook;
+exports.retryDecisionOf = retryDecisionOf;
+function isRetryOutlook(v) {
+    return v === 'again' || v === 'after-fix' || v === 'never';
+}
+/**
+ * `again` 의 물러섬 — 30초 · 2분 · 10분, 그다음 접는다.
+ *
+ * 첫 값이 일꾼의 주기와 같다(§`RULE_PERIOD_MS`). 새 박자를 만들지 않는다.
+ */
+exports.AGAIN_BACKOFF_MS = [30_000, 120_000, 600_000];
+/**
+ * `after-fix` 는 **10분마다 계속** 본다 — 접지 않는다(머리말).
+ *
+ * 사람이 설정을 고치는 것을 기다리는 간격이다. 짧게 두면 헛되고, 길게 두면 고쳐 놓고 기다린다.
+ */
+exports.AFTER_FIX_PERIOD_MS = 600_000;
+const at = (ms) => new Date(ms).toISOString();
+/**
+ * 이 조치를 지금 넘길 것인가.
+ *
+ * **모르면 넘기지 않는다.** 어댑터가 갈래를 말하지 않았거나 멱등을 선언하지 않았으면 재시도하지
+ * 않고 목록에 남긴다 — 오늘 커널의 다른 축에서 지킨 것과 같은 규율이다(정격 사용량·품질 계수기·
+ * 조용한 시각: 모르면 단언하지 않는다).
+ */
+function retryDecisionOf(input) {
+    if (!input.dispatchable)
+        return { take: false, skip: 'not-dispatchable' };
+    const attempts = typeof input.attempts === 'number' && input.attempts > 0 ? input.attempts : 0;
+    /*
+     * **첫 시도** — 승인됐는데 한 번도 안 나간 것. 물러섬도 멱등도 묻지 않는다: 한 번뿐이라 두 건이
+     * 설 수 없고, 어댑터는 아직 아무 답도 하지 않았다.
+     *
+     * 이 갈래가 승인 직후 발신이 놓친 것을 줍는다 — 커밋과 발신 사이에 프로세스가 죽은 경우다.
+     */
+    if (attempts === 0) {
+        return { take: true, attempt: 1, nextAttemptAt: at(input.nowMs + exports.AGAIN_BACKOFF_MS[0]) };
+    }
+    /* 재시도다. 여기서부터 어댑터의 답과 커넥터의 성질을 묻는다. */
+    if (!isRetryOutlook(input.retry))
+        return { take: false, skip: 'outlook-unknown' };
+    if (input.retry === 'never')
+        return { take: false, skip: 'never' };
+    if (input.idempotent !== true)
+        return { take: false, skip: 'not-idempotent' };
+    if (input.nextAttemptAt) {
+        const dueMs = Date.parse(input.nextAttemptAt);
+        /* 읽을 수 없는 값으로 막지 않는다 — 막으면 그 조치가 표에 갇힌다. */
+        if (Number.isFinite(dueMs) && input.nowMs < dueMs)
+            return { take: false, skip: 'backing-off' };
+    }
+    if (input.retry === 'after-fix') {
+        /* 접지 않는다(머리말) — 같은 간격으로 계속 본다. */
+        return { take: true, attempt: attempts + 1, nextAttemptAt: at(input.nowMs + exports.AFTER_FIX_PERIOD_MS) };
+    }
+    /* `again` — 물러섬 표를 다 쓰면 접는다. */
+    if (attempts >= exports.AGAIN_BACKOFF_MS.length)
+        return { take: false, skip: 'attempts-spent' };
+    const next = exports.AGAIN_BACKOFF_MS[attempts];
+    return { take: true, attempt: attempts + 1, nextAttemptAt: at(input.nowMs + next) };
+}
+//# sourceMappingURL=retry-plan.js.map

package/dist-server/service/actuation/retry-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-plan.js","sourceRoot":"","sources":["../../../server/service/actuation/retry-plan.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;;;AAKH,wCAEC;AAoED,0CAoCC;AA1GD,SAAgB,cAAc,CAAC,CAAU;IACvC,OAAO,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,WAAW,IAAI,CAAC,KAAK,OAAO,CAAA;AAC5D,CAAC;AAED;;;;GAIG;AACU,QAAA,gBAAgB,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAU,CAAA;AAEnE;;;;GAIG;AACU,QAAA,mBAAmB,GAAG,OAAO,CAAA;AA6C1C,MAAM,EAAE,GAAG,CAAC,EAAU,EAAU,EAAE,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAA;AAE7D;;;;;;GAMG;AACH,SAAgB,eAAe,CAAC,KAAiB;IAC/C,IAAI,CAAC,KAAK,CAAC,YAAY;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,kBAAkB,EAAE,CAAA;IAEzE,MAAM,QAAQ,GAAG,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAA;IAE9F;;;;;OAKG;IACH,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,aAAa,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,GAAG,wBAAgB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IACzF,CAAC;IAED,uCAAuC;IACvC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAA;IACjF,IAAI,KAAK,CAAC,KAAK,KAAK,OAAO;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,CAAA;IAClE,IAAI,KAAK,CAAC,UAAU,KAAK,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAA;IAE7E,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,CAAA;QAC7C,4CAA4C;QAC5C,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,GAAG,KAAK;YAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,CAAA;IAChG,CAAC;IAED,IAAI,KAAK,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;QAChC,kCAAkC;QAClC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,GAAG,CAAC,EAAE,aAAa,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,GAAG,2BAAmB,CAAC,EAAE,CAAA;IACpG,CAAC;IAED,gCAAgC;IAChC,IAAI,QAAQ,IAAI,wBAAgB,CAAC,MAAM;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAA;IAEvF,MAAM,IAAI,GAAG,wBAAgB,CAAC,QAAQ,CAAC,CAAA;IACvC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,GAAG,CAAC,EAAE,aAAa,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,EAAE,CAAA;AACrF,CAAC","sourcesContent":["/*\n * **다시 넘길 것인가, 언제인가** — 일꾼이 묻는 것 하나.\n *\n * ── 왜 순수한가 ─────────────────────────────────────────────────────────────\n * 일꾼의 판단이 전부 여기 있다. DB 도 어댑터도 시계도 보지 않는다 — 시각은 받는다. 그래서 「10분\n * 뒤에 다시」 같은 규칙을 기다리지 않고 값만 바꿔 가며 잴 수 있다.\n *\n * ── 세 갈래는 어댑터가 답한다 ───────────────────────────────────────────────\n * 실패가 다 같지 않다. 2026-09-02 에 둘을 겪었다 — 저쪽 인증 정보가 없어 503(고치면 됨)이었고,\n * `ITEM-1` 은 400(고쳐도 이 조치로는 안 됨)이었다. 답만 보면 구별되지 않았다.\n *\n *   again       그대로 다시 해 볼 만하다      못 닿았거나 저쪽이 잠깐 흔들렸다\n *   after-fix   사람이 고친 뒤 그대로 나간다   설정 문제\n *   never       이 조치로는 영원히 안 된다     지시 내용이 틀렸다\n *\n * 가르는 자리는 **「조치를 다시 낼 필요가 있나」**다(인티그레이션 레인 판단).\n *\n * ── `after-fix` 를 횟수로 접지 않는다 ───────────────────────────────────────\n * 이것이 이 파일에서 가장 중요한 결정이다. `after-fix` 는 **재시도가 아니라 기다리는 것**이다.\n * 두드려서 풀릴 일이 아니고, 사람이 설정을 고치는 순간 다음 주기에 나가면 된다.\n *\n * 횟수로 접으면 **사람이 고쳐 놓고도 다시 손으로 눌러야** 한다. 2026-09-02 사고가 정확히 그\n * 모양이었다 — 저쪽이 고쳐진 뒤 사람이 손으로 다시 넘겨서 나갔다.\n *\n * `again` 만 접는다. 끝없이 두드리는 것은 소음이고, 짧게 세 번 해서 안 되면 망이 흔들린 것이\n * 아니라 다른 것이다 — 그때는 사람이 봐야 한다.\n *\n * ── 멱등이 첫 시도와 재시도를 가른다 ────────────────────────────────────────\n *   approved → 넘김    **첫 시도**다. 멱등 선언이 없어도 한다 — 한 번뿐이라 위험이 없다\n *   failed → 넘김      **재시도**다. 두 번 보내도 지시가 하나라고 선언한 커넥터만 한다\n *\n * 선언하지 않은 커넥터의 실패는 목록에 남는다. 사람이 저쪽 상태를 보고 결정해야 한다 — 우리가\n * 「아마 괜찮겠지」로 두 번 보내면 현장에 지시가 두 건 선다.\n */\n\n/** 어댑터가 답하는 세 갈래. 비어 있으면 **말하지 않은 것**이고, `never` 가 아니다. */\nexport type RetryOutlook = 'again' | 'after-fix' | 'never'\n\nexport function isRetryOutlook(v: unknown): v is RetryOutlook {\n  return v === 'again' || v === 'after-fix' || v === 'never'\n}\n\n/**\n * `again` 의 물러섬 — 30초 · 2분 · 10분, 그다음 접는다.\n *\n * 첫 값이 일꾼의 주기와 같다(§`RULE_PERIOD_MS`). 새 박자를 만들지 않는다.\n */\nexport const AGAIN_BACKOFF_MS = [30_000, 120_000, 600_000] as const\n\n/**\n * `after-fix` 는 **10분마다 계속** 본다 — 접지 않는다(머리말).\n *\n * 사람이 설정을 고치는 것을 기다리는 간격이다. 짧게 두면 헛되고, 길게 두면 고쳐 놓고 기다린다.\n */\nexport const AFTER_FIX_PERIOD_MS = 600_000\n\n/** 왜 집지 않는가 — 목록이 「고칠 것」과 「우리 쪽을 보지 말 것」을 갈라 보이게 한다. */\nexport type SkipReason =\n  /** 종착이거나 넘길 수 없는 상태다. */\n  | 'not-dispatchable'\n  /** 아직 물러섬이 끝나지 않았다 — 다음 기회를 기다린다. */\n  | 'backing-off'\n  /** 어댑터가 「영원히 안 된다」고 답했다 — 사람이 **새 조치**를 내야 한다. 우리 쪽에 고칠 것이 없다. */\n  | 'never'\n  /** `again` 을 세 번 다 썼다 — 사람이 봐야 한다. */\n  | 'attempts-spent'\n  /** 어댑터가 다시 될 일인지 말하지 않았다 — 모르는 것을 재시도로 밀지 않는다. */\n  | 'outlook-unknown'\n  /** 재시도인데 커넥터가 멱등을 선언하지 않았다 — 두 건이 설 위험을 우리가 지지 않는다. */\n  | 'not-idempotent'\n\nexport interface RetryDecision {\n  /** 지금 넘길 것인가. */\n  take: boolean\n  /** 안 넘기면 왜 — 목록이 그대로 보인다. */\n  skip?: SkipReason\n  /** 넘길 것이면 이번이 몇 번째 시도인가(첫 시도가 1). */\n  attempt?: number\n  /** 이번 시도가 실패하면 다음은 언제인가(ISO). 없으면 더 안 본다. */\n  nextAttemptAt?: string\n}\n\nexport interface RetryInput {\n  /** 지금 상태 — `approved` 는 첫 시도, `failed` 는 재시도. */\n  state: string\n  /** 넘길 수 있는 상태인가 — 상태 기계가 답한다(`nextCommandState(state,'dispatch')`). */\n  dispatchable: boolean\n  /** 어댑터가 지난 실패에 답한 갈래. 첫 시도에는 없다. */\n  retry?: string\n  /** 지금까지 몇 번 넘겨 봤나. 없으면 0. */\n  attempts?: number\n  /** 다음에 볼 시각(ISO). 없으면 지금 봐도 된다. */\n  nextAttemptAt?: string\n  /** 이 커넥터가 두 번 보내도 지시가 하나인가 — **선언만 참으로 읽는다.** */\n  idempotent?: boolean\n  /** 지금(ms). */\n  nowMs: number\n}\n\nconst at = (ms: number): string => new Date(ms).toISOString()\n\n/**\n * 이 조치를 지금 넘길 것인가.\n *\n * **모르면 넘기지 않는다.** 어댑터가 갈래를 말하지 않았거나 멱등을 선언하지 않았으면 재시도하지\n * 않고 목록에 남긴다 — 오늘 커널의 다른 축에서 지킨 것과 같은 규율이다(정격 사용량·품질 계수기·\n * 조용한 시각: 모르면 단언하지 않는다).\n */\nexport function retryDecisionOf(input: RetryInput): RetryDecision {\n  if (!input.dispatchable) return { take: false, skip: 'not-dispatchable' }\n\n  const attempts = typeof input.attempts === 'number' && input.attempts > 0 ? input.attempts : 0\n\n  /*\n   * **첫 시도** — 승인됐는데 한 번도 안 나간 것. 물러섬도 멱등도 묻지 않는다: 한 번뿐이라 두 건이\n   * 설 수 없고, 어댑터는 아직 아무 답도 하지 않았다.\n   *\n   * 이 갈래가 승인 직후 발신이 놓친 것을 줍는다 — 커밋과 발신 사이에 프로세스가 죽은 경우다.\n   */\n  if (attempts === 0) {\n    return { take: true, attempt: 1, nextAttemptAt: at(input.nowMs + AGAIN_BACKOFF_MS[0]) }\n  }\n\n  /* 재시도다. 여기서부터 어댑터의 답과 커넥터의 성질을 묻는다. */\n  if (!isRetryOutlook(input.retry)) return { take: false, skip: 'outlook-unknown' }\n  if (input.retry === 'never') return { take: false, skip: 'never' }\n  if (input.idempotent !== true) return { take: false, skip: 'not-idempotent' }\n\n  if (input.nextAttemptAt) {\n    const dueMs = Date.parse(input.nextAttemptAt)\n    /* 읽을 수 없는 값으로 막지 않는다 — 막으면 그 조치가 표에 갇힌다. */\n    if (Number.isFinite(dueMs) && input.nowMs < dueMs) return { take: false, skip: 'backing-off' }\n  }\n\n  if (input.retry === 'after-fix') {\n    /* 접지 않는다(머리말) — 같은 간격으로 계속 본다. */\n    return { take: true, attempt: attempts + 1, nextAttemptAt: at(input.nowMs + AFTER_FIX_PERIOD_MS) }\n  }\n\n  /* `again` — 물러섬 표를 다 쓰면 접는다. */\n  if (attempts >= AGAIN_BACKOFF_MS.length) return { take: false, skip: 'attempts-spent' }\n\n  const next = AGAIN_BACKOFF_MS[attempts]\n  return { take: true, attempt: attempts + 1, nextAttemptAt: at(input.nowMs + next) }\n}\n"]}

package/dist-server/service/actuation/rule-evaluate.d.ts

@@ -0,0 +1,127 @@
+import type { CommandTypeSpec } from '@operato/ops-contract';
+/** 어느 주의에 어느 지시를 붙이는가 — 선언 한 줄. */
+export interface ActuationRuleSpec {
+    id: string;
+    /** 이 트윈에만 적용된다. 트윈마다 라인이 다르므로 전역 규칙은 두지 않는다. */
+    instanceId: string;
+    /** 어느 주의인가 — 커널의 안정 코드(`Attention.kind`). */
+    attentionKind: string;
+    /** 이 심각도 이상일 때만 — 없으면 종류만 본다. */
+    minSeverity?: 'low' | 'medium' | 'high' | 'critical';
+    /**
+     * **조건이 이만큼 이어졌을 때** 올린다.
+     *
+     * 없으면 처음 본 주기에 바로 올린다. 깜빡이는 조건에 현장 지시가 나가는 것을 막으려면 이 값이 필요하다
+     * — 커널이 조건이 처음 성립한 시각을 기억하므로(`Attention.timeStamp`) 여기서 잴 수 있다.
+     */
+    minHeldMs?: number;
+    /** 무엇을 내는가 — 선언된 조치 종류(`CommandTypeSpec.type`). 커널 자극이 아니다. */
+    commandType: string;
+    /**
+     * 지시의 내용 — `{이름}` 을 주의의 값으로 바꿔 넣는다.
+     *
+     * 바꿀 값은 `Attention.params` 와 `anchor` 에서 온다(`{locationId}` · `{ratioPct}`). 한 겹 중괄호를
+     * 쓰는 것은 이 저장소의 i18n 관례와 같다.
+     *
+     * 바꿀 것이 없으면 **그 자리를 비운다** — 지어낸 값을 넣지 않는다. 요구하는 칸이 비면 계약이 거절하고
+     * (§`missingCommandPayload`) 그 거절이 사람에게 전해진다.
+     */
+    payloadTemplate?: Record<string, unknown>;
+    /**
+     * **한 번 낸 근거에 다시 내기까지 기다리는 시간.**
+     *
+     * 이것이 없으면 승인하는 순간 규칙이 같은 것을 또 낸다 — 실제로 그랬다. 「결정을 기다리는 것」만 보고
+     * 중복을 막았는데, 승인하면 그 커맨드가 대기에서 빠지고 조건은 그대로 서 있기 때문이다. 사람이
+     * 승인할수록 대기 줄이 다시 차는 모양이 된다.
+     *
+     * 조건은 이어지는 것이고 조치는 시간이 걸린다. 낸 조치가 효과를 낼 때까지 기다리는 시간이 이 값이다.
+     */
+    cooldownMs?: number;
+    /** 꺼 둔 규칙은 판정하지 않는다. 지우지 않고 끌 수 있어야 한다. */
+    enabled?: boolean;
+}
+/** 판정에 들어가는 주의 — 커널이 낸 모양 그대로 중 필요한 것만. */
+export interface AttentionLike {
+    id: string;
+    kind: string;
+    severity: string;
+    state?: string;
+    anchor?: {
+        locationId?: string;
+        moverId?: string;
+        orderId?: string;
+        operation?: string;
+    };
+    timeStamp?: string;
+    params?: Record<string, string | number>;
+}
+/** 올릴 것 하나. */
+export interface RuleProposal {
+    ruleId: string;
+    attentionId: string;
+    attentionKind: string;
+    commandType: string;
+    payload: Record<string, unknown>;
+}
+/** 올리지 않은 것과 그 이유 — **말하지 않으면 사람은 규칙이 도는 줄 안다.** */
+export interface RuleSkip {
+    ruleId: string;
+    attentionId?: string;
+    reason: string;
+}
+export interface RuleVerdict {
+    proposals: RuleProposal[];
+    /** 왜 안 올렸나. 조용히 넘어가지 않는다. */
+    skips: RuleSkip[];
+    /** 상한에 닿아 잘랐나 — 잘랐으면 몇 개를 두고 왔나. */
+    withheld?: number;
+}
+/**
+ * 이번에 무엇을 올릴지 정한다 — **순수 함수**. 저장소도 시계도 보지 않는다.
+ *
+ * 시험이 재기동과 상한과 중복을 다 걸을 수 있어야 하고, 그러려면 이 판정이 밖에서 값을 받아야 한다.
+ * 이 저장소에서 가장 자주 나는 결함이 「자리는 있고 길이 없다」이고, 게이트에 물리는 것이므로 여기서
+ * 나면 결과가 현장의 지시다.
+ */
+export declare function evaluateRules(args: {
+    rules: readonly ActuationRuleSpec[];
+    attentions: readonly AttentionLike[];
+    /** 선언된 조치 종류 — 없는 종류를 가리키는 규칙은 여기서 걸린다. */
+    specs: readonly CommandTypeSpec[];
+    /**
+     * **이미 다루고 있는 근거들** — 근거마다 마지막으로 조치를 낸 시각.
+     *
+     * 결정을 기다리는 것만 보면 부족하다. 승인하는 순간 그 커맨드가 대기에서 빠지고 조건은 그대로
+     * 서 있어서, 다음 바퀴가 같은 것을 또 낸다 — 걸어 보고 그 상태를 실제로 만들었다.
+     *
+     * 그래서 **낸 시각**을 받는다. 결정을 기다리는 것은 시각과 무관하게 막는다(§`openCauses`).
+     * 저장소에서 읽어 넘긴다 — 프로세스 기억에 두면 재기동이 곧 중복이 된다.
+     */
+    openCauses: ReadonlySet<string>;
+    /** 근거 → 마지막으로 조치를 낸 시각(ms). 없으면 낸 적이 없다. */
+    lastProposedAt?: ReadonlyMap<string, number>;
+    /** 지금 — 조건이 얼마나 이어졌는지 재는 기준. */
+    nowMs: number;
+    /** 한 번에 몇 개까지 올리나. 넘는 것은 두고 오고, 두고 온 수를 말한다. */
+    maxPerRun?: number;
+}): RuleVerdict;
+/** 한 번에 올리는 상한 — 사람이 읽을 수 있는 수. 읽지 않는 대기 줄은 게이트가 아니다. */
+export declare const DEFAULT_MAX_PER_RUN = 20;
+/**
+ * 같은 근거에 다시 내기까지 — **선언하지 않아도 기다린다.**
+ *
+ * 기본을 0 으로 두면 선언하지 않은 규칙이 승인할 때마다 같은 것을 또 낸다. 그 결함을 기본값으로 두지
+ * 않는다. 더 빨리 내야 하는 규칙은 스스로 짧게 적는다.
+ */
+export declare const DEFAULT_COOLDOWN_MS: number;
+/**
+ * 이 규칙이 낼 수 있는 종류인가 — **판정이 한 자리에만 있게.**
+ *
+ * 저장할 때와 돌 때가 같은 것을 봐야 한다. 두 벌이면 저장은 되는데 안 도는 규칙이 생기고, 사람은 규칙이
+ * 걸린 줄로 읽는다.
+ *
+ * `stimuli` 를 받는 이유: 커널 자극(`CMD`)을 적었을 때 **왜 안 되는지**를 말하려면 그 어휘를 알아야 한다.
+ * 「선언되지 않았다」로만 답하면 부르는 쪽은 선언이 빠진 줄로 읽고 선언을 추가한다 — 그 순간 모델 안의
+ * 자극이 현장 지시가 된다.
+ */
+export declare function commandTypeGap(commandType: string, specs: readonly CommandTypeSpec[], stimuli?: readonly string[]): string | undefined;

package/dist-server/service/actuation/rule-evaluate.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_COOLDOWN_MS = exports.DEFAULT_MAX_PER_RUN = void 0;
+exports.evaluateRules = evaluateRules;
+exports.commandTypeGap = commandTypeGap;
+const SEVERITY_ORDER = ['low', 'medium', 'high', 'critical'];
+/** 심각도가 문턱에 닿나 — 모르는 값은 닿지 않는 것으로 본다(모름을 통과로 읽지 않는다). */
+function severityMeets(actual, min) {
+    if (!min)
+        return true;
+    const a = SEVERITY_ORDER.indexOf(actual);
+    const m = SEVERITY_ORDER.indexOf(min);
+    if (a < 0 || m < 0)
+        return false;
+    return a >= m;
+}
+/**
+ * `{이름}` 을 바꿔 넣는다 — 바꿀 값이 없으면 **그 칸을 뺀다.**
+ *
+ * 원래 문자열을 그대로 두면 `{quantity}` 같은 글자가 지시의 수량으로 들어가고, 그 지시가 현장에 나간다.
+ * 빼면 계약이 「요구하는 칸이 없다」로 거절하고 그 거절이 사람에게 전해진다.
+ */
+function fill(template, values) {
+    const payload = {};
+    const missing = [];
+    if (!template)
+        return { payload, missing };
+    for (const [key, raw] of Object.entries(template)) {
+        if (typeof raw !== 'string') {
+            payload[key] = raw;
+            continue;
+        }
+        /* 값 하나를 그대로 나르는 자리 — 수를 문자열로 만들지 않는다(수량이 문자열이면 계산이 무너진다). */
+        const whole = /^\{([A-Za-z0-9_.]+)\}$/.exec(raw);
+        if (whole) {
+            const name = whole[1];
+            if (!(name in values)) {
+                missing.push(name);
+                continue;
+            }
+            payload[key] = values[name];
+            continue;
+        }
+        let gap = false;
+        const text = raw.replace(/\{([A-Za-z0-9_.]+)\}/g, (_m, name) => {
+            if (name in values)
+                return String(values[name]);
+            missing.push(name);
+            gap = true;
+            return '';
+        });
+        if (!gap)
+            payload[key] = text;
+    }
+    return { payload, missing };
+}
+/** 바꿔 넣을 값 — 주의의 `params` 와 `anchor` 에서. */
+function valuesOf(attention) {
+    const out = { ...(attention.params ?? {}) };
+    for (const [key, value] of Object.entries(attention.anchor ?? {})) {
+        if (value !== undefined && value !== null && value !== '')
+            out[key] = value;
+    }
+    out.attentionId = attention.id;
+    out.attentionKind = attention.kind;
+    return out;
+}
+/**
+ * 이번에 무엇을 올릴지 정한다 — **순수 함수**. 저장소도 시계도 보지 않는다.
+ *
+ * 시험이 재기동과 상한과 중복을 다 걸을 수 있어야 하고, 그러려면 이 판정이 밖에서 값을 받아야 한다.
+ * 이 저장소에서 가장 자주 나는 결함이 「자리는 있고 길이 없다」이고, 게이트에 물리는 것이므로 여기서
+ * 나면 결과가 현장의 지시다.
+ */
+function evaluateRules(args) {
+    const { rules, attentions, specs, openCauses, nowMs } = args;
+    const maxPerRun = args.maxPerRun ?? exports.DEFAULT_MAX_PER_RUN;
+    const proposals = [];
+    const skips = [];
+    let withheld = 0;
+    /* 한 주의에 규칙이 둘 붙어 있어도 조치는 하나만 올린다 — 같은 조건에 두 지시가 나가면 현장이 두 번 움직인다. */
+    const claimed = new Set(openCauses);
+    for (const rule of rules) {
+        if (rule.enabled === false)
+            continue;
+        const gap = commandTypeGap(rule.commandType, specs);
+        if (gap) {
+            skips.push({ ruleId: rule.id, reason: gap });
+            continue;
+        }
+        const spec = specs.find(s => s.type === rule.commandType);
+        for (const attention of attentions) {
+            if (attention.kind !== rule.attentionKind)
+                continue;
+            /* 확인된 것과 사라진 것에는 올리지 않는다 — 사람이 이미 본 것이다. */
+            if (attention.state && attention.state !== 'active')
+                continue;
+            if (!severityMeets(attention.severity, rule.minSeverity))
+                continue;
+            if (claimed.has(attention.id))
+                continue;
+            /*
+             * 낸 지 얼마 안 됐으면 기다린다. 조건은 이어지는 것이고 조치는 시간이 걸린다 — 효과를 보기 전에
+             * 또 내면 대기 줄이 같은 지시로 찬다.
+             */
+            const lastAt = args.lastProposedAt?.get(attention.id);
+            const cooldown = rule.cooldownMs ?? exports.DEFAULT_COOLDOWN_MS;
+            if (lastAt !== undefined && cooldown > 0 && nowMs - lastAt < cooldown)
+                continue;
+            const held = heldMs(attention, nowMs);
+            if (rule.minHeldMs && rule.minHeldMs > 0) {
+                if (held === undefined) {
+                    /*
+                     * 언제부터인지 모르는 주의다. **모름을 「충분히 오래됐다」로 읽지 않는다** — 그렇게 읽으면
+                     * 방금 생긴 깜빡임에 현장 지시가 나간다.
+                     */
+                    skips.push({
+                        ruleId: rule.id,
+                        attentionId: attention.id,
+                        reason: `이 주의는 언제부터인지 말하지 않는다 — ${rule.minHeldMs}ms 이어졌는지 알 수 없어 올리지 않았다`
+                    });
+                    continue;
+                }
+                if (held < rule.minHeldMs)
+                    continue;
+            }
+            if (proposals.length >= maxPerRun) {
+                withheld++;
+                continue;
+            }
+            const { payload, missing } = fill(rule.payloadTemplate, valuesOf(attention));
+            if (missing.length) {
+                skips.push({
+                    ruleId: rule.id,
+                    attentionId: attention.id,
+                    reason: `지시에 넣을 값이 주의에 없다 (${[...new Set(missing)].join(', ')}) — 지어낸 값으로 현장 지시를 만들지 않았다`
+                });
+                continue;
+            }
+            const gaps = missingRequired(spec, payload);
+            if (gaps.length) {
+                skips.push({
+                    ruleId: rule.id,
+                    attentionId: attention.id,
+                    reason: `지시가 요구하는 칸이 비었다 (${gaps.join(', ')}) — 무엇을 지시하는지 모르면 승인할 근거가 없다`
+                });
+                continue;
+            }
+            claimed.add(attention.id);
+            proposals.push({
+                ruleId: rule.id,
+                attentionId: attention.id,
+                attentionKind: attention.kind,
+                commandType: rule.commandType,
+                payload
+            });
+        }
+    }
+    return { proposals, skips, ...(withheld ? { withheld } : {}) };
+}
+/** 한 번에 올리는 상한 — 사람이 읽을 수 있는 수. 읽지 않는 대기 줄은 게이트가 아니다. */
+exports.DEFAULT_MAX_PER_RUN = 20;
+/**
+ * 같은 근거에 다시 내기까지 — **선언하지 않아도 기다린다.**
+ *
+ * 기본을 0 으로 두면 선언하지 않은 규칙이 승인할 때마다 같은 것을 또 낸다. 그 결함을 기본값으로 두지
+ * 않는다. 더 빨리 내야 하는 규칙은 스스로 짧게 적는다.
+ */
+exports.DEFAULT_COOLDOWN_MS = 60 * 60_000;
+/**
+ * 이 규칙이 낼 수 있는 종류인가 — **판정이 한 자리에만 있게.**
+ *
+ * 저장할 때와 돌 때가 같은 것을 봐야 한다. 두 벌이면 저장은 되는데 안 도는 규칙이 생기고, 사람은 규칙이
+ * 걸린 줄로 읽는다.
+ *
+ * `stimuli` 를 받는 이유: 커널 자극(`CMD`)을 적었을 때 **왜 안 되는지**를 말하려면 그 어휘를 알아야 한다.
+ * 「선언되지 않았다」로만 답하면 부르는 쪽은 선언이 빠진 줄로 읽고 선언을 추가한다 — 그 순간 모델 안의
+ * 자극이 현장 지시가 된다.
+ */
+function commandTypeGap(commandType, specs, stimuli) {
+    if (specs.some(s => s.type === commandType))
+        return undefined;
+    if (stimuli?.includes(commandType)) {
+        return (`그것은 커널 안에서 도는 자극이다 (${commandType}) — 현장에 나가는 지시가 아니다. ` +
+            '모델 상태를 바꾸려면 커널에 자극을 넣고, 현장에 무언가를 시키려면 그 지시를 조치 종류로 선언한다');
+    }
+    return `선언되지 않은 조치 종류를 가리킨다 (${commandType}) — 선언된 것: ${specs.map(s => s.type).join(', ') || '(없음)'}`;
+}
+/** 조건이 얼마나 이어졌나 — 모르면 `undefined`(0 이 아니다). */
+function heldMs(attention, nowMs) {
+    if (!attention.timeStamp)
+        return undefined;
+    const at = Date.parse(attention.timeStamp);
+    if (!Number.isFinite(at))
+        return undefined;
+    return Math.max(0, nowMs - at);
+}
+/** 계약의 요구를 그대로 본다 — 판정을 여기서 다시 쓰지 않는다. */
+function missingRequired(spec, payload) {
+    return (spec.required ?? []).filter(key => {
+        const v = payload[key];
+        return v === undefined || v === null || v === '';
+    });
+}
+//# sourceMappingURL=rule-evaluate.js.map

package/dist-server/service/actuation/rule-evaluate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-evaluate.js","sourceRoot":"","sources":["../../../server/service/actuation/rule-evaluate.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * **관측에서 조치를 낸다** — 그 판정 하나.\n *\n * ── 무엇이 없었나 (2026-09-01) ───────────────────────────────────────────\n * 승인 게이트를 세우고 나니 **낼 수 있는 것이 사람뿐**이었다. 계약은 낸 쪽을 네 가지로 두는데\n * (`operator` · `rule` · `ai` · `schedule`) 사람 말고는 길이 없었다. 게이트의 값어치는 트윈이 스스로\n * 알아챈 것을 사람이 판단하는 데 있는데, 알아챈 것을 올릴 자리가 없었다.\n *\n * ── 조건을 새로 만들지 않는다 ────────────────────────────────────────────\n * 커널이 이미 상태에서 「봐야 할 것」을 판단해 `Attention` 으로 낸다 — 안정된 종류 코드(`kind`),\n * 무엇에 대한 것인지(`anchor`), 언제부터인지(`timeStamp`), 표현용 값(`params`). 조건 언어를 새로 만들면\n * 같은 판단이 두 벌이 되고, 한쪽만 고쳐지는 날이 온다.\n *\n * 그래서 규칙은 **어느 주의에 어느 지시를 붙이는가**만 정한다.\n *\n * ── 자극과 지시를 잇지 않는다 ────────────────────────────────────────────\n * 주의에는 `suggestedAction.command` 가 실려 있지만 그것은 **커널 안에서 도는 자극**이다\n * (`resource.repair` = 모델에서 수리된 것으로 둔다). 여기서 내는 것은 현장에 나가는 지시다. 그 값을\n * 그대로 쓰면 「모델을 그렇게 두라」가 「사람을 보내라」가 된다(§`propose` 의 거절).\n *\n * ── 무너지는 것 넷 ───────────────────────────────────────────────────────\n * 행복한 길은 짧다. 실제로 무너지는 것은 이것들이다.\n *\n *   같은 조건이 매 주기 다시 올라온다   대기 줄에 같은 지시가 수십 개 선다\n *   방금 생긴 조건에 바로 올린다        깜빡인 것에 현장 지시가 나간다\n *   조건이 사라진 뒤에도 대기에 남는다  승인하는 사람이 없는 문제를 판단한다\n *   한 번에 수백 개가 올라온다          사람이 읽을 수 없고, 읽지 않으면 게이트가 시늉이 된다\n *\n * 넷 다 오류가 나지 않는다. 그래서 이 파일이 넷을 다룬다.\n */\nimport type { CommandTypeSpec } from '@operato/ops-contract'\n\n/** 어느 주의에 어느 지시를 붙이는가 — 선언 한 줄. */\nexport interface ActuationRuleSpec {\n  id: string\n  /** 이 트윈에만 적용된다. 트윈마다 라인이 다르므로 전역 규칙은 두지 않는다. */\n  instanceId: string\n  /** 어느 주의인가 — 커널의 안정 코드(`Attention.kind`). */\n  attentionKind: string\n  /** 이 심각도 이상일 때만 — 없으면 종류만 본다. */\n  minSeverity?: 'low' | 'medium' | 'high' | 'critical'\n  /**\n   * **조건이 이만큼 이어졌을 때** 올린다.\n   *\n   * 없으면 처음 본 주기에 바로 올린다. 깜빡이는 조건에 현장 지시가 나가는 것을 막으려면 이 값이 필요하다\n   * — 커널이 조건이 처음 성립한 시각을 기억하므로(`Attention.timeStamp`) 여기서 잴 수 있다.\n   */\n  minHeldMs?: number\n  /** 무엇을 내는가 — 선언된 조치 종류(`CommandTypeSpec.type`). 커널 자극이 아니다. */\n  commandType: string\n  /**\n   * 지시의 내용 — `{이름}` 을 주의의 값으로 바꿔 넣는다.\n   *\n   * 바꿀 값은 `Attention.params` 와 `anchor` 에서 온다(`{locationId}` · `{ratioPct}`). 한 겹 중괄호를\n   * 쓰는 것은 이 저장소의 i18n 관례와 같다.\n   *\n   * 바꿀 것이 없으면 **그 자리를 비운다** — 지어낸 값을 넣지 않는다. 요구하는 칸이 비면 계약이 거절하고\n   * (§`missingCommandPayload`) 그 거절이 사람에게 전해진다.\n   */\n  payloadTemplate?: Record<string, unknown>\n  /**\n   * **한 번 낸 근거에 다시 내기까지 기다리는 시간.**\n   *\n   * 이것이 없으면 승인하는 순간 규칙이 같은 것을 또 낸다 — 실제로 그랬다. 「결정을 기다리는 것」만 보고\n   * 중복을 막았는데, 승인하면 그 커맨드가 대기에서 빠지고 조건은 그대로 서 있기 때문이다. 사람이\n   * 승인할수록 대기 줄이 다시 차는 모양이 된다.\n   *\n   * 조건은 이어지는 것이고 조치는 시간이 걸린다. 낸 조치가 효과를 낼 때까지 기다리는 시간이 이 값이다.\n   */\n  cooldownMs?: number\n  /** 꺼 둔 규칙은 판정하지 않는다. 지우지 않고 끌 수 있어야 한다. */\n  enabled?: boolean\n}\n\n/** 판정에 들어가는 주의 — 커널이 낸 모양 그대로 중 필요한 것만. */\nexport interface AttentionLike {\n  id: string\n  kind: string\n  severity: string\n  state?: string\n  anchor?: { locationId?: string; moverId?: string; orderId?: string; operation?: string }\n  timeStamp?: string\n  params?: Record<string, string | number>\n}\n\n/** 올릴 것 하나. */\nexport interface RuleProposal {\n  ruleId: string\n  attentionId: string\n  attentionKind: string\n  commandType: string\n  payload: Record<string, unknown>\n}\n\n/** 올리지 않은 것과 그 이유 — **말하지 않으면 사람은 규칙이 도는 줄 안다.** */\nexport interface RuleSkip {\n  ruleId: string\n  attentionId?: string\n  reason: string\n}\n\nexport interface RuleVerdict {\n  proposals: RuleProposal[]\n  /** 왜 안 올렸나. 조용히 넘어가지 않는다. */\n  skips: RuleSkip[]\n  /** 상한에 닿아 잘랐나 — 잘랐으면 몇 개를 두고 왔나. */\n  withheld?: number\n}\n\nconst SEVERITY_ORDER = ['low', 'medium', 'high', 'critical'] as const\n\n/** 심각도가 문턱에 닿나 — 모르는 값은 닿지 않는 것으로 본다(모름을 통과로 읽지 않는다). */\nfunction severityMeets(actual: string, min: string | undefined): boolean {\n  if (!min) return true\n  const a = SEVERITY_ORDER.indexOf(actual as any)\n  const m = SEVERITY_ORDER.indexOf(min as any)\n  if (a < 0 || m < 0) return false\n  return a >= m\n}\n\n/**\n * `{이름}` 을 바꿔 넣는다 — 바꿀 값이 없으면 **그 칸을 뺀다.**\n *\n * 원래 문자열을 그대로 두면 `{quantity}` 같은 글자가 지시의 수량으로 들어가고, 그 지시가 현장에 나간다.\n * 빼면 계약이 「요구하는 칸이 없다」로 거절하고 그 거절이 사람에게 전해진다.\n */\nfunction fill(template: Record<string, unknown> | undefined, values: Record<string, string | number>): {\n  payload: Record<string, unknown>\n  missing: string[]\n} {\n  const payload: Record<string, unknown> = {}\n  const missing: string[] = []\n  if (!template) return { payload, missing }\n\n  for (const [key, raw] of Object.entries(template)) {\n    if (typeof raw !== 'string') {\n      payload[key] = raw\n      continue\n    }\n\n    /* 값 하나를 그대로 나르는 자리 — 수를 문자열로 만들지 않는다(수량이 문자열이면 계산이 무너진다). */\n    const whole = /^\\{([A-Za-z0-9_.]+)\\}$/.exec(raw)\n    if (whole) {\n      const name = whole[1]!\n      if (!(name in values)) {\n        missing.push(name)\n        continue\n      }\n      payload[key] = values[name]\n      continue\n    }\n\n    let gap = false\n    const text = raw.replace(/\\{([A-Za-z0-9_.]+)\\}/g, (_m, name: string) => {\n      if (name in values) return String(values[name])\n      missing.push(name)\n      gap = true\n      return ''\n    })\n    if (!gap) payload[key] = text\n  }\n\n  return { payload, missing }\n}\n\n/** 바꿔 넣을 값 — 주의의 `params` 와 `anchor` 에서. */\nfunction valuesOf(attention: AttentionLike): Record<string, string | number> {\n  const out: Record<string, string | number> = { ...(attention.params ?? {}) }\n  for (const [key, value] of Object.entries(attention.anchor ?? {})) {\n    if (value !== undefined && value !== null && value !== '') out[key] = value as string\n  }\n  out.attentionId = attention.id\n  out.attentionKind = attention.kind\n  return out\n}\n\n/**\n * 이번에 무엇을 올릴지 정한다 — **순수 함수**. 저장소도 시계도 보지 않는다.\n *\n * 시험이 재기동과 상한과 중복을 다 걸을 수 있어야 하고, 그러려면 이 판정이 밖에서 값을 받아야 한다.\n * 이 저장소에서 가장 자주 나는 결함이 「자리는 있고 길이 없다」이고, 게이트에 물리는 것이므로 여기서\n * 나면 결과가 현장의 지시다.\n */\nexport function evaluateRules(args: {\n  rules: readonly ActuationRuleSpec[]\n  attentions: readonly AttentionLike[]\n  /** 선언된 조치 종류 — 없는 종류를 가리키는 규칙은 여기서 걸린다. */\n  specs: readonly CommandTypeSpec[]\n  /**\n   * **이미 다루고 있는 근거들** — 근거마다 마지막으로 조치를 낸 시각.\n   *\n   * 결정을 기다리는 것만 보면 부족하다. 승인하는 순간 그 커맨드가 대기에서 빠지고 조건은 그대로\n   * 서 있어서, 다음 바퀴가 같은 것을 또 낸다 — 걸어 보고 그 상태를 실제로 만들었다.\n   *\n   * 그래서 **낸 시각**을 받는다. 결정을 기다리는 것은 시각과 무관하게 막는다(§`openCauses`).\n   * 저장소에서 읽어 넘긴다 — 프로세스 기억에 두면 재기동이 곧 중복이 된다.\n   */\n  openCauses: ReadonlySet<string>\n  /** 근거 → 마지막으로 조치를 낸 시각(ms). 없으면 낸 적이 없다. */\n  lastProposedAt?: ReadonlyMap<string, number>\n  /** 지금 — 조건이 얼마나 이어졌는지 재는 기준. */\n  nowMs: number\n  /** 한 번에 몇 개까지 올리나. 넘는 것은 두고 오고, 두고 온 수를 말한다. */\n  maxPerRun?: number\n}): RuleVerdict {\n  const { rules, attentions, specs, openCauses, nowMs } = args\n  const maxPerRun = args.maxPerRun ?? DEFAULT_MAX_PER_RUN\n\n  const proposals: RuleProposal[] = []\n  const skips: RuleSkip[] = []\n  let withheld = 0\n\n  /* 한 주의에 규칙이 둘 붙어 있어도 조치는 하나만 올린다 — 같은 조건에 두 지시가 나가면 현장이 두 번 움직인다. */\n  const claimed = new Set<string>(openCauses)\n\n  for (const rule of rules) {\n    if (rule.enabled === false) continue\n\n    const gap = commandTypeGap(rule.commandType, specs)\n    if (gap) {\n      skips.push({ ruleId: rule.id, reason: gap })\n      continue\n    }\n    const spec = specs.find(s => s.type === rule.commandType)!\n\n    for (const attention of attentions) {\n      if (attention.kind !== rule.attentionKind) continue\n\n      /* 확인된 것과 사라진 것에는 올리지 않는다 — 사람이 이미 본 것이다. */\n      if (attention.state && attention.state !== 'active') continue\n\n      if (!severityMeets(attention.severity, rule.minSeverity)) continue\n\n      if (claimed.has(attention.id)) continue\n\n      /*\n       * 낸 지 얼마 안 됐으면 기다린다. 조건은 이어지는 것이고 조치는 시간이 걸린다 — 효과를 보기 전에\n       * 또 내면 대기 줄이 같은 지시로 찬다.\n       */\n      const lastAt = args.lastProposedAt?.get(attention.id)\n      const cooldown = rule.cooldownMs ?? DEFAULT_COOLDOWN_MS\n      if (lastAt !== undefined && cooldown > 0 && nowMs - lastAt < cooldown) continue\n\n      const held = heldMs(attention, nowMs)\n      if (rule.minHeldMs && rule.minHeldMs > 0) {\n        if (held === undefined) {\n          /*\n           * 언제부터인지 모르는 주의다. **모름을 「충분히 오래됐다」로 읽지 않는다** — 그렇게 읽으면\n           * 방금 생긴 깜빡임에 현장 지시가 나간다.\n           */\n          skips.push({\n            ruleId: rule.id,\n            attentionId: attention.id,\n            reason: `이 주의는 언제부터인지 말하지 않는다 — ${rule.minHeldMs}ms 이어졌는지 알 수 없어 올리지 않았다`\n          })\n          continue\n        }\n        if (held < rule.minHeldMs) continue\n      }\n\n      if (proposals.length >= maxPerRun) {\n        withheld++\n        continue\n      }\n\n      const { payload, missing } = fill(rule.payloadTemplate, valuesOf(attention))\n      if (missing.length) {\n        skips.push({\n          ruleId: rule.id,\n          attentionId: attention.id,\n          reason: `지시에 넣을 값이 주의에 없다 (${[...new Set(missing)].join(', ')}) — 지어낸 값으로 현장 지시를 만들지 않았다`\n        })\n        continue\n      }\n\n      const gaps = missingRequired(spec, payload)\n      if (gaps.length) {\n        skips.push({\n          ruleId: rule.id,\n          attentionId: attention.id,\n          reason: `지시가 요구하는 칸이 비었다 (${gaps.join(', ')}) — 무엇을 지시하는지 모르면 승인할 근거가 없다`\n        })\n        continue\n      }\n\n      claimed.add(attention.id)\n      proposals.push({\n        ruleId: rule.id,\n        attentionId: attention.id,\n        attentionKind: attention.kind,\n        commandType: rule.commandType,\n        payload\n      })\n    }\n  }\n\n  return { proposals, skips, ...(withheld ? { withheld } : {}) }\n}\n\n/** 한 번에 올리는 상한 — 사람이 읽을 수 있는 수. 읽지 않는 대기 줄은 게이트가 아니다. */\nexport const DEFAULT_MAX_PER_RUN = 20\n\n/**\n * 같은 근거에 다시 내기까지 — **선언하지 않아도 기다린다.**\n *\n * 기본을 0 으로 두면 선언하지 않은 규칙이 승인할 때마다 같은 것을 또 낸다. 그 결함을 기본값으로 두지\n * 않는다. 더 빨리 내야 하는 규칙은 스스로 짧게 적는다.\n */\nexport const DEFAULT_COOLDOWN_MS = 60 * 60_000\n\n/**\n * 이 규칙이 낼 수 있는 종류인가 — **판정이 한 자리에만 있게.**\n *\n * 저장할 때와 돌 때가 같은 것을 봐야 한다. 두 벌이면 저장은 되는데 안 도는 규칙이 생기고, 사람은 규칙이\n * 걸린 줄로 읽는다.\n *\n * `stimuli` 를 받는 이유: 커널 자극(`CMD`)을 적었을 때 **왜 안 되는지**를 말하려면 그 어휘를 알아야 한다.\n * 「선언되지 않았다」로만 답하면 부르는 쪽은 선언이 빠진 줄로 읽고 선언을 추가한다 — 그 순간 모델 안의\n * 자극이 현장 지시가 된다.\n */\nexport function commandTypeGap(\n  commandType: string,\n  specs: readonly CommandTypeSpec[],\n  stimuli?: readonly string[]\n): string | undefined {\n  if (specs.some(s => s.type === commandType)) return undefined\n\n  if (stimuli?.includes(commandType)) {\n    return (\n      `그것은 커널 안에서 도는 자극이다 (${commandType}) — 현장에 나가는 지시가 아니다. ` +\n      '모델 상태를 바꾸려면 커널에 자극을 넣고, 현장에 무언가를 시키려면 그 지시를 조치 종류로 선언한다'\n    )\n  }\n\n  return `선언되지 않은 조치 종류를 가리킨다 (${commandType}) — 선언된 것: ${specs.map(s => s.type).join(', ') || '(없음)'}`\n}\n\n/** 조건이 얼마나 이어졌나 — 모르면 `undefined`(0 이 아니다). */\nfunction heldMs(attention: AttentionLike, nowMs: number): number | undefined {\n  if (!attention.timeStamp) return undefined\n  const at = Date.parse(attention.timeStamp)\n  if (!Number.isFinite(at)) return undefined\n  return Math.max(0, nowMs - at)\n}\n\n/** 계약의 요구를 그대로 본다 — 판정을 여기서 다시 쓰지 않는다. */\nfunction missingRequired(spec: CommandTypeSpec, payload: Record<string, unknown>): string[] {\n  return (spec.required ?? []).filter(key => {\n    const v = payload[key]\n    return v === undefined || v === null || v === ''\n  })\n}\n"]}

package/dist-server/service/actuation/rule-loop.d.ts

@@ -0,0 +1,5 @@
+/** 몇 초마다 도나. 오래 이어진 조건을 보는 일이라 촘촘할 이유가 없다. */
+export declare const RULE_PERIOD_MS = 30000;
+/** 주기를 세운다 — 두 번 불러도 하나만 선다. */
+export declare function startActuationRuleLoop(periodMs?: number): void;
+export declare function stopActuationRuleLoop(): void;