@crewhaus/continuity-store 0.3.0

package/dist/lock.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Advisory single-writer `.lock` for the update-in-place continuity stores
+ * (design §7.6): wait up to 2 s → steal a lock whose mtime is > 30 s stale
+ * (with a `lock_stolen` warning naming the dead holder) → fail with a
+ * `ContinuityLockError` naming the holder pid.
+ *
+ * The policy IMPLEMENTATION lives in `@crewhaus/infra-utils`
+ * (`acquireFileLock`/`withFileLock`) — unified there by the
+ * composition-root PR after continuity-store and wiki-store shipped
+ * byte-identical copies on parallel 0.3.0 branches. This module keeps the
+ * store's public lock surface (error identity, message prefix, option and
+ * handle types) exactly as its tests pin it.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { type FileLockHandle, type FileLockPolicy } from "@crewhaus/infra-utils";
+export declare class ContinuityLockError extends CrewhausError {
+    readonly name = "ContinuityLockError";
+    constructor(message: string, cause?: unknown);
+}
+export type LockPolicy = FileLockPolicy;
+export declare const DEFAULT_LOCK_POLICY: LockPolicy;
+export type AcquireLockOptions = Partial<LockPolicy> & {
+    /** Receives the `lock_stolen` warning line. Default: `console.error`. */
+    readonly onWarn?: (message: string) => void;
+};
+export type LockHandle = FileLockHandle;
+/**
+ * Acquire the advisory lock at `lockPath` under the §7.6 policy. Resolves to
+ * a handle whose `release()` unlinks the file; rejects with
+ * `ContinuityLockError` (naming the holder pid) when the lock stays held past
+ * `waitMs` without going stale.
+ */
+export declare function acquireLock(lockPath: string, opts?: AcquireLockOptions): Promise<LockHandle>;
+/** Run `fn` while holding the lock at `lockPath`; always releases. */
+export declare function withLock<T>(lockPath: string, fn: () => Promise<T>, opts?: AcquireLockOptions): Promise<T>;

package/dist/lock.js

@@ -0,0 +1,43 @@
+/**
+ * Advisory single-writer `.lock` for the update-in-place continuity stores
+ * (design §7.6): wait up to 2 s → steal a lock whose mtime is > 30 s stale
+ * (with a `lock_stolen` warning naming the dead holder) → fail with a
+ * `ContinuityLockError` naming the holder pid.
+ *
+ * The policy IMPLEMENTATION lives in `@crewhaus/infra-utils`
+ * (`acquireFileLock`/`withFileLock`) — unified there by the
+ * composition-root PR after continuity-store and wiki-store shipped
+ * byte-identical copies on parallel 0.3.0 branches. This module keeps the
+ * store's public lock surface (error identity, message prefix, option and
+ * handle types) exactly as its tests pin it.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { DEFAULT_FILE_LOCK_POLICY, acquireFileLock, withFileLock, } from "@crewhaus/infra-utils";
+export class ContinuityLockError extends CrewhausError {
+    name = "ContinuityLockError";
+    constructor(message, cause) {
+        super("runtime", message, cause);
+    }
+}
+export const DEFAULT_LOCK_POLICY = DEFAULT_FILE_LOCK_POLICY;
+const STORE_LABEL = "continuity-store";
+function toFileLockOptions(opts) {
+    return {
+        ...opts,
+        label: STORE_LABEL,
+        createError: (message) => new ContinuityLockError(message),
+    };
+}
+/**
+ * Acquire the advisory lock at `lockPath` under the §7.6 policy. Resolves to
+ * a handle whose `release()` unlinks the file; rejects with
+ * `ContinuityLockError` (naming the holder pid) when the lock stays held past
+ * `waitMs` without going stale.
+ */
+export async function acquireLock(lockPath, opts = {}) {
+    return acquireFileLock(lockPath, toFileLockOptions(opts));
+}
+/** Run `fn` while holding the lock at `lockPath`; always releases. */
+export async function withLock(lockPath, fn, opts = {}) {
+    return withFileLock(lockPath, fn, toFileLockOptions(opts));
+}

package/dist/trash.d.ts

