pulseed 0.4.18 → 0.4.20

package/dist/base/state/checkpoint-trust-port.d.ts

@@ -0,0 +1,4 @@
+export interface CheckpointTrustPort {
+    setOverride(domain: string, balance: number, reason: string): Promise<void>;
+}
+//# sourceMappingURL=checkpoint-trust-port.d.ts.map

package/dist/base/state/checkpoint-trust-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-trust-port.d.ts","sourceRoot":"","sources":["../../../src/base/state/checkpoint-trust-port.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7E"}

package/dist/base/state/checkpoint-trust-port.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=checkpoint-trust-port.js.map

package/dist/base/state/checkpoint-trust-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-trust-port.js","sourceRoot":"","sources":["../../../src/base/state/checkpoint-trust-port.ts"],"names":[],"mappings":""}

package/dist/base/state/state-lock.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Per-goal advisory locking using lockfiles.
+ * Lock path: <baseDir>/locks/goals/<goalId>.lock/
+ * Transition compatibility: also acquire <baseDir>/goals/<goalId>/.lock
+ * when the legacy goal directory already exists.
+ * Uses mkdir as atomic primitive (POSIX: EEXIST = lock held).
+ */
+export interface LockOptions {
+    maxRetries?: number;
+    initialDelayMs?: number;
+    maxTotalMs?: number;
+}
+/** Acquire an advisory lock for the given goalId. Throws if timeout exceeded. */
+export declare function acquireLock(goalId: string, baseDir: string, opts?: LockOptions): Promise<void>;
+/** Release the advisory lock for the given goalId. No-op if lock does not exist. */
+export declare function releaseLock(goalId: string, baseDir: string): Promise<void>;
+//# sourceMappingURL=state-lock.d.ts.map

package/dist/base/state/state-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-lock.d.ts","sourceRoot":"","sources":["../../../src/base/state/state-lock.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AAEH,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAsHD,iFAAiF;AACjF,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED,oFAAoF;AACpF,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhF"}

package/dist/base/state/state-lock.js

