Skip to content

refactor(heartbeat): extract enqueueWakeup into heartbeat-enqueue-wakeup - #768

Merged
insightflo merged 1 commit into
mainfrom
refactor/hb16-enqueue-wakeup-20261118
Nov 18, 2026
Merged

insightflo merged 1 commit into
mainfrom
refactor/hb16-enqueue-wakeup-20261118

Conversation

@insightflo

Copy link
Copy Markdown
Owner

Summary

  • Mechanically extract enqueueWakeup from server/src/services/heartbeat.ts (L7067–L7827, 761 lines) verbatim into server/src/services/heartbeat-enqueue-wakeup.ts (851 lines), following the PR refactor(heartbeat): extract orphaned run reaper #676 (heartbeat-orphan-reaper.ts) pattern (#hb16).
  • Reduce server/src/services/heartbeat.ts from 8,211 (8,184 functional) lines down to 7,434 lines with zero behavioral changes, zero circular imports (./heartbeat.js is never imported), and call-time TDZ-safe enqueueWakeupDeps assembly.
  • Synchronize scripts/check-run-status-write-chokepoint.mjs (kept at 465 lines <= 465 base): adjust heartbeat.ts LEGACY note (16곳 -> 14곳) and register server/src/services/heartbeat-enqueue-wakeup.ts (2곳 moved contextSnapshot merge updates, 0 new write sites added).

AGENTS.md Rule 8 Exception Note

  • server/src/services/heartbeat-enqueue-wakeup.ts is 851 lines (> 300), matching PR refactor(heartbeat): extract orphaned run reaper #676 (server/src/services/heartbeat-orphan-reaper.ts, 537 lines) as a 1:1 verbatim mechanical extraction intended strictly to shrink legacy heartbeat.ts (8,211 -> 7,434 lines) without refactoring inner transactional boundaries at the same time.

Verification

  • pnpm -r typecheck: exit 0
  • pnpm --filter @paperclipai/server build: exit 0
  • node scripts/check-run-status-write-chokepoint.mjs --self-test & main scan: 9/9 self-tests + 2,118 source files scanned, 31 allowlisted, 0 warnings
  • Focused wakeup Vitest suite (12 files / 64 tests): 64/64 passed
  • Independent line-by-line review (w-agy / gemini-4-hydrogen-xhigh): PASS (0 BLOCKER, 0 MAJOR, 1 MINOR Rule 8 exception note included above)

@insightflo insightflo added ci-full PR CI: run the full suite (verify + verify-tests shards + e2e) on this PR and removed ci-full PR CI: run the full suite (verify + verify-tests shards + e2e) on this PR labels Nov 18, 2026
@insightflo
insightflo force-pushed the refactor/hb16-enqueue-wakeup-20261118 branch from 27db080 to c4bafe1 Compare November 18, 2026 07:05
@insightflo
insightflo merged commit 65f3e8e into main Nov 18, 2026
6 checks passed
@insightflo
insightflo deleted the refactor/hb16-enqueue-wakeup-20261118 branch November 18, 2026 07:08
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

🔍 OpenCodeReview found 4 issue(s) in this PR.

  • ✅ Successfully posted inline: 4 comment(s)

Comment on lines +105 to 108
[
"server/src/services/heartbeat-enqueue-wakeup.ts",
"LEGACY|heartbeat.ts 에서 기계적 분리된 동일 스코프 깨움 병합(contextSnapshot 갱신) 2곳(상태 전이 아님, 단계 수렴 대상)",
],

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maintainability · low
이 신규 allowlist 항목은 파일 단위 면책을 부여하므로, 향후 이 파일에 상태 전이 쓰기(.set({ status: ... }))가 추가되거나 사이트 수가 2곳에서 늘어나도 가드는 CI 를 통과시키고 설명의 "2곳"/"상태 전이 아님" 서술은 조용히 drift 한다. 기존 hygiene 경로(0-hit 경고)처럼 실제 findings 수와 문서화된 수의 불일치를 경고하면 이런 drift 를 조기에 감지할 수 있다.

Suggestion:

