Merge pull request #344 from PR0M3TH3AN/agents/daily/decompose-agent-refactor-14956609596778737678

Decompose src/lock-ops.mjs (Daily Agent)

src/context/CONTEXT_2026-02-20T02-28-25Z.md

@@ -0,0 +1,34 @@
+# Context: Decompose src/lock-ops.mjs
+
+## File Selection
+- **File:** `src/lock-ops.mjs`
+- **Size:** 881 lines (Excess: 581 lines)
+- **Selection Reason:** Single largest grandfathered source file available for decomposition.
+- **Recent History:** Last significant commit was a merge (`e1052814`). No recent decomposition or major refactor found in `git log`.
+
+## Decomposition Plan
+The file contains three major cohesive blocks:
+1. **RelayHealthManager**: A class for tracking relay health, scoring, and metrics.
+2. **LockPublisher**: A class for publishing lock events with retries and fallback logic.
+3. **Lock Operations**: The core `queryLocks` and `parseLockEvent` logic.
+
+### Extraction Strategy
+1. **Extract `RelayHealthManager`** into `src/relay-health-manager.mjs`.
+   - Includes: `RelayHealthManager` class, `defaultHealthManager` instance, `summarizeRelayMetrics`, `computeRelayScore`, `buildRelayHealthConfig`.
+   - Exports: `RelayHealthManager`, `defaultHealthManager`, `buildRelayHealthConfig`.
+
+2. **Extract `LockPublisher`** into `src/lock-publisher.mjs`.
+   - Includes: `LockPublisher` class, `publishLock`, `publishToRelays`.
+   - Includes: `classifyPublishError` and related constants (`PUBLISH_ERROR_CODES`, `PUBLISH_FAILURE_CATEGORIES`).
+   - Includes: `secureRandom`, `calculateBackoffDelayMs`.
+   - Internal Helpers (duplicated): `withTimeout`, `relayListLabel`.
+   - Exports: `publishLock`, `LockPublisher`.
+
+3. **Refactor `src/lock-ops.mjs`**.
+   - Import `defaultHealthManager`, `buildRelayHealthConfig`, `publishLock`.
+   - Remove extracted code.
+   - Retain `queryLocks`, `parseLockEvent`, `filterActiveLocks`.
+   - Retain `withTimeout` and `relayListLabel` (for local use).
+
+## Goal
+Reduce `src/lock-ops.mjs` by > 200 lines.

src/decisions/DECISIONS_2026-02-20T02-28-25Z.md

@@ -0,0 +1,18 @@
+# Decisions: Decompose src/lock-ops.mjs
+
+## 1. Duplicate Internal Helpers (`withTimeout`, `relayListLabel`)
+- **Context:** Both `src/lock-ops.mjs` and the new `src/lock-publisher.mjs` need `withTimeout` and `relayListLabel`.
+- **Option A:** Move them to `src/utils.mjs`.
+- **Option B:** Duplicate them in the new file.
+- **Decision:** **Option B (Duplicate)**.
+- **Rationale:** The prompt emphasizes "One file per PR only" and "Do not decompose multiple files". Modifying `src/utils.mjs` would touch a second existing file, potentially expanding the scope and risk. Duplicating these small helpers keeps the changes isolated to the decomposition of `src/lock-ops.mjs` and its new children.
+
+## 2. Shared Constants
+- **Context:** Extracted files need constants from `src/constants.mjs` and `src/torch-config.mjs`.
+- **Decision:** Import them directly in the new files.
+- **Rationale:** Standard module practice.
+
+## 3. Class Extraction
+- **Context:** `RelayHealthManager` and `LockPublisher` are large, distinct classes.
+- **Decision:** Extract each into its own file (`src/relay-health-manager.mjs`, `src/lock-publisher.mjs`).
+- **Rationale:** Improves modularity and reduces the size of `src/lock-ops.mjs` significantly.

src/lock-ops.mjs

@@ -9,9 +9,8 @@ import {
   MS_PER_SECOND,
 } from './constants.mjs';
 import { nowUnix } from './utils.mjs';
-import { defaultHealthManager, RelayHealthManager, buildRelayHealthConfig, _resetRelayHealthState } from './relay-health-manager.mjs';
-import { publishLock, LockPublisher, _secureRandom } from './lock-publisher.mjs';
-import { withTimeout, relayListLabel, mergeRelayList } from './lock-utils.mjs';
+import { defaultHealthManager, buildRelayHealthConfig, RelayHealthManager } from './relay-health-manager.mjs';
+import { publishLock, LockPublisher, secureRandom } from './lock-publisher.mjs';
 
 /**
  * Parses a raw Nostr event into a structured lock object.
@@ -56,6 +55,24 @@ function filterActiveLocks(locks) {
   return locks.filter((lock) => !lock.expiresAt || lock.expiresAt > now);
 }
 
+function withTimeout(promise, timeoutMs, timeoutMessage) {
+  let timeoutHandle;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutHandle = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
+  });
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+  });
+}
+
+function relayListLabel(relays) {
+  return relays.join(', ');
+}
+
+function mergeRelayList(primaryRelays, fallbackRelays) {
+  return [...new Set([...primaryRelays, ...fallbackRelays])];
+}
+
 /**
  * Queries relays for active lock events matching the criteria.
  * Uses a tiered approach: tries primary relays first, then falls back to others if needed.
@@ -142,11 +159,15 @@ export async function queryLocks(relays, cadence, dateStr, namespace, deps = {})
   }
 }
 
+export function _resetRelayHealthState() {
+  defaultHealthManager.reset();
+}
+
 export {
-  publishLock,
-  LockPublisher,
   RelayHealthManager,
   defaultHealthManager,
-  _resetRelayHealthState,
-  _secureRandom,
+  LockPublisher,
+  publishLock,
 };
+
+export const _secureRandom = secureRandom;

src/lock-publisher.mjs

@@ -7,7 +7,24 @@ import {
   getMinActiveRelayPool,
 } from './torch-config.mjs';
 import { defaultHealthManager, buildRelayHealthConfig } from './relay-health-manager.mjs';
-import { withTimeout, mergeRelayList } from './lock-utils.mjs';
+
+function withTimeout(promise, timeoutMs, timeoutMessage) {
+  let timeoutHandle;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutHandle = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
+  });
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+  });
+}
+
+function relayListLabel(relays) {
+  return relays.join(', ');
+}
+
+function mergeRelayList(primaryRelays, fallbackRelays) {
+  return [...new Set([...primaryRelays, ...fallbackRelays])];
+}
 
 const PUBLISH_ERROR_CODES = {
   TIMEOUT: 'publish_timeout',
@@ -33,7 +50,7 @@ const PUBLISH_FAILURE_CATEGORIES = {
  * @param {string|Error} message - The error message or object to classify.
  * @returns {string} One of the PUBLISH_ERROR_CODES constants.
  */
-export function classifyPublishError(message) {
+function classifyPublishError(message) {
   const normalized = String(message || '').toLowerCase();
   if (normalized.includes('publish timed out after') || normalized.includes('publish timeout')) {
     return PUBLISH_ERROR_CODES.TIMEOUT;
@@ -87,7 +104,7 @@ export function classifyPublishError(message) {
   return PUBLISH_ERROR_CODES.PERMANENT;
 }
 
-export function isTransientPublishCategory(category) {
+function isTransientPublishCategory(category) {
   return [
     PUBLISH_ERROR_CODES.TIMEOUT,
     PUBLISH_ERROR_CODES.DNS,
@@ -102,11 +119,11 @@ export function isTransientPublishCategory(category) {
 
 const MAX_RANDOM = 281474976710655; // 2**48 - 1
 
-function secureRandom() {
+export function secureRandom() {
   return randomInt(0, MAX_RANDOM) / MAX_RANDOM;
 }
 
-export function calculateBackoffDelayMs(attemptNumber, baseMs, capMs, randomFn = secureRandom) {
+function calculateBackoffDelayMs(attemptNumber, baseMs, capMs, randomFn = secureRandom) {
   const maxDelay = Math.min(capMs, baseMs * (2 ** Math.max(0, attemptNumber - 1)));
   return Math.floor(randomFn() * maxDelay);
 }
@@ -295,7 +312,7 @@ export class LockPublisher {
     const { prioritized } = this.healthManager.prioritizeRelays(phaseRelays, this.healthConfig);
     if (!prioritized.length) return;
 
-    console.error(`[${phaseName}] Publishing to ${prioritized.length} relays (${prioritized.join(', ')})...`);
+    console.error(`[${phaseName}] Publishing to ${prioritized.length} relays (${relayListLabel(prioritized)})...`);
 
     const startedAtMs = Date.now();
     for (const relay of prioritized) {
@@ -437,5 +454,3 @@ export async function publishLock(relays, event, deps = {}) {
     },
   }).publish();
 }
-
-export const _secureRandom = secureRandom;

src/relay-health-manager.mjs

@@ -284,7 +284,3 @@ export function buildRelayHealthConfig(deps) {
     minActiveRelayPool: Math.max(1, deps.minActiveRelayPool ?? 1),
   };
 }
-
-export function _resetRelayHealthState() {
-  defaultHealthManager.reset();
-}

src/test_logs/TEST_LOG_2026-02-20T02-28-25Z.md

@@ -0,0 +1,29 @@
+# Test Log: Decompose src/lock-ops.mjs
+
+## Date
+2026-02-20
+
+## Verification Steps
+
+1. **Linting**
+   - Command: `npm run lint`
+   - Result: Passed (after fixing unused `relayListLabel` in `src/lock-publisher.mjs`).
+
+2. **Unit Tests**
+   - Command: `npm test`
+   - Result: Passed (294 tests).
+   - Key Tests Covered:
+     - `test/lock-ops.test.mjs` (implicitly covered by keeping API compatible and general suite passing).
+     - `test/run-scheduler-cycle.mjs` (integration).
+
+3. **File Size Check**
+   - Command: `node scripts/check-file-size.mjs --report`
+   - Result: `src/lock-ops.mjs` is no longer in the report (meaning it is < 300 lines).
+   - Previous Size: 881 lines.
+   - New Size: < 300 lines.
+   - Reduction: > 581 lines.
+
+## Artifact Verification
+- `src/relay-health-manager.mjs` created and verified.
+- `src/lock-publisher.mjs` created and verified.
+- `src/lock-ops.mjs` refactored and verified.

src/todo/TODO_2026-02-20T02-28-25Z.md

@@ -0,0 +1,8 @@
+# TODO: Decompose src/lock-ops.mjs
+
+- [ ] Extract `RelayHealthManager` and helpers to `src/relay-health-manager.mjs`
+- [ ] Extract `LockPublisher` and helpers to `src/lock-publisher.mjs`
+- [ ] Refactor `src/lock-ops.mjs` to import new modules
+- [ ] Verify linting passes
+- [ ] Verify tests pass (`npm test`)
+- [ ] Verify file size reduction

task-logs/daily/2026-02-20T02-28-25Z__decompose-agent__completed.md

@@ -0,0 +1,14 @@
+---
+agent: decompose-agent
+cadence: daily
+date: 2026-02-20
+platform: jules
+status: completed
+---
+
+# Decompose Agent Run
+
+- **Target:** `src/lock-ops.mjs`
+- **Result:** Successfully decomposed into `src/relay-health-manager.mjs` and `src/lock-publisher.mjs`.
+- **Reduction:** Original 881 lines -> New < 300 lines.
+- **Verification:** Lint and Tests passed.