@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/coordinator-git.js

@@ -0,0 +1,121 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+/**
+ * @param {Exec} exec - Git 실행기
+ * @param {string} cwd - checkout
+ * @param {string[]} args - Git 인자
+ * @returns {string} trim된 stdout
+ */
+function git(exec, cwd, args) {
+    return String(exec('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })).trim();
+}
+/**
+ * dispatch 직전 porcelain 출력을 원문 그대로 보존한다.
+ *
+ * @param {Exec} exec - 주입 가능한 Git 실행기
+ * @param {string} cwd - worker worktree
+ * @returns {string} porcelain=v1 stdout 원문
+ */
+function initialWorktreeState(exec, cwd) {
+    return String(exec('git', ['status', '--porcelain=v1'], {
+        cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+    }));
+}
+/** @param {Exec} exec - Git 실행기 @param {string} cwd - checkout @returns {string} source porcelain */
+function sourceStatus(exec, cwd) {
+    // .worktrees는 bootstrap fixture에서 ignore 규칙이 아직 없어도 source 변경으로 세지 않는다.
+    return git(exec, cwd, ['status', '--porcelain']).split('\n')
+        .filter((line) => !line.slice(3).startsWith('.worktrees/')).join('\n');
+}
+/**
+ * worker HEAD가 주어진 SHA를 조상으로 갖는지 확인한다.
+ *
+ * @param {Exec} exec - Git 실행기
+ * @param {string} workerPath - 할당된 worker checkout
+ * @param {string} sha - 검사할 commit SHA
+ * @returns {boolean} 조상이면 true, Git 조회 실패면 false
+ */
+function workerOwnsSha(exec, workerPath, sha) {
+    try {
+        git(exec, workerPath, ['merge-base', '--is-ancestor', sha, 'HEAD']);
+        return true;
+    }
+    catch (_error) {
+        // 얕은 clone이나 삭제된 object도 안전하게 입증할 수 없어 소유하지 않은 것으로 처리한다.
+        return false;
+    }
+}
+/**
+ * SHA의 단일 부모를 구한다. merge 또는 Git 조회 실패는 provenance를 추측하지 않고 거절한다.
+ *
+ * @param {Exec} exec - Git 실행기
+ * @param {string} cwd - 할당된 worker checkout
+ * @param {string} sha - 검사할 worker HEAD
+ * @returns {string | null} 유일한 부모 SHA 또는 null
+ */
+function directParent(exec, cwd, sha) {
+    try {
+        const fields = git(exec, cwd, ['rev-list', '--parents', '-n', '1', sha]).split(/\s+/);
+        return fields.length === 2 ? fields[1] : null;
+    }
+    catch (_error) {
+        // 존재하지 않는 object와 Git 조회 실패는 모두 provenance를 입증하지 못한다.
+        return null;
+    }
+}
+/**
+ * worker 경로가 symlink가 아니며 integration 저장소에 등록된 worktree인지 검사한다.
+ *
+ * @param {Exec} exec - Git 실행기
+ * @param {string} integrationPath - integration checkout
+ * @param {string} workerPath - 검사할 worker 경로
+ * @returns {boolean} 등록된 동일 checkout이면 true
+ */
+function registeredWorker(exec, integrationPath, workerPath) {
+    try {
+        const canonicalWorker = fs.realpathSync(workerPath);
+        if (canonicalWorker !== path.resolve(workerPath))
+            return false;
+        const workerRoot = fs.realpathSync(path.dirname(workerPath));
+        const relative = path.relative(workerRoot, canonicalWorker);
+        if (relative === '' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+            return false;
+        const registered = git(exec, integrationPath, ['worktree', 'list', '--porcelain'])
+            .split('\n').filter((line) => line.startsWith('worktree ')).map((line) => line.slice('worktree '.length));
+        return registered.some((entry) => fs.realpathSync(entry) === canonicalWorker);
+    }
+    catch (_error) {
+        // 사라진 경로·Git 조회 실패는 등록을 입증하지 못하므로 false다.
+        return false;
+    }
+}
+/**
+ * integration 경로가 symlink가 아니며 project 저장소에 등록된 worktree인지 검사한다.
+ *
+ * @param {Exec} exec - Git 실행기
+ * @param {string} repoRoot - project checkout
+ * @param {string} integrationPath - 검사할 integration 경로
+ * @returns {boolean} 등록된 동일 checkout이면 true
+ */
+function registeredIntegration(exec, repoRoot, integrationPath) {
+    try {
+        const canonicalIntegration = fs.realpathSync(integrationPath);
+        if (canonicalIntegration !== path.resolve(integrationPath))
+            return false;
+        const integrationRoot = fs.realpathSync(path.dirname(integrationPath));
+        const relative = path.relative(integrationRoot, canonicalIntegration);
+        if (relative === '' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+            return false;
+        const registered = git(exec, repoRoot, ['worktree', 'list', '--porcelain'])
+            .split('\n').filter((line) => line.startsWith('worktree ')).map((line) => line.slice('worktree '.length));
+        return registered.some((entry) => fs.realpathSync(entry) === canonicalIntegration);
+    }
+    catch (_error) {
+        // 경로나 Git이 유효하지 않으면 integration checkout 소유권을 입증할 수 없다.
+        return false;
+    }
+}
+module.exports = {
+    git, initialWorktreeState, sourceStatus, workerOwnsSha, directParent, registeredWorker, registeredIntegration,
+};

package/dist/coordinator-input.js

@@ -0,0 +1,37 @@
+'use strict';
+/**
+ * coordinator print dispatch 입력 텍스트를 조립한다. 입력 파일 형식을 세션이
+ * 플러그인 소스에서 역산하지 않도록 `coordinate status --write-input`이 이
+ * 함수의 결과를 그대로 쓴다. 파일 I/O와 값 수집은 호출자 몫이라 순수 함수다.
+ *
+ * @param {object} fields - 입력 텍스트에 들어갈 값
+ * @param {string} fields.integrationPath - coordinator와 worker의 유일한 write cwd
+ * @param {string} fields.blueprint - blueprint 디렉터리
+ * @param {string} fields.base - 원장 `base` SHA
+ * @param {CoordinatorInputCheckpoint} fields.checkpoint - status checkpoint (ledger ref 포함)
+ * @param {string} fields.autonomy - 보고 주기로만 쓰는 autonomy 값
+ * @param {string} fields.projectRoot - main worktree. base SHA 출처 표기에만 쓴다
+ * @returns {string} 개행으로 끝나는 coordinator 입력 텍스트
+ */
+function buildCoordinatorInput(fields) {
+    const { checkpoint } = fields;
+    // revision은 원장에 없을 수 있다(null). 줄 자체는 형식 고정을 위해 항상 남긴다.
+    return [
+        'Coordinator dispatch input',
+        `write cwd: ${fields.integrationPath}`,
+        `blueprint: ${fields.blueprint}`,
+        `base SHA: ${fields.base}`,
+        `checkpoint.ledger.path: ${checkpoint.ledger.path}`,
+        `checkpoint.ledger.sha256: ${checkpoint.ledger.sha256}`,
+        `checkpoint.ledger.revision: ${checkpoint.ledger.revision}`,
+        `checkpoint: ${JSON.stringify(checkpoint)}`,
+        `autonomy: ${fields.autonomy} (reporting cadence only; open no per-task ACQ)`,
+        `read-only provenance: ${fields.projectRoot} (base SHA provenance only; never a write cwd)`,
+        // 조기 반환 방지 가드: native/generic/print 모두 이 문자열을 그대로 받는다.
+        // 병렬 launch는 막지 않고, 핸들만 받은 상태를 보고로 오인하지 못하게 한다.
+        'Before returning, wait for every worker final report (a handle is not a report) and integrate your whole wave;',
+        'return continue only with at least one newly integrated task id, never an empty list or a partial wave.',
+        '',
+    ].join('\n');
+}
+module.exports = { buildCoordinatorInput };

package/dist/coordinator-ledger.js

@@ -0,0 +1,381 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const runtime = require("./runtime-state");
+const configMod = require("./config");
+const { readCoordinatorPolicy } = configMod;
+const executionDag = require("./execution-dag");
+const { readyWave } = executionDag;
+const leaseMod = require("./lease");
+const { isValidLease, isValidLeaseSeq } = leaseMod;
+const coordinatorWorker = require("./coordinator-worker");
+const { reportPathFor } = coordinatorWorker;
+const LEDGER_REL = runtime.COORDINATOR_LEDGER_REL;
+function atomicWrite(file, data) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(data, null, 2)}\n`);
+    fs.renameSync(temporary, file);
+}
+/**
+ * 원장 bytes와 파싱 결과를 같은 snapshot에서 읽어 fence가 TOCTOU로 느슨해지지 않게 한다.
+ *
+ * @param {string} file - 원장 절대 경로
+ * @returns {{ ledger: Ledger, bytes: Buffer } | null} 파일이 없으면 null
+ */
+function loadLedgerBytes(file) {
+    if (!fs.existsSync(file))
+        return null;
+    const bytes = fs.readFileSync(file);
+    return { ledger: JSON.parse(bytes.toString('utf8')), bytes };
+}
+function loadLedger(file) {
+    const loaded = loadLedgerBytes(file);
+    return loaded ? loaded.ledger : null;
+}
+/** @param {Buffer} bytes - load 시점의 원장 bytes @returns {string} SHA-256 hex */
+function ledgerBytesHash(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/**
+ * mutation이 들고 온 원장 경로와 hash를 검사하고 detached ledger를 차단한다.
+ *
+ * @param {{ ledgerPath?: string, ledgerHash?: string, ledgerBytes: Buffer }} opts - fence 입력
+ * @returns {{ok: true} | {ok: false, reason: string}} 기존 거절 reason 또는 통과
+ */
+function assertLedgerFence(opts) {
+    const { ledgerPath, ledgerHash, ledgerBytes } = opts;
+    if (typeof ledgerPath !== 'string' || ledgerPath === ''
+        || typeof ledgerHash !== 'string' || ledgerHash === '')
+        return { ok: false, reason: 'ledger-checkpoint-invalid' };
+    if (path.isAbsolute(ledgerPath))
+        return { ok: false, reason: 'ledger-checkpoint-invalid' };
+    if (ledgerPath.includes('\\') || ledgerPath.split('/').includes('..')
+        || ledgerPath.split('/').includes('') || ledgerPath !== LEDGER_REL) {
+        return { ok: false, reason: 'ledger-checkpoint-invalid' };
+    }
+    if (!/^[a-f0-9]{64}$/.test(ledgerHash))
+        return { ok: false, reason: 'ledger-checkpoint-invalid' };
+    if (!Buffer.isBuffer(ledgerBytes) || ledgerBytes.length === 0) {
+        return { ok: false, reason: 'ledger-checkpoint-invalid' };
+    }
+    if (ledgerBytesHash(ledgerBytes) !== ledgerHash)
+        return { ok: false, reason: 'stale-ledger-checkpoint' };
+    // 모든 fenced mutation이 공유하는 끝단 검사라 새 명령도 detached 상태를 빠뜨리지 않는다.
+    const parsed = JSON.parse(ledgerBytes.toString('utf8'));
+    if (parsed && parsed.status === 'detached')
+        return { ok: false, reason: 'run-detached' };
+    return { ok: true };
+}
+/**
+ * 잠금 소유를 확인한 뒤에만 원장을 쓴다.
+ *
+ * @param {() => boolean} owns - 현재 잠금 소유 확인
+ * @param {(file: string, data: unknown) => void} writeLedger - 원자 쓰기 구현
+ * @param {string} file - 원장 경로
+ * @param {Ledger} ledger - 기록할 원장
+ * @returns {{ok: false, reason: 'ledger-lock-lost'} | null} 소유 상실 시 실패
+ */
+function writeOwnedLedger(owns, writeLedger, file, ledger) {
+    if (!owns())
+        return { ok: false, reason: 'ledger-lock-lost' };
+    writeLedger(file, ledger);
+    return null;
+}
+/** 성공 mutation 결과에 다음 fencing token이 될 checkpoint를 붙인다. */
+function withCheckpoint(result, ledger, ledgerFile) {
+    return { ...result, checkpoint: projectCheckpoint(ledger, ledgerFile) };
+}
+/**
+ * 잠금 안에서 원장을 읽고 기존 순서대로 lease·명령별 validation·fence를 검사한다.
+ * reason 우선순위가 caller마다 달라지지 않도록 이 공유 helper가 순서를 소유한다.
+ *
+ * @param {object} opts - 원장 경로와 검증 조건
+ * @returns {OpenedLedger | LedgerFail} bytes snapshot 또는 기존 거절 reason
+ */
+function openLedgerFenced({ ledgerFile, ledgerPath, ledgerHash, validate }) {
+    const loaded = loadLedgerBytes(ledgerFile);
+    if (!loaded)
+        return { ok: false, reason: 'missing-ledger' };
+    const { ledger, bytes } = loaded;
+    const leaseShape = assertLeaseShape(ledger);
+    if (!leaseShape.ok)
+        return leaseShape;
+    const rejected = validate ? validate(ledger) : null;
+    if (rejected)
+        return rejected;
+    const fenced = assertLedgerFence({ ledgerPath, ledgerHash, ledgerBytes: bytes });
+    if (!fenced.ok)
+        return fenced;
+    return { ok: true, ledger, bytes };
+}
+/**
+ * 잠금 재획득 뒤 원장이 checkpoint 이후 바뀌지 않았는지 확인한다. null hash는 caller fence를 재검사한다.
+ *
+ * @param {object} opts - 재확인 입력
+ * @returns {OpenedLedger | LedgerFail} 현재 snapshot 또는 기존 거절 reason
+ */
+function recheckLedgerCheckpoint({ ledgerFile, expectedHash, fence, onStale }) {
+    const loaded = loadLedgerBytes(ledgerFile);
+    if (!loaded)
+        return { ok: false, reason: 'missing-ledger' };
+    const { ledger, bytes } = loaded;
+    if (expectedHash === null) {
+        const fenced = assertLedgerFence({
+            ledgerPath: fence?.ledgerPath, ledgerHash: fence?.ledgerHash, ledgerBytes: bytes,
+        });
+        if (!fenced.ok)
+            return fenced;
+    }
+    else if (ledgerBytesHash(bytes) !== expectedHash) {
+        if (onStale)
+            onStale(ledger);
+        return { ok: false, reason: 'stale-ledger-checkpoint' };
+    }
+    return { ok: true, ledger, bytes };
+}
+/**
+ * fan-in 사전 검사로 fence보다 먼저 원장 전체 불변조건을 검사한다.
+ *
+ * @param {Ledger} ledger - 방금 연 원장
+ * @returns {LedgerFail | null} 거절 reason 또는 통과
+ */
+function validateFaninLedger(ledger) {
+    const checked = runtime.validateCoordinatorLedger(ledger);
+    return checked.ok ? null : { ok: false, reason: checked.reason };
+}
+/**
+ * 보고 파일의 존재를 투영 시점에 관측한다. 원장에는 기록하지 않는다.
+ * 일반 파일이고 크기가 0보다 클 때만 present다. 파일 없음·0바이트·디렉터리와
+ * 그 밖의 모든 stat 오류는 absent로 접는다 — 이 관측은 복구 재개 여부를 정하는
+ * 보수적 신호일 뿐이라 오류를 던지면 status 전체가 깨지고, absent는 기존
+ * 보존 중단 경로로 이어지므로 안전하다.
+ *
+ * @param {string} reportPath - 현재 attempt의 보고 파일 절대 경로
+ * @returns {'present' | 'absent'} 관측 결과
+ */
+function observeReport(reportPath) {
+    try {
+        const stat = fs.statSync(reportPath);
+        return stat.isFile() && stat.size > 0 ? 'present' : 'absent';
+    }
+    catch (_error) {
+        // stat 실패(ENOENT·EACCES 등)는 모두 absent: 위 docstring의 보수적 접힘 근거 참조.
+        return 'absent';
+    }
+}
+/**
+ * 현재 CLI는 호스트 실행기를 추적하지 않으므로 항상 관측 불가를 뜻하는 상수 모양이다.
+ * running·terminated는 root가 실제 호스트 핸들로만 확인하며 여기서 만들지 않는다.
+ */
+// 실패 사유가 아니므로 `reason: '...'` 리터럴 대신 상수로 두어 COORDINATE_FAILURE_HINTS
+// 전수 검사(실패 reason 리터럴 수집)에 섞이지 않게 한다.
+const EXECUTOR_NOT_TRACKED = 'executor-state-not-tracked';
+/** checkpoint에 싣는 note 개수 상한. 오래된 note는 원장에만 남는다. */
+const CHECKPOINT_NOTES_LIMIT = 5;
+/**
+ * 읽기 전용 ready 계산용 한도. 잘못된 config는 1로 접어 병렬 폭을 넓히지 않는다.
+ * prepare의 거절 경로와 달리 status·current·commit 안내는 worktree를 만들지 않으므로
+ * 여기서는 거절 대신 보수적 폴백만 한다.
+ *
+ * @param {string} repoRoot - 정책을 읽을 checkout 루트
+ * @returns {number} 유효 한도 또는 invalid 시 1
+ */
+function maxParallelForRead(repoRoot) {
+    const policy = readCoordinatorPolicy(repoRoot);
+    return policy.ok ? policy.maxParallel : 1;
+}
+/**
+ * 원장 파일 경로에서 integration checkout 루트를 복원한다. checkpoint·bootstrap
+ * ready가 prepare와 같은 config를 읽게 하려고 ledger 상대 위치만 쓴다.
+ *
+ * @param {string} ledgerFile - `.bouncer/runtime/coordinator.json` 절대 경로
+ * @returns {string} integration checkout 루트
+ */
+function integrationRootFromLedger(ledgerFile) {
+    return path.resolve(path.dirname(ledgerFile), '..', '..');
+}
+/**
+ * 완료 task를 status에 실을 요약만 고른다. dispatch·decisions 본문은 상세 원장에
+ * 남기고, 없는 선택 필드는 키 자체를 생략해 응답이 커지지 않게 한다.
+ *
+ * @param {Task} task - 원장 task
+ * @returns {CompletedTaskSummary} 완료 summary
+ */
+function summarizeCompletedTask(task) {
+    const summary = { id: task.id, status: task.status || 'integrated' };
+    if (task.dispatch && Number.isInteger(task.dispatch.attempt)) {
+        summary.attempt = task.dispatch.attempt;
+    }
+    if (typeof task.sha === 'string' && task.sha !== '')
+        summary.commit_sha = task.sha;
+    if (task.scope && Array.isArray(task.scope.paths))
+        summary.changed_paths = [...task.scope.paths];
+    if (task.scope && typeof task.scope.revision === 'string') {
+        summary.scope_revision = task.scope.revision;
+    }
+    if (typeof task.verify_evidence_id === 'string' && task.verify_evidence_id !== '') {
+        summary.verify_evidence_id = task.verify_evidence_id;
+    }
+    if (typeof task.review_evidence_id === 'string' && task.review_evidence_id !== '') {
+        summary.review_evidence_id = task.review_evidence_id;
+    }
+    if (task.advisory !== undefined)
+        summary.advisory = task.advisory;
+    return summary;
+}
+/**
+ * 다음 dispatch/fan-in에 필요한 활성 task 필드만 고른다. Interface allowlist는
+ * current scope·dependency·branch/worktree·dispatch metadata뿐이다 —
+ * execution_kind/sha/criticalRecovery/dynamic은 상세 원장에 두고 status를 키우지 않는다.
+ *
+ * @param {Task} task - 아직 integrated가 아닌 task
+ * @returns {ActiveTaskProjection} 활성 projection
+ */
+function projectActiveTask(task) {
+    const projected = {
+        id: task.id,
+        status: task.status || 'pending',
+    };
+    if (task.depends_on)
+        projected.depends_on = [...task.depends_on];
+    if (task.dependency_gate)
+        projected.dependency_gate = task.dependency_gate;
+    if (task.parallel_safe !== undefined)
+        projected.parallel_safe = task.parallel_safe;
+    if (task.workerPath)
+        projected.workerPath = task.workerPath;
+    if (task.branch)
+        projected.branch = task.branch;
+    if (task.scope)
+        projected.scope = { revision: task.scope.revision, paths: [...task.scope.paths] };
+    if (task.dispatch)
+        projected.dispatch = { ...task.dispatch };
+    // active attempt에만 붙인다: reported 보고는 원장 outcome이 이미 정본이다.
+    if (task.dispatch?.status === 'active' && task.workerPath) {
+        const reportPath = reportPathFor(task.workerPath, task.id, task.dispatch.attempt);
+        projected.report = {
+            path: reportPath, attempt: task.dispatch.attempt, state: observeReport(reportPath),
+        };
+    }
+    return projected;
+}
+/**
+ * 상세 원장을 보존한 채 status/mutation 응답에 실을 bounded checkpoint를 만든다.
+ * unresolved decision은 아직 integrated가 아닌 task를 가리키는 항목만 남겨,
+ * 완료 task의 과거 decision 본문이 활성 context로 되살아나지 않게 한다.
+ * sha256은 호출자가 넘긴 원장 bytes(또는 쓰기 직후 디스크)에 묶는다.
+ *
+ * @param {Ledger} ledger - 메모리상 원장 정본
+ * @param {string} ledgerFile - 쓰기 후 hash용 절대 경로(ledgerBytes 없을 때)
+ * @param {Buffer} [ledgerBytes] - load 시 고정한 bytes. 있으면 디스크를 다시 읽지 않는다
+ * @returns {CoordinatorCheckpoint} compact checkpoint
+ */
+function projectCheckpoint(ledger, ledgerFile, ledgerBytes) {
+    const completed_tasks = [];
+    const active_tasks = [];
+    const integratedIds = new Set();
+    for (const task of ledger.tasks) {
+        if (task.status === 'integrated') {
+            integratedIds.add(task.id);
+            completed_tasks.push(summarizeCompletedTask(task));
+        }
+        else {
+            active_tasks.push(projectActiveTask(task));
+        }
+    }
+    const decisions = Array.isArray(ledger.decisions) ? ledger.decisions : [];
+    // note는 task를 가리켜도 미해결 판단이 아니라 인계 메모이므로 unresolved_decisions에서 뺀다.
+    const isNote = (entry) => !!entry && typeof entry === 'object' && !Array.isArray(entry) && entry.kind === 'note';
+    const unresolved_decisions = decisions
+        .filter((entry) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            return false;
+        if (isNote(entry))
+            return false;
+        const id = entry.task;
+        return typeof id === 'string' && !integratedIds.has(id);
+    });
+    // task 없는 note와 아직 통합되지 않은 task의 note만 최근 N개 싣는다(통합된 task의 메모는 낡았다).
+    const notes = decisions
+        .filter(isNote)
+        .filter((n) => n.task === undefined || !integratedIds.has(n.task))
+        .slice(-CHECKPOINT_NOTES_LIMIT)
+        .map((n) => ({
+        text: n.text, written_at: n.written_at, ...(n.task !== undefined ? { task: n.task } : {}),
+    }));
+    // 쓰기 직후는 디스크로 확정된 bytes를 읽고, status·fence 직전에는 load bytes를 재사용한다.
+    const sha256 = ledgerBytes
+        ? ledgerBytesHash(ledgerBytes)
+        : ledgerBytesHash(fs.readFileSync(ledgerFile));
+    return {
+        ready: readyWaveGated(ledger.tasks, {
+            maxParallel: maxParallelForRead(integrationRootFromLedger(ledgerFile)),
+        }),
+        active_tasks,
+        completed_tasks,
+        unresolved_decisions,
+        notes,
+        recent_failure: ledger.terminalFailure || null,
+        integration_head: typeof ledger.integrationHead === 'string' ? ledger.integrationHead : null,
+        revision: typeof ledger.revision === 'string' ? ledger.revision : null,
+        ledger: {
+            path: LEDGER_REL,
+            sha256,
+            revision: typeof ledger.revision === 'string' ? ledger.revision : null,
+        },
+        // active는 launch 전에 기록되고 stale report도 해시를 바꾸므로, 원장 값은
+        // 워커 생존의 증거가 아니다. 프로세스 관측·원장 저장 없이 한계만 명시한다.
+        executor_observation: {
+            state: 'unknown', source: 'unavailable', reason: EXECUTOR_NOT_TRACKED,
+        },
+    };
+}
+/**
+ * `readyWave`에 "재배정된 task가 재통합되기 전에는 terminal을 열지 않는다"는 규칙을 더한다.
+ * `repair --resume-task`는 DAG를 바꾸지 않으므로 terminal의 직접 선행(통합 완료)만 보면 terminal이
+ * 재작업과 동시에(또는 id 순서상 먼저) 열릴 수 있다. resumed 표지가 붙은 task가 integrated가 되기
+ * 전까지 pending terminal을 후보에서 뺀다. resumed 표지가 없는 원장은 입력 그대로 `readyWave`에 간다.
+ *
+ * @param {Task[]} tasks - 원장 task 목록(읽기만 한다)
+ * @param {{ maxParallel?: number }} [options] - `readyWave`와 같은 동시 실행 상한
+ * @returns {string[]} 다음에 열 수 있는 task id
+ */
+function readyWaveGated(tasks, options) {
+    const reopened = tasks.some((entry) => entry.resumed === true && entry.status !== 'integrated');
+    if (!reopened)
+        return readyWave(tasks, options);
+    return readyWave(tasks.map((entry) => (entry.execution_kind === 'verification' && (entry.status || 'pending') === 'pending'
+        ? { ...entry, status: 'waiting-for-resumed' }
+        : entry)), options);
+}
+/**
+ * 원장 lease 필드만 검사한다. 전체 validateCoordinatorLedger는 partial-close
+ * 불변조건까지 보므로, 일반 mutation에서는 lease-invalid만 분리해 거절한다.
+ *
+ * @param {Ledger} ledger - 로드한 원장
+ * @returns {{ok: true} | {ok: false, reason: 'lease-invalid'}}
+ */
+function assertLeaseShape(ledger) {
+    if (!isValidLeaseSeq(ledger.leaseSeq))
+        return { ok: false, reason: 'lease-invalid' };
+    for (const task of ledger.tasks) {
+        if (task.lease !== undefined && !isValidLease(task.lease)) {
+            return { ok: false, reason: 'lease-invalid' };
+        }
+    }
+    return { ok: true };
+}
+/** 원장 mode를 읽는다. 값이 없거나 light가 아니면 legacy full로 해석한다. */
+function ledgerModeOf(ledger) {
+    return ledger.mode === 'light' ? 'light' : 'full';
+}
+module.exports = {
+    atomicWrite, loadLedgerBytes, loadLedger, ledgerBytesHash, assertLedgerFence, writeOwnedLedger, LEDGER_REL,
+    projectCheckpoint, assertLeaseShape,
+    // coordinator-commands가 checkpoint와 같은 ready 계산·한도 폴백을 쓰도록 함께 내보낸다.
+    readyWaveGated, maxParallelForRead,
+    withCheckpoint, openLedgerFenced, recheckLedgerCheckpoint, validateFaninLedger,
+    ledgerModeOf,
+};