@@ -0,0 +1,68 @@
+import { CrewhausError } from "@crewhaus/errors";
+export declare class TrashError extends CrewhausError {
+    readonly name = "TrashError";
+    constructor(message: string, cause?: unknown);
+}
+export declare const TRASH_DIR_NAME = "trash";
+export type MoveToTrashResult = {
+    /** The snapshot directory everything moved into. */
+    readonly trashDir: string;
+    /** The snapshot timestamp — the `restore()` handle. */
+    readonly ts: string;
+    /** Paths that were moved, relative to the `.crewhaus` dir. */
+    readonly moved: readonly string[];
+};
+export type TrashSnapshot = {
+    readonly ts: string;
+    /** Files inside the snapshot, relative to the `.crewhaus` dir. */
+    readonly files: readonly string[];
+};
+export type RestoreResult = {
+    readonly ts: string;
+    /** Restored file paths, relative to the `.crewhaus` dir. */
+    readonly restored: readonly string[];
+};
+/**
+ * Move `paths` (files or whole directories) into a fresh trash snapshot under
+ * `<crewhausDir>/trash/<ts>/`, preserving each path's location relative to
+ * `crewhausDir`. Missing paths are skipped (clearing an empty store is a
+ * no-op, not an error); paths outside `crewhausDir` — or inside the trash
+ * itself — fail closed. The snapshot directory is only created when at least
+ * one path actually moves.
+ */
+export declare function moveToTrash(paths: readonly string[], crewhausDir: string, opts?: {
+    readonly now?: () => Date;
+}): Promise<MoveToTrashResult>;
+/** List every trash snapshot under `<crewhausDir>/trash/`, oldest first. */
+export declare function listTrash(crewhausDir: string): Promise<readonly TrashSnapshot[]>;
+/**
+ * Move every file of snapshot `ts` back to its original location under
+ * `crewhausDir`. Fail-closed: if ANY destination already exists the restore
+ * throws before moving anything (a clear made after the snapshot must not be
+ * silently clobbered). The emptied snapshot directory is removed afterwards.
+ */
+export declare function restoreFromTrash(ts: string, crewhausDir: string): Promise<RestoreResult>;
+/** Default purge window (design §2.6: "trash is purged after 7 days"). */
+export declare const TRASH_PURGE_AFTER_MS: number;
+export type PurgeTrashResult = {
+    /** Snapshot timestamps that were purged, oldest first. */
+    readonly purged: readonly string[];
+    /** Snapshots kept (younger than the window). */
+    readonly kept: number;
+};
+/** Parse a trash snapshot timestamp (`YYYY-MM-DDTHH-MM-SS`, produced from
+ *  `toISOString()`) back to epoch ms. Collision suffixes (`-N`) share the
+ *  base timestamp. Returns null for a non-matching name. */
+export declare function parseTrashTimestamp(ts: string): number | null;
+/**
+ * Hard-delete every trash snapshot STRICTLY older than `olderThanMs`
+ * (default {@link TRASH_PURGE_AFTER_MS} — the design's 7-day undo window).
+ * A snapshot exactly at the boundary is KEPT: the undo window is inclusive,
+ * so "purged after 7 days" never eats a restore attempted at 7 days sharp.
+ * This is the one sanctioned hard delete in the clearing story — everything
+ * in the trash already survived its undo window.
+ */
+export declare function purgeTrash(crewhausDir: string, opts?: {
+    readonly olderThanMs?: number;
+    readonly now?: () => Date;
+}): Promise<PurgeTrashResult>;

package/dist/trash.js