Suggested change
[
"server/src/services/heartbeat-enqueue-wakeup.ts",
"LEGACY|heartbeat.ts 에서 기계적 분리된 동일 스코프 깨움 병합(contextSnapshot 갱신) 2곳(상태 전이 아님, 단계 수렴 대상)",
],
// 허용 목록 위생: 더 이상 해당 쓰기가 없는 항목은 정리 대상 안내(실패 아님).
const hitPaths = new Map(
[...files]
.map(([path, content]): [string, number] => [
path,
detectWritesInContent(content, collectTableAliases(content)).length,
])
.filter(([, count]) => count > 0),
);
for (const path of WRITE_ALLOWLIST.keys()) {
const actual = hitPaths.get(path) ?? 0;
const documented = Number((WRITE_ALLOWLIST.get(path)?.match(/(\d+)곳/) ?? [])[1]);
if (actual === 0) {
console.warn(` ⚠ allowlist entry has no matching writes (prune when converged): ${path}`);
} else if (documented && documented !== actual) {
console.warn(` ⚠ allowlist site count drift (documented ${documented}, actual ${actual}): ${path}`);
}
}

// heartbeatService 인스턴스 클로저 함수/값(db/budgets/getAgent/...)은 deps 로 주입받는다.
// heartbeat.ts 로부터는 아무것도 import 하지 않는다(순환 import 방지).
// DEFERRED_WAKE_CONTEXT_KEY 는 deps.deferredWakeContextKey 로 전달된다.
import { and, asc, desc, eq, inArray, is, not, or, sql } from "drizzle-orm";

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

style · low
drizzle-orm의 is와 not 심볼이 이 파일 어디에서도 사용되지 않습니다. heartbeat.ts의 import 목록을 기계적으로 복사한 부작용으로 추정되며(heartbeat.ts는 is(db, PgTransaction)로 사용하지만 추출된 enqueueWakeup 본문에는 해당 호출이 없음), noUnusedLocals/eslint no-unused-vars 위반 및 가독성 저하를 유발합니다. 사용되는 and, asc, desc, eq, inArray, or, sql만 남기고 제거하세요.

Suggestion:

Suggested change
import { and, asc, desc, eq, inArray, is, not, or, sql } from "drizzle-orm";
import { and, asc, desc, eq, inArray, or, sql } from "drizzle-orm";

Comment on lines +380 to +382
if (existingQualityWake) {
return { kind: "quality_existing" as const, row: existingQualityWake };
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maintainability · low
quality_existing outcome의 row 필드가 어디에서도 소비되지 않는 죽은 데이터입니다. withTxTimeout 이후 if (outcome.kind === "quality_existing") return null;로 즉시 폐기되어 호출자에게는 null만 전달되며, 바로 위 주석("그 상태를 그대로 반환한다")과도 동작이 불일치합니다. 본 파일은 heartbeat.ts로부터의 동작 무변경 기계적 추출(파일 헤더의 추출 계약)이므로 여기서 고치면 계약을 깨뜨리게 됩니다. 병합 후 별도 정리 작업에서 row 속성을 제거하거나, 주석의 의도대로 기존 행 상태를 실제로 반환할지 검토하세요.

Suggestion:

Suggested change
if (existingQualityWake) {
return { kind: "quality_existing" as const, row: existingQualityWake };
}
if (existingQualityWake) {
// 기존 quality wake 행 발견 — 멱등 재전송. row는 후속 처리에서 사용되지 않음.
return { kind: "quality_existing" as const, row: existingQualityWake };
}

Comment on lines 109 to 111
mergeableWakeupKeyCondition,
queuePausedAgentWakeupRequest,
} from "./quality/heartbeat-admission.js";

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maintainability · low
enqueueWakeup 본문의 heartbeat-enqueue-wakeup.ts 이전으로 인해 이 블록의 findExistingQualityWakeRow·mergeableWakeupKeyCondition·queuePausedAgentWakeupRequest 세 심볼이 heartbeat.ts에서 더 이상 사용되지 않게 되었습니다(사용처가 전부 새 모듈 L130/L376/L555/L635로 이동됨). 같은 이유로 L189의 assertMissionRuntimeAcceptsWork import도 미사용이 되었습니다. noUnusedLocals가 꺼져 있어 빌드는 깨지지 않지만 죽은 import이므로 이번 변경에서 정리하는 것이 적절합니다. (참고: buildQualityWakeAcceptancePatch는 이번 변경 이전부터 미사용 상태이므로 본 PR 범위 밖입니다.)

Suggestion:

Suggested change
mergeableWakeupKeyCondition,
queuePausedAgentWakeupRequest,
} from "./quality/heartbeat-admission.js";
import {
buildQualityWakeAcceptancePatch,
} from "./quality/heartbeat-admission.js";
// L189: `assertMissionRuntimeAcceptsWork,` 도 mission-runtime-manager.js import 블록에서 함께 제거

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant