chapterhouse 0.13.0 → 0.14.0

package/dist/memory/housekeeping-scheduler.js

@@ -1,187 +0,0 @@
-import { getDb } from "../store/db.js";
-import { childLogger } from "../util/logger.js";
-import { isHousekeepingInFlight, runHousekeeping } from "./housekeeping.js";
-import { reflectAllScopes } from "./reflect.js";
-export const DEFAULT_MEMORY_HOUSEKEEP_INTERVAL_MS = 21_600_000;
-export const DEFAULT_MEMORY_HOUSEKEEP_INITIAL_DELAY_MS = 300_000;
-export const DEFAULT_MEMORY_REFLECT_INTERVAL_DAYS = 7;
-function parseNonNegativeIntegerEnv(name, rawValue, defaultValue) {
-    const normalized = rawValue?.trim();
-    if (!normalized) {
-        return defaultValue;
-    }
-    const parsed = Number(normalized);
-    if (!Number.isInteger(parsed) || parsed < 0) {
-        throw new Error(`${name} must be a non-negative integer, got: "${rawValue}"`);
-    }
-    return parsed;
-}
-function toPassCounts(result) {
-    return Object.fromEntries(result.summaries.map((summary) => [
-        summary.pass,
-        {
-            examined: summary.examined,
-            modified: summary.modified,
-            errors: summary.errors,
-        },
-    ]));
-}
-export class MemoryHousekeepingScheduler {
-    env;
-    runHousekeepingImpl;
-    log;
-    runReflectAllScopesImpl;
-    nowImpl;
-    setTimeoutImpl;
-    clearTimeoutImpl;
-    setIntervalImpl;
-    clearIntervalImpl;
-    timeoutHandle;
-    intervalHandle;
-    activeRun;
-    running = false;
-    started = false;
-    reflectIntervalDays;
-    lastReflectAtMs;
-    constructor(options = {}) {
-        this.env = options.env ?? {};
-        this.runHousekeepingImpl = options.runHousekeeping ?? runHousekeeping;
-        this.runReflectAllScopesImpl = options.runReflectAllScopes ?? reflectAllScopes;
-        this.nowImpl = options.nowImpl ?? Date.now;
-        this.log = options.log ?? childLogger("memory.housekeeping.scheduler");
-        this.reflectIntervalDays = parseNonNegativeIntegerEnv("CHAPTERHOUSE_MEMORY_REFLECT_INTERVAL_DAYS", this.env.CHAPTERHOUSE_MEMORY_REFLECT_INTERVAL_DAYS, DEFAULT_MEMORY_REFLECT_INTERVAL_DAYS);
-        this.lastReflectAtMs = this.reflectIntervalDays > 0 ? this.nowImpl() : undefined;
-        this.setTimeoutImpl = options.setTimeoutImpl ?? setTimeout;
-        this.clearTimeoutImpl = options.clearTimeoutImpl ?? ((handle) => clearTimeout(handle));
-        this.setIntervalImpl = options.setIntervalImpl ?? setInterval;
-        this.clearIntervalImpl = options.clearIntervalImpl ?? ((handle) => clearInterval(handle));
-    }
-    start() {
-        if (this.started) {
-            return;
-        }
-        const intervalMs = parseNonNegativeIntegerEnv("CHAPTERHOUSE_MEMORY_HOUSEKEEP_INTERVAL_MS", this.env.CHAPTERHOUSE_MEMORY_HOUSEKEEP_INTERVAL_MS, DEFAULT_MEMORY_HOUSEKEEP_INTERVAL_MS);
-        if (intervalMs === 0) {
-            this.log.info({ interval_ms: intervalMs }, "Memory housekeeping scheduler disabled");
-            return;
-        }
-        const initialDelayMs = parseNonNegativeIntegerEnv("CHAPTERHOUSE_MEMORY_HOUSEKEEP_INITIAL_DELAY_MS", this.env.CHAPTERHOUSE_MEMORY_HOUSEKEEP_INITIAL_DELAY_MS, DEFAULT_MEMORY_HOUSEKEEP_INITIAL_DELAY_MS);
-        this.started = true;
-        this.timeoutHandle = this.setTimeoutImpl(() => {
-            this.timeoutHandle = undefined;
-            this.startScheduledRun("initial_delay");
-            this.intervalHandle = this.setIntervalImpl(() => {
-                this.startScheduledRun("interval");
-            }, intervalMs);
-            this.intervalHandle?.unref?.();
-        }, initialDelayMs);
-        this.timeoutHandle?.unref?.();
-        this.log.info({ interval_ms: intervalMs, initial_delay_ms: initialDelayMs }, "Memory housekeeping scheduler started");
-    }
-    async stop() {
-        if (this.timeoutHandle) {
-            this.clearTimeoutImpl(this.timeoutHandle);
-            this.timeoutHandle = undefined;
-        }
-        if (this.intervalHandle) {
-            this.clearIntervalImpl(this.intervalHandle);
-            this.intervalHandle = undefined;
-        }
-        this.started = false;
-        await this.activeRun;
-    }
-    startScheduledRun(trigger) {
-        const run = this.runScheduledHousekeeping(trigger);
-        const tracked = run.finally(() => {
-            if (this.activeRun === tracked) {
-                this.activeRun = undefined;
-            }
-        });
-        this.activeRun = tracked;
-        void this.activeRun;
-    }
-    async runScheduledHousekeeping(trigger) {
-        if (this.running || isHousekeepingInFlight()) {
-            this.log.warn({ trigger }, "Memory housekeeping run skipped because a previous run is still active");
-            return;
-        }
-        this.running = true;
-        try {
-            const result = await this.runHousekeepingImpl({ allScopes: true });
-            if (isHousekeepingRunResult(result)) {
-                if (isContentionResult(result)) {
-                    this.log.warn({
-                        trigger,
-                        scope_ids: result.scopeIds,
-                        summaries: result.summaries,
-                    }, "Memory housekeeping run skipped because a previous run is still active");
-                    return;
-                }
-                this.log.info({
-                    trigger,
-                    scope_ids: result.scopeIds,
-                    summaries: result.summaries,
-                    pass_counts: toPassCounts(result),
-                    total_examined: result.totalExamined,
-                    total_modified: result.totalModified,
-                    duration_ms: result.durationMs,
-                }, "Memory housekeeping scheduled run complete");
-                await this.maybeRunReflect(trigger);
-            }
-            else {
-                this.log.info({ trigger }, "Memory housekeeping scheduled run complete");
-                await this.maybeRunReflect(trigger);
-            }
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            if (this.log.error) {
-                this.log.error({ trigger, err: message }, "Memory housekeeping scheduled run failed");
-            }
-            else {
-                this.log.warn({ trigger, err: message }, "Memory housekeeping scheduled run failed");
-            }
-        }
-        finally {
-            this.running = false;
-        }
-    }
-    async maybeRunReflect(trigger) {
-        if (this.reflectIntervalDays === 0) {
-            return;
-        }
-        const now = this.nowImpl();
-        const intervalMs = this.reflectIntervalDays * 24 * 60 * 60 * 1000;
-        if (this.lastReflectAtMs !== undefined && (now - this.lastReflectAtMs) < intervalMs) {
-            return;
-        }
-        const result = await this.runReflectAllScopesImpl(getDb());
-        this.lastReflectAtMs = now;
-        const totals = Object.values(result).reduce((acc, scopeResult) => ({
-            patterns_created: acc.patterns_created + scopeResult.patternsCreated,
-            patterns_updated: acc.patterns_updated + scopeResult.patternsUpdated,
-            contradictions_found: acc.contradictions_found + scopeResult.contradictionsFound,
-        }), {
-            patterns_created: 0,
-            patterns_updated: 0,
-            contradictions_found: 0,
-        });
-        this.log.info({ trigger, scopes: Object.keys(result), ...totals }, "Memory reflect scheduled run complete");
-    }
-}
-function isContentionResult(result) {
-    return result.summaries.some((summary) => (summary.pass === "runHousekeeping"
-        && summary.errors.some((error) => /already in flight/i.test(error))));
-}
-function isHousekeepingRunResult(value) {
-    if (!value || typeof value !== "object") {
-        return false;
-    }
-    const candidate = value;
-    return Array.isArray(candidate.scopeIds)
-        && Array.isArray(candidate.summaries)
-        && typeof candidate.totalExamined === "number"
-        && typeof candidate.totalModified === "number"
-        && typeof candidate.durationMs === "number";
-}
-//# sourceMappingURL=housekeeping-scheduler.js.map

package/dist/memory/housekeeping-scheduler.test.js

@@ -1,236 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-async function loadSchedulerModule() {
-    return await import(new URL(`./housekeeping-scheduler.js?cachebust=${Date.now()}-${Math.random()}`, import.meta.url).href);
-}
-function createTimers() {
-    let nextId = 1;
-    const timeouts = [];
-    const intervals = [];
-    return {
-        timeouts,
-        intervals,
-        setTimeoutImpl(callback, delayMs) {
-            const handle = { kind: "timeout", id: nextId++, unref() { } };
-            timeouts.push({ handle, callback, delayMs, cleared: false });
-            return handle;
-        },
-        clearTimeoutImpl(handle) {
-            const entry = timeouts.find((item) => item.handle === handle);
-            if (entry)
-                entry.cleared = true;
-        },
-        setIntervalImpl(callback, delayMs) {
-            const handle = { kind: "interval", id: nextId++, unref() { } };
-            intervals.push({ handle, callback, delayMs, cleared: false });
-            return handle;
-        },
-        clearIntervalImpl(handle) {
-            const entry = intervals.find((item) => item.handle === handle);
-            if (entry)
-                entry.cleared = true;
-        },
-    };
-}
-test("MemoryHousekeepingScheduler registers with the default 6h interval when env is unset", async () => {
-    const schedulerModule = await loadSchedulerModule();
-    const timers = createTimers();
-    const scheduler = new schedulerModule.MemoryHousekeepingScheduler({
-        env: {},
-        runHousekeeping: () => ({ scopeIds: [], summaries: [], totalExamined: 0, totalModified: 0, durationMs: 0 }),
-        setTimeoutImpl: timers.setTimeoutImpl,
-        clearTimeoutImpl: timers.clearTimeoutImpl,
-        setIntervalImpl: timers.setIntervalImpl,
-        clearIntervalImpl: timers.clearIntervalImpl,
-    });
-    scheduler.start();
-    timers.timeouts[0]?.callback();
-    assert.equal(schedulerModule.DEFAULT_MEMORY_HOUSEKEEP_INTERVAL_MS, 21_600_000);
-    assert.equal(timers.intervals.length, 1);
-    assert.equal(timers.intervals[0]?.delayMs, 21_600_000);
-});
-test("MemoryHousekeepingScheduler is disabled when CHAPTERHOUSE_MEMORY_HOUSEKEEP_INTERVAL_MS is 0", async () => {
-    const schedulerModule = await loadSchedulerModule();
-    const timers = createTimers();
-    let runs = 0;
-    const scheduler = new schedulerModule.MemoryHousekeepingScheduler({
-        env: { CHAPTERHOUSE_MEMORY_HOUSEKEEP_INTERVAL_MS: "0" },
-        runHousekeeping: () => {
-            runs += 1;
-        },
-        setTimeoutImpl: timers.setTimeoutImpl,
-        clearTimeoutImpl: timers.clearTimeoutImpl,
-        setIntervalImpl: timers.setIntervalImpl,
-        clearIntervalImpl: timers.clearIntervalImpl,
-    });
-    scheduler.start();
-    assert.equal(timers.timeouts.length, 0);
-    assert.equal(timers.intervals.length, 0);
-    assert.equal(runs, 0);
-});
-test("MemoryHousekeepingScheduler waits for the initial delay before the first run", async () => {
-    const schedulerModule = await loadSchedulerModule();
-    const timers = createTimers();
-    let runs = 0;
-    const scheduler = new schedulerModule.MemoryHousekeepingScheduler({
-        env: {},
-        runHousekeeping: () => {
-            runs += 1;
-        },
-        setTimeoutImpl: timers.setTimeoutImpl,
-        clearTimeoutImpl: timers.clearTimeoutImpl,
-        setIntervalImpl: timers.setIntervalImpl,
-        clearIntervalImpl: timers.clearIntervalImpl,
-    });
-    scheduler.start();
-    assert.equal(schedulerModule.DEFAULT_MEMORY_HOUSEKEEP_INITIAL_DELAY_MS, 300_000);
-    assert.equal(timers.timeouts.length, 1);
-    assert.equal(timers.timeouts[0]?.delayMs, 300_000);
-    assert.equal(runs, 0);
-    timers.timeouts[0]?.callback();
-    await Promise.resolve();
-    assert.equal(runs, 1);
-});
-test("MemoryHousekeepingScheduler does not overlap runs when an interval fires during an active run", async () => {
-    const schedulerModule = await loadSchedulerModule();
-    const timers = createTimers();
-    const warnings = [];
-    let runs = 0;
-    let releaseRun;
-    const scheduler = new schedulerModule.MemoryHousekeepingScheduler({
-        env: {
-            CHAPTERHOUSE_MEMORY_HOUSEKEEP_INITIAL_DELAY_MS: "1",
-            CHAPTERHOUSE_MEMORY_HOUSEKEEP_INTERVAL_MS: "2",
-        },
-        runHousekeeping: () => {
-            runs += 1;
-            return new Promise((resolve) => {
-                releaseRun = resolve;
-            });
-        },
-        log: {
-            info: () => { },
-            warn: (_obj, msg) => warnings.push(msg),
-        },
-        setTimeoutImpl: timers.setTimeoutImpl,
-        clearTimeoutImpl: timers.clearTimeoutImpl,
-        setIntervalImpl: timers.setIntervalImpl,
-        clearIntervalImpl: timers.clearIntervalImpl,
-    });
-    scheduler.start();
-    timers.timeouts[0]?.callback();
-    await Promise.resolve();
-    timers.intervals[0]?.callback();
-    await Promise.resolve();
-    assert.equal(runs, 1);
-    assert.ok(warnings.some((entry) => entry.includes("Memory housekeeping run skipped")));
-    releaseRun?.();
-    await Promise.resolve();
-    await Promise.resolve();
-    timers.intervals[0]?.callback();
-    await Promise.resolve();
-    assert.equal(runs, 2);
-});
-test("MemoryHousekeepingScheduler stop clears pending initial-delay and active interval timers", async () => {
-    const schedulerModule = await loadSchedulerModule();
-    const timers = createTimers();
-    const beforeInitialRun = new schedulerModule.MemoryHousekeepingScheduler({
-        env: {},
-        runHousekeeping: () => { },
-        setTimeoutImpl: timers.setTimeoutImpl,
-        clearTimeoutImpl: timers.clearTimeoutImpl,
-        setIntervalImpl: timers.setIntervalImpl,
-        clearIntervalImpl: timers.clearIntervalImpl,
-    });
-    beforeInitialRun.start();
-    await beforeInitialRun.stop();
-    assert.equal(timers.timeouts[0]?.cleared, true);
-    const afterInitialRun = new schedulerModule.MemoryHousekeepingScheduler({
-        env: {},
-        runHousekeeping: () => { },
-        setTimeoutImpl: timers.setTimeoutImpl,
-        clearTimeoutImpl: timers.clearTimeoutImpl,
-        setIntervalImpl: timers.setIntervalImpl,
-        clearIntervalImpl: timers.clearIntervalImpl,
-    });
-    afterInitialRun.start();
-    timers.timeouts[1]?.callback();
-    await afterInitialRun.stop();
-    assert.equal(timers.intervals[0]?.cleared, true);
-});
-test("MemoryHousekeepingScheduler stop waits for an in-flight run to finish without aborting it", async () => {
-    const schedulerModule = await loadSchedulerModule();
-    const timers = createTimers();
-    let releaseRun;
-    let stopResolved = false;
-    const scheduler = new schedulerModule.MemoryHousekeepingScheduler({
-        env: {},
-        runHousekeeping: () => new Promise((resolve) => {
-            releaseRun = resolve;
-        }),
-        setTimeoutImpl: timers.setTimeoutImpl,
-        clearTimeoutImpl: timers.clearTimeoutImpl,
-        setIntervalImpl: timers.setIntervalImpl,
-        clearIntervalImpl: timers.clearIntervalImpl,
-    });
-    scheduler.start();
-    timers.timeouts[0]?.callback();
-    await Promise.resolve();
-    const stopped = scheduler.stop().then(() => {
-        stopResolved = true;
-    });
-    await Promise.resolve();
-    assert.equal(stopResolved, false);
-    releaseRun?.();
-    await stopped;
-    assert.equal(stopResolved, true);
-});
-test("MemoryHousekeepingScheduler runs weekly reflection after housekeeping and logs pattern deltas", async () => {
-    const schedulerModule = await loadSchedulerModule();
-    const timers = createTimers();
-    const infos = [];
-    const housekeepingRuns = [];
-    const reflectRuns = [];
-    const DAY_MS = 24 * 60 * 60 * 1000;
-    let now = 0;
-    const scheduler = new schedulerModule.MemoryHousekeepingScheduler({
-        env: {
-            CHAPTERHOUSE_MEMORY_HOUSEKEEP_INITIAL_DELAY_MS: "1",
-            CHAPTERHOUSE_MEMORY_HOUSEKEEP_INTERVAL_MS: "2",
-            CHAPTERHOUSE_MEMORY_REFLECT_INTERVAL_DAYS: "7",
-        },
-        runHousekeeping: async () => {
-            housekeepingRuns.push(`housekeeping:${now}`);
-            return { scopeIds: [1], summaries: [], totalExamined: 0, totalModified: 0, durationMs: 0 };
-        },
-        runReflectAllScopes: async () => {
-            reflectRuns.push(`reflect:${now}`);
-            return {
-                chapterhouse: { patternsCreated: 2, patternsUpdated: 1, contradictionsFound: 1 },
-            };
-        },
-        nowImpl: () => now,
-        log: {
-            info: (obj, msg) => infos.push({ obj, msg }),
-            warn: () => { },
-        },
-        setTimeoutImpl: timers.setTimeoutImpl,
-        clearTimeoutImpl: timers.clearTimeoutImpl,
-        setIntervalImpl: timers.setIntervalImpl,
-        clearIntervalImpl: timers.clearIntervalImpl,
-    });
-    scheduler.start();
-    timers.timeouts[0]?.callback();
-    await Promise.resolve();
-    await Promise.resolve();
-    assert.equal(housekeepingRuns.length, 1);
-    assert.equal(reflectRuns.length, 0);
-    now = 7 * DAY_MS;
-    timers.intervals[0]?.callback();
-    await scheduler.stop();
-    assert.equal(housekeepingRuns.length, 2);
-    assert.equal(reflectRuns.length, 1);
-    assert.equal(infos.some((entry) => entry.msg.includes("Memory reflect scheduled run complete")), true);
-    assert.equal(infos.some((entry) => entry.obj.patterns_created === 2 && entry.obj.patterns_updated === 1 && entry.obj.contradictions_found === 1), true);
-});
-//# sourceMappingURL=housekeeping-scheduler.test.js.map