@@ -0,0 +1,196 @@
+/**
+ * Trash-and-undo clearing (design §2.6): user-facing "clear" NEVER
+ * hard-deletes. Files move to `.crewhaus/trash/<timestamp>/…` preserving their
+ * path relative to the `.crewhaus` directory, so `restore(<timestamp>)` can
+ * put every file back exactly where it came from. Trash purge (7-day window
+ * per the design) lives here as `purgeTrash` — SCHEDULING it is a
+ * janitor/dream concern (the dream engine's phase-1 pass calls it), but the
+ * layout knowledge stays in this one module.
+ *
+ * `moveToTrash` is exported as a reusable helper so other `.crewhaus` stores
+ * (wiki-store, memory-store's clear verbs) can adopt the identical clearing
+ * story later without re-deriving the layout.
+ */
+import { existsSync } from "node:fs";
+import { lstat, mkdir, readdir, rename, rm } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+export class TrashError extends CrewhausError {
+    name = "TrashError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+export const TRASH_DIR_NAME = "trash";
+/** `2026-07-13T19-04-12` (+ optional `-N` collision suffix) — filesystem-safe
+ *  ISO seconds, matching the design's clearing transcript. */
+const TRASH_TS_REGEX = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}(-\d+)?$/;
+function trashTimestamp(now) {
+    return now().toISOString().slice(0, 19).replace(/:/g, "-");
+}
+function assertUnder(absPath, root, what) {
+    if (absPath !== root && !absPath.startsWith(`${root}/`)) {
+        throw new TrashError(`${what} "${absPath}" is outside the .crewhaus dir "${root}" — refusing to trash it`);
+    }
+}
+async function walkFiles(dir, base) {
+    const out = [];
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return out;
+        throw err;
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...(await walkFiles(full, base)));
+        }
+        else {
+            out.push(relative(base, full));
+        }
+    }
+    return out;
+}
+/**
+ * Move `paths` (files or whole directories) into a fresh trash snapshot under
+ * `<crewhausDir>/trash/<ts>/`, preserving each path's location relative to
+ * `crewhausDir`. Missing paths are skipped (clearing an empty store is a
+ * no-op, not an error); paths outside `crewhausDir` — or inside the trash
+ * itself — fail closed. The snapshot directory is only created when at least
+ * one path actually moves.
+ */
+export async function moveToTrash(paths, crewhausDir, opts = {}) {
+    const now = opts.now ?? (() => new Date());
+    const root = resolve(crewhausDir);
+    const trashRoot = join(root, TRASH_DIR_NAME);
+    let ts = trashTimestamp(now);
+    let trashDir = join(trashRoot, ts);
+    for (let suffix = 2; existsSync(trashDir); suffix++) {
+        ts = `${trashTimestamp(now)}-${suffix}`;
+        trashDir = join(trashRoot, ts);
+    }
+    const moved = [];
+    for (const path of paths) {
+        const abs = resolve(path);
+        assertUnder(abs, root, "path");
+        if (abs === trashRoot || abs.startsWith(`${trashRoot}/`)) {
+            throw new TrashError(`path "${abs}" is inside the trash — refusing to trash the trash`);
+        }
+        try {
+            await lstat(abs);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw err;
+        }
+        const rel = relative(root, abs);
+        const dest = join(trashDir, rel);
+        await mkdir(dirname(dest), { recursive: true });
+        await rename(abs, dest);
+        moved.push(rel);
+    }
+    return { trashDir, ts, moved };
+}
+/** List every trash snapshot under `<crewhausDir>/trash/`, oldest first. */
+export async function listTrash(crewhausDir) {
+    const trashRoot = join(resolve(crewhausDir), TRASH_DIR_NAME);
+    let entries;
+    try {
+        entries = await readdir(trashRoot);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const snapshots = [];
+    for (const entry of entries.filter((e) => TRASH_TS_REGEX.test(e)).sort()) {
+        const snapshotDir = join(trashRoot, entry);
+        snapshots.push({ ts: entry, files: await walkFiles(snapshotDir, snapshotDir) });
+    }
+    return snapshots;
+}
+/**
+ * Move every file of snapshot `ts` back to its original location under
+ * `crewhausDir`. Fail-closed: if ANY destination already exists the restore
+ * throws before moving anything (a clear made after the snapshot must not be
+ * silently clobbered). The emptied snapshot directory is removed afterwards.
+ */
+export async function restoreFromTrash(ts, crewhausDir) {
+    if (!TRASH_TS_REGEX.test(ts)) {
+        throw new TrashError(`invalid trash timestamp "${ts}" — expected YYYY-MM-DDTHH-MM-SS`);
+    }
+    const root = resolve(crewhausDir);
+    const trashRoot = join(root, TRASH_DIR_NAME);
+    const trashDir = join(trashRoot, ts);
+    if (!existsSync(trashDir)) {
+        throw new TrashError(`no trash snapshot "${ts}" under ${trashRoot}`);
+    }
+    const files = await walkFiles(trashDir, trashDir);
+    // Conflict pre-check before any move, so a failed restore changes nothing.
+    for (const rel of files) {
+        const dest = join(root, rel);
+        if (existsSync(dest)) {
+            throw new TrashError(`restore ${ts} would overwrite "${dest}" — move the current file aside first`);
+        }
+    }
+    const restored = [];
+    for (const rel of files) {
+        const dest = join(root, rel);
+        await mkdir(dirname(dest), { recursive: true });
+        await rename(join(trashDir, rel), dest);
+        restored.push(rel);
+    }
+    await rm(trashDir, { recursive: true, force: true });
+    return { ts, restored };
+}
+/** Default purge window (design §2.6: "trash is purged after 7 days"). */
+export const TRASH_PURGE_AFTER_MS = 7 * 24 * 60 * 60 * 1000;
+/** Parse a trash snapshot timestamp (`YYYY-MM-DDTHH-MM-SS`, produced from
+ *  `toISOString()`) back to epoch ms. Collision suffixes (`-N`) share the
+ *  base timestamp. Returns null for a non-matching name. */
+export function parseTrashTimestamp(ts) {
+    if (!TRASH_TS_REGEX.test(ts))
+        return null;
+    const base = ts.slice(0, 19); // strip any -N collision suffix
+    const iso = `${base.slice(0, 13)}:${base.slice(14, 16)}:${base.slice(17, 19)}Z`;
+    const parsed = Date.parse(iso);
+    return Number.isNaN(parsed) ? null : parsed;
+}
+/**
+ * Hard-delete every trash snapshot STRICTLY older than `olderThanMs`
+ * (default {@link TRASH_PURGE_AFTER_MS} — the design's 7-day undo window).
+ * A snapshot exactly at the boundary is KEPT: the undo window is inclusive,
+ * so "purged after 7 days" never eats a restore attempted at 7 days sharp.
+ * This is the one sanctioned hard delete in the clearing story — everything
+ * in the trash already survived its undo window.
+ */
+export async function purgeTrash(crewhausDir, opts = {}) {
+    const olderThanMs = opts.olderThanMs ?? TRASH_PURGE_AFTER_MS;
+    const now = opts.now ?? (() => new Date());
+    const cutoff = now().getTime() - olderThanMs;
+    const trashRoot = join(resolve(crewhausDir), TRASH_DIR_NAME);
+    const snapshots = await listTrash(crewhausDir);
+    const purged = [];
+    let kept = 0;
+    for (const snapshot of snapshots) {
+        const ts = parseTrashTimestamp(snapshot.ts);
+        if (ts === null) {
+            kept += 1;
+            continue; // unrecognized name — never delete what we can't date
+        }
+        if (ts < cutoff) {
+            await rm(join(trashRoot, snapshot.ts), { recursive: true, force: true });
+            purged.push(snapshot.ts);
+        }
+        else {
+            kept += 1;
+        }
+    }
+    return { purged, kept };
+}

package/dist/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared record types for the continuity store (design §2.2/§2.4).
+ * Split from index.ts so the pure handoff renderer can import them without a
+ * module cycle.
+ */
+import type { FrozenProof } from "./evidence";
+/** The proof ladder (design §2.4). `claimed` is always free to record;
+ *  `proven` is earned only through `verifyEvidence`. */
+export type LadderStatus = "open" | "in_progress" | "claimed" | "proven";
+/** Ladder statuses a caller may set WITHOUT evidence — everything below
+ *  `proven`. */
+export type ClaimableStatus = "open" | "in_progress" | "claimed";
+export type RequirementStatus = "open" | "confirmed" | "dropped";
+/** One `REQ-nnn` requirements-ledger entry (design §2.2/§2.3): the user's
+ *  words VERBATIM — there is deliberately no paraphrase field — plus the
+ *  session/turn attribution rendered as `(user, sess_…, turn N)`. */
+export type Requirement = {
+    readonly id: string;
+    readonly text: string;
+    readonly status: RequirementStatus;
+    readonly source: {
+        readonly sessionId: string;
+        readonly turn: number;
+    };
+};
+export type PlanStep = {
+    /** 1-based position in the plan. */
+    readonly index: number;
+    readonly text: string;
+    readonly status: LadderStatus;
+    /** Frozen proof excerpts accumulated by `proven` transitions. Retained
+     *  even if the step is later reopened — history, not status. */
+    readonly proofs: readonly FrozenProof[];
+};
+export type PlanRecord = {
+    /** `plan-NNNN`. */
+    readonly id: string;
+    readonly slug: string;
+    readonly title: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly steps: readonly PlanStep[];
+};
+/** One `goals.yaml` entry — the local mirror of Thredz goals (design §2.2):
+ *  `{id, title, status, target?, current?, unit?}` plus bookkeeping. */
+export type Goal = {
+    /** `goal-NNNN`. */
+    readonly id: string;
+    readonly title: string;
+    readonly status: LadderStatus;
+    readonly target?: number;
+    readonly current?: number;
+    readonly unit?: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly proofs?: readonly FrozenProof[];
+};
+/** Parsed managed `focus.md` state. */
+export type FocusState = {
+    /** The mutable focus body (may be empty). */
+    readonly body: string;
+    /** The active plan pointer, or null. */
+    readonly activePlanId: string | null;
+    readonly requirements: readonly Requirement[];
+    /** True when the requirements ledger evicted oldest entries to stay under
+     *  its byte cap (a `[ledger truncated]` marker is rendered in the file). */
+    readonly ledgerTruncated: boolean;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@crewhaus/continuity-store",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "v0.3.0 Goal 1 — focus/plans/goals/handoff stores under .crewhaus/state/ with the claimed→proven proof ladder verified against session event logs, trash/restore clearing, advisory locking, and tenant path fencing.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.3.0",
+    "@crewhaus/event-log": "0.3.0",
+    "@crewhaus/infra-utils": "0.3.0",
+    "@crewhaus/tenancy": "0.3.0",
+    "yaml": "^2.6.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/continuity-store"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/continuity-store#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+}