@@ -0,0 +1,134 @@
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+function lockPath(goalId, baseDir) {
+    return path.join(baseDir, "locks", "goals", `${goalId}.lock`);
+}
+function legacyLockPath(goalId, baseDir) {
+    return path.join(baseDir, "goals", goalId, ".lock");
+}
+function pidFilePath(lockDir) {
+    return path.join(lockDir, "pid");
+}
+async function pathExists(dir) {
+    try {
+        await fsp.access(dir);
+        return true;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+async function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function tryAcquire(lockDir, checkStale = false) {
+    try {
+        await fsp.mkdir(lockDir, { recursive: false });
+        await fsp.writeFile(pidFilePath(lockDir), String(process.pid), "utf-8");
+        return true;
+    }
+    catch (err) {
+        if (err.code === "EEXIST") {
+            if (checkStale) {
+                await clearStaleLock(lockDir);
+                // Retry once after clearing stale lock
+                try {
+                    await fsp.mkdir(lockDir, { recursive: false });
+                    await fsp.writeFile(pidFilePath(lockDir), String(process.pid), "utf-8");
+                    return true;
+                }
+                catch (retryErr) {
+                    if (retryErr.code === "EEXIST") {
+                        return false;
+                    }
+                    throw retryErr;
+                }
+            }
+            return false;
+        }
+        throw err;
+    }
+}
+async function clearStaleLock(lockDir) {
+    try {
+        const pidStr = await fsp.readFile(pidFilePath(lockDir), "utf-8");
+        const pid = parseInt(pidStr.trim(), 10);
+        if (!isNaN(pid) && !(await isProcessAlive(pid))) {
+            await fsp.rm(lockDir, { recursive: true, force: true });
+        }
+    }
+    catch {
+        // If we cannot read pid, leave the lock intact
+    }
+}
+async function acquireLockDir(lockDir, label, opts, createParent = true) {
+    const maxRetries = opts?.maxRetries ?? 5;
+    const initialDelayMs = opts?.initialDelayMs ?? 50;
+    const maxTotalMs = opts?.maxTotalMs ?? 500;
+    if (createParent) {
+        await fsp.mkdir(path.dirname(lockDir), { recursive: true });
+    }
+    const start = Date.now();
+    let delay = initialDelayMs;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        if (await tryAcquire(lockDir, true)) {
+            return;
+        }
+        if (Date.now() - start >= maxTotalMs) {
+            throw new Error(`acquireLock: timeout exceeded for "${label}" after ${maxTotalMs}ms`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        delay = Math.min(delay * 2, maxTotalMs);
+    }
+    throw new Error(`acquireLock: max retries exceeded for "${label}"`);
+}
+async function releaseLockDir(lockDir) {
+    try {
+        await fsp.rm(lockDir, { recursive: true, force: true });
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        throw err;
+    }
+}
+async function shouldAcquireLegacyLock(goalId, baseDir) {
+    return pathExists(path.join(baseDir, "goals", goalId));
+}
+/** Acquire an advisory lock for the given goalId. Throws if timeout exceeded. */
+export async function acquireLock(goalId, baseDir, opts) {
+    const legacyLockDir = legacyLockPath(goalId, baseDir);
+    const needsLegacyLock = await shouldAcquireLegacyLock(goalId, baseDir);
+    if (needsLegacyLock) {
+        try {
+            await acquireLockDir(legacyLockDir, `${goalId} legacy`, opts, false);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+    }
+    const stableLockDir = lockPath(goalId, baseDir);
+    try {
+        await acquireLockDir(stableLockDir, goalId, opts);
+    }
+    catch (err) {
+        if (needsLegacyLock)
+            await releaseLockDir(legacyLockDir);
+        throw err;
+    }
+}
+/** Release the advisory lock for the given goalId. No-op if lock does not exist. */
+export async function releaseLock(goalId, baseDir) {
+    await releaseLockDir(lockPath(goalId, baseDir));
+    await releaseLockDir(legacyLockPath(goalId, baseDir));
+}
+//# sourceMappingURL=state-lock.js.map

package/dist/base/state/state-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-lock.js","sourceRoot":"","sources":["../../../src/base/state/state-lock.ts"],"names":[],"mappings":"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"}

package/dist/base/state/state-manager-goal-write.d.ts

@@ -0,0 +1,26 @@
+import type { Goal } from "../types/goal.js";
+import type { StateWriteFence } from "./state-manager.js";
+export interface GoalWriteCoordinatorOptions {
+    baseDir: string;
+    walEnabled: boolean;
+    loadGoal: (goalId: string) => Promise<Goal | null>;
+}
+export declare class GoalWriteCoordinator {
+    private readonly baseDir;
+    private readonly walEnabled;
+    private readonly loadGoal;
+    private readonly writeCount;
+    private readonly writeFences;
+    constructor(options: GoalWriteCoordinatorOptions);
+    setWriteFence(goalId: string, fence: StateWriteFence): void;
+    clearWriteFence(goalId: string): void;
+    assertWriteFence(goalId: string, op: string, data: unknown): Promise<void>;
+    goalDir(goalId: string): Promise<string>;
+    /** Wrap a goal write with lock + WAL + snapshot cycle. */
+    protectedWrite(goalId: string, op: string, data: unknown, writeFn: () => Promise<void>): Promise<void>;
+    /** Wrap a goal-scoped operation with lock + fence only (no WAL). */
+    protectedOperation(goalId: string, op: string, data: unknown, run: () => Promise<void>): Promise<void>;
+    /** Wrap a locked read-modify-write cycle with lock + WAL + snapshot cycle. */
+    protectedReadModifyWrite<TData>(goalId: string, op: string, buildData: () => Promise<TData>, writeFn: (data: TData) => Promise<void>): Promise<void>;
+}
+//# sourceMappingURL=state-manager-goal-write.d.ts.map

package/dist/base/state/state-manager-goal-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-manager-goal-write.d.ts","sourceRoot":"","sources":["../../../src/base/state/state-manager-goal-write.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAA0B,MAAM,oBAAoB,CAAC;AAElF,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;CACpD;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;IACpE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;gBAEtD,OAAO,EAAE,2BAA2B;IAMhD,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI;IAI3D,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI/B,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1E,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAW9C,0DAA0D;IACpD,cAAc,CAClB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC;IA4BhB,oEAAoE;IAC9D,kBAAkB,CACtB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GACvB,OAAO,CAAC,IAAI,CAAC;IAUhB,8EAA8E;IACxE,wBAAwB,CAAC,KAAK,EAClC,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC,EAC/B,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC;CA4BjB"}

package/dist/base/state/state-manager-goal-write.js

@@ -0,0 +1,116 @@
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import { acquireLock, releaseLock } from "./state-lock.js";
+import { appendWALRecord, compactWAL } from "./state-wal.js";
+import { writeSnapshot } from "./state-snapshot.js";
+export class GoalWriteCoordinator {
+    baseDir;
+    walEnabled;
+    loadGoal;
+    writeCount = new Map();
+    writeFences = new Map();
+    constructor(options) {
+        this.baseDir = options.baseDir;
+        this.walEnabled = options.walEnabled;
+        this.loadGoal = options.loadGoal;
+    }
+    setWriteFence(goalId, fence) {
+        this.writeFences.set(goalId, fence);
+    }
+    clearWriteFence(goalId) {
+        this.writeFences.delete(goalId);
+    }
+    async assertWriteFence(goalId, op, data) {
+        const fence = this.writeFences.get(goalId);
+        if (!fence)
+            return;
+        await fence({ goalId, op, data });
+    }
+    async goalDir(goalId) {
+        const dir = path.join(this.baseDir, "goals", goalId);
+        try {
+            await fsp.mkdir(dir, { recursive: true });
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return dir;
+            throw err;
+        }
+        return dir;
+    }
+    /** Wrap a goal write with lock + WAL + snapshot cycle. */
+    async protectedWrite(goalId, op, data, writeFn) {
+        await acquireLock(goalId, this.baseDir);
+        try {
+            await this.assertWriteFence(goalId, op, data);
+            if (!this.walEnabled) {
+                await writeFn();
+                return;
+            }
+            const ts = new Date().toISOString();
+            await appendWALRecord(goalId, this.baseDir, { op, data, ts });
+            await writeFn();
+            await appendWALRecord(goalId, this.baseDir, {
+                op: "commit",
+                ref_ts: ts,
+                ts: new Date().toISOString(),
+            });
+            this.writeCount.set(goalId, (this.writeCount.get(goalId) || 0) + 1);
+            const count = this.writeCount.get(goalId);
+            if (count % 50 === 0) {
+                const fullGoal = await this.loadGoal(goalId);
+                if (fullGoal !== null)
+                    await writeSnapshot(goalId, this.baseDir, fullGoal);
+            }
+            if (count % 100 === 0)
+                await compactWAL(goalId, this.baseDir);
+        }
+        finally {
+            await releaseLock(goalId, this.baseDir);
+        }
+    }
+    /** Wrap a goal-scoped operation with lock + fence only (no WAL). */
+    async protectedOperation(goalId, op, data, run) {
+        await acquireLock(goalId, this.baseDir);
+        try {
+            await this.assertWriteFence(goalId, op, data);
+            await run();
+        }
+        finally {
+            await releaseLock(goalId, this.baseDir);
+        }
+    }
+    /** Wrap a locked read-modify-write cycle with lock + WAL + snapshot cycle. */
+    async protectedReadModifyWrite(goalId, op, buildData, writeFn) {
+        await acquireLock(goalId, this.baseDir);
+        try {
+            const data = await buildData();
+            await this.assertWriteFence(goalId, op, data);
+            if (!this.walEnabled) {
+                await writeFn(data);
+                return;
+            }
+            const ts = new Date().toISOString();
+            await appendWALRecord(goalId, this.baseDir, { op, data, ts });
+            await writeFn(data);
+            await appendWALRecord(goalId, this.baseDir, {
+                op: "commit",
+                ref_ts: ts,
+                ts: new Date().toISOString(),
+            });
+            this.writeCount.set(goalId, (this.writeCount.get(goalId) || 0) + 1);
+            const count = this.writeCount.get(goalId);
+            if (count % 50 === 0) {
+                const fullGoal = await this.loadGoal(goalId);
+                if (fullGoal !== null)
+                    await writeSnapshot(goalId, this.baseDir, fullGoal);
+            }
+            if (count % 100 === 0)
+                await compactWAL(goalId, this.baseDir);
+        }
+        finally {
+            await releaseLock(goalId, this.baseDir);
+        }
+    }
+}
+//# sourceMappingURL=state-manager-goal-write.js.map

package/dist/base/state/state-manager-goal-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-manager-goal-write.js","sourceRoot":"","sources":["../../../src/base/state/state-manager-goal-write.ts"],"names":[],"mappings":"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"}

package/dist/base/state/state-manager-wal.d.ts

@@ -0,0 +1,11 @@
+import type { Logger } from "../../runtime/logger.js";
+import type { WALIntent } from "./state-wal.js";
+export interface StateManagerWALRecoveryOptions {
+    baseDir: string;
+    logger?: Logger;
+    listGoalIds: () => Promise<string[]>;
+}
+export declare function recoverStateManagerWAL(options: StateManagerWALRecoveryOptions): Promise<void>;
+/** Map a WAL intent op back to the appropriate file write. */
+export declare function replayStateManagerIntent(baseDir: string, intent: WALIntent, logger?: Logger): Promise<void>;
+//# sourceMappingURL=state-manager-wal.d.ts.map

package/dist/base/state/state-manager-wal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-manager-wal.d.ts","sourceRoot":"","sources":["../../../src/base/state/state-manager-wal.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACtC;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED,8DAA8D;AAC9D,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CA0Ef"}

package/dist/base/state/state-manager-wal.js

@@ -0,0 +1,101 @@
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import { atomicWrite } from "./state-persistence.js";
+import { replayWAL } from "./state-wal.js";
+export async function recoverStateManagerWAL(options) {
+    const { baseDir, logger, listGoalIds } = options;
+    let goalIds;
+    try {
+        goalIds = await listGoalIds();
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        throw err;
+    }
+    for (const goalId of goalIds) {
+        const replayed = await replayWAL(goalId, baseDir, async (intent) => {
+            await replayStateManagerIntent(baseDir, intent, logger);
+        });
+        if (replayed > 0) {
+            logger?.info(`[StateManager] Replayed ${replayed} WAL entries for goal ${goalId}`);
+        }
+    }
+}
+/** Map a WAL intent op back to the appropriate file write. */
+export async function replayStateManagerIntent(baseDir, intent, logger) {
+    const data = intent.data;
+    switch (intent.op) {
+        case "save_goal": {
+            const goalId = data?.id;
+            if (goalId) {
+                const dir = path.join(baseDir, "goals", goalId);
+                await fsp.mkdir(dir, { recursive: true });
+                await atomicWrite(path.join(dir, "goal.json"), data);
+            }
+            break;
+        }
+        case "save_observation": {
+            const goalId = data?.goal_id;
+            if (goalId) {
+                const dir = path.join(baseDir, "goals", goalId);
+                await fsp.mkdir(dir, { recursive: true });
+                await atomicWrite(path.join(dir, "observations.json"), data);
+            }
+            break;
+        }
+        case "append_observation": {
+            const goalId = data?.goal_id;
+            if (goalId) {
+                const dir = path.join(baseDir, "goals", goalId);
+                await fsp.mkdir(dir, { recursive: true });
+                await atomicWrite(path.join(dir, "observations.json"), data);
+            }
+            break;
+        }
+        case "append_observation_and_save_goal": {
+            const goal = data?.goal;
+            const observationLog = data?.observationLog;
+            const goalId = goal?.id;
+            if (goalId && observationLog && goal) {
+                const dir = path.join(baseDir, "goals", goalId);
+                await fsp.mkdir(dir, { recursive: true });
+                await atomicWrite(path.join(dir, "observations.json"), observationLog);
+                await atomicWrite(path.join(dir, "goal.json"), goal);
+            }
+            break;
+        }
+        case "save_gap_history":
+        case "append_gap_entry": {
+            const goalId = data?.goalId;
+            if (goalId) {
+                const dir = path.join(baseDir, "goals", goalId);
+                await fsp.mkdir(dir, { recursive: true });
+                await atomicWrite(path.join(dir, "gap-history.json"), data?.entries ?? data);
+            }
+            break;
+        }
+        case "save_pace_snapshot": {
+            const goalId = data?.id;
+            if (goalId) {
+                const dir = path.join(baseDir, "goals", goalId);
+                await fsp.mkdir(dir, { recursive: true });
+                await atomicWrite(path.join(dir, "goal.json"), data);
+            }
+            break;
+        }
+        case "write_raw": {
+            const relativePath = data?.path;
+            const payload = data?.payload;
+            if (relativePath && payload !== undefined) {
+                const resolved = path.resolve(baseDir, relativePath);
+                await fsp.mkdir(path.dirname(resolved), { recursive: true });
+                await atomicWrite(resolved, payload);
+            }
+            break;
+        }
+        default:
+            logger?.warn(`[StateManager] Unknown WAL intent op: ${intent.op}`);
+    }
+}
+//# sourceMappingURL=state-manager-wal.js.map

package/dist/base/state/state-manager-wal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-manager-wal.js","sourceRoot":"","sources":["../../../src/base/state/state-manager-wal.ts"],"names":[],"mappings":"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"}

package/dist/base/state/state-manager.d.ts

@@ -0,0 +1,156 @@
+import type { Logger } from "../../runtime/logger.js";
+import type { Goal, GoalTree } from "../types/goal.js";
+import type { ObservationLog, ObservationLogEntry } from "../types/state.js";
+import type { GapHistoryEntry } from "../types/gap.js";
+import type { PaceSnapshot } from "../types/goal.js";
+import type { Task } from "../types/task.js";
+import type { CheckpointTrustPort } from "./checkpoint-trust-port.js";
+import { initDirs, atomicWrite, atomicRead } from "./state-persistence.js";
+export { initDirs, atomicWrite, atomicRead };
+export interface StateWriteFenceContext {
+    goalId: string;
+    op: string;
+    data: unknown;
+}
+export type StateWriteFence = (context: StateWriteFenceContext) => Promise<void> | void;
+/**
+ * StateManager handles persistence of goals, state vectors, observation logs,
+ * and gap history under a base directory (default: ~/.pulseed/).
+ *
+ * File layout:
+ *   <base>/goals/<goal_id>/goal.json
+ *   <base>/goals/<goal_id>/observations.json
+ *   <base>/goals/<goal_id>/gap-history.json
+ *   <base>/goal-trees/<root_id>.json
+ *   <base>/events/              (event queue directory)
+ *   <base>/events/archive/      (processed events)
+ *   <base>/reports/             (report output directory)
+ *
+ * All writes are atomic: write to .tmp file, then rename.
+ */
+export declare class StateManager {
+    private readonly baseDir;
+    private readonly logger?;
+    private readonly walEnabled;
+    private readonly goalWriteCoordinator;
+    constructor(baseDir?: string, logger?: Logger, options?: {
+        walEnabled?: boolean;
+    });
+    /** Create required subdirectories. Must be called after construction before first use. */
+    init(): Promise<void>;
+    /**
+     * Scan all goals for uncommitted WAL entries and replay them.
+     * Depends on initDirs() having been called first (to ensure goals/ exists).
+     */
+    private recoverWAL;
+    /** Returns the base directory path */
+    getBaseDir(): string;
+    setWriteFence(goalId: string, fence: StateWriteFence): void;
+    clearWriteFence(goalId: string): void;
+    private assertWriteFence;
+    private goalDir;
+    private atomicWrite;
+    private atomicRead;
+    /** Wrap a goal write with lock + WAL + snapshot cycle. */
+    private protectedWrite;
+    private isEnoent;
+    private pathExists;
+    private goalStorageLocation;
+    private archiveGoalDir;
+    private archiveGoalStagingDir;
+    private archiveCompleteMarkerPath;
+    private resolveWithinBase;
+    private taskStorageDirs;
+    private readTasksFromDir;
+    private cleanupActiveGoalState;
+    private hasActiveGoalState;
+    private copyActiveArchiveRemnants;
+    private commitArchiveGoal;
+    private resolveGoalLocation;
+    private markGoalVisited;
+    private loadGoalForChildTraversal;
+    private visitChildGoals;
+    private capHistoryEntries;
+    private assertObservationGoalId;
+    private writeObservationLog;
+    private writeGapHistory;
+    saveGoal(goal: Goal): Promise<void>;
+    loadGoal(goalId: string): Promise<Goal | null>;
+    deleteGoal(goalId: string, _visited?: Set<string>): Promise<boolean>;
+    /**
+     * Archive a completed goal by moving its state files to
+     * <base>/archive/<goalId>/.
+     *
+     * Moves:
+     *   goals/<goalId>/         → archive/<goalId>/goal/
+     *   tasks/<goalId>/         → archive/<goalId>/tasks/    (if exists)
+     *   strategies/<goalId>/    → archive/<goalId>/strategies/ (if exists)
+     *   stalls/<goalId>.json    → archive/<goalId>/stalls.json (if exists)
+     *   reports/<goalId>/       → archive/<goalId>/reports/  (if exists)
+     *
+     * Returns true if the goal was archived, false if the goal was not found.
+     */
+    archiveGoal(goalId: string, _visited?: Set<string>): Promise<boolean>;
+    /**
+     * Returns the goal IDs of all archived goals under <base>/archive/.
+     */
+    listArchivedGoals(): Promise<string[]>;
+    listGoalIds(): Promise<string[]>;
+    listRecoverableArchivedGoalIds(): Promise<string[]>;
+    listTasks(goalId: string, options?: {
+        includeArchive?: boolean;
+    }): Promise<Task[]>;
+    loadTask(goalId: string, taskId: string, options?: {
+        includeArchive?: boolean;
+    }): Promise<Task | null>;
+    saveGoalTree(tree: GoalTree): Promise<void>;
+    loadGoalTree(rootId: string): Promise<GoalTree | null>;
+    deleteGoalTree(rootId: string): Promise<boolean>;
+    saveObservationLog(log: ObservationLog): Promise<void>;
+    loadObservationLog(goalId: string): Promise<ObservationLog | null>;
+    appendObservation(goalId: string, entry: ObservationLogEntry): Promise<void>;
+    saveGapHistory(goalId: string, history: GapHistoryEntry[]): Promise<void>;
+    loadGapHistory(goalId: string): Promise<GapHistoryEntry[]>;
+    appendGapHistoryEntry(goalId: string, entry: GapHistoryEntry): Promise<void>;
+    appendObservationAndSaveGoal(goalId: string, entry: ObservationLogEntry, updateGoal: (goal: Goal) => Goal): Promise<void>;
+    /**
+     * Save a pace snapshot to a milestone goal (persists to disk).
+     */
+    savePaceSnapshot(goalId: string, snapshot: PaceSnapshot): Promise<void>;
+    /**
+     * BFS traversal starting at rootId.
+     * Returns null if rootId doesn't exist, otherwise returns goals in BFS order.
+     */
+    private bfsCollect;
+    /**
+     * Get the full goal tree rooted at rootId.
+     * Returns null if the root goal doesn't exist.
+     * Returns goals in BFS order: root first, then children level by level.
+     */
+    getGoalTree(rootId: string): Promise<Goal[] | null>;
+    /**
+     * Get all goals in the subtree of goalId (including goalId itself).
+     * Returns [] if goal not found.
+     */
+    getSubtree(goalId: string): Promise<Goal[]>;
+    /**
+     * Update a goal that belongs to a tree, handling both goal and tree consistency.
+     * Merges updates into the existing goal, preserving its id.
+     * If the goal has a parent_id, ensures the parent's children_ids still includes this goal.
+     */
+    updateGoalInTree(goalId: string, updates: Partial<Goal>): Promise<void>;
+    /** Check whether a goal directory exists */
+    goalExists(goalId: string): Promise<boolean>;
+    /**
+     * Restore dimension values and trust balance from a loop crash-recovery checkpoint.
+     * Uses Zod validation on both the checkpoint and the goal.
+     * Returns the saved cycle_number so the caller can resume iteration counting,
+     * or 0 if no checkpoint exists or restoration fails (non-fatal).
+     */
+    restoreFromCheckpoint(goalId: string, adapterType: string, trustManager?: CheckpointTrustPort): Promise<number>;
+    /** Read raw JSON from any path relative to base dir */
+    readRaw(relativePath: string): Promise<unknown | null>;
+    /** Write raw JSON to any path relative to base dir (atomic) */
+    writeRaw(relativePath: string, data: unknown): Promise<void>;
+}
+//# sourceMappingURL=state-manager.d.ts.map

package/dist/base/state/state-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-manager.d.ts","sourceRoot":"","sources":["../../../src/base/state/state-manager.ts"],"names":[],"mappings":"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"}