@crewhaus/continuity-store 0.3.0

package/README.md

@@ -0,0 +1,98 @@
+# @crewhaus/continuity-store
+
+v0.3.0 Goal 1 (design §2.2–§2.7): the continuity substrate. Human-readable,
+user-clearable focus/plans/goals/handoff artifacts under
+`.crewhaus/state/<specName>/`, with the **claimed → proven proof ladder**
+machine-checked against session event logs. No model call anywhere in this
+package — everything is deterministic infrastructure.
+
+## Storage layout
+
+```
+.crewhaus/state/<spec>/
+  focus.md                  # marker-gated (<!-- crewhaus:focus -->), body capped
+                            # at focusMaxChars; carries the REQ-nnn requirements
+                            # ledger and the active-plan pointer
+  plans/plan-NNNN-<slug>.md # YAML frontmatter + numbered steps with ladder
+                            # statuses and frozen proof excerpts
+  goals.yaml                # {id, title, status, target?, current?, unit?}
+  handoff.md                # deterministic teardown render (same inputs →
+                            # identical bytes)
+  .lock                     # advisory single-writer lock
+```
+
+Why files + markers: matches project-memory's `LESSONS.md` precedent — a
+user-authored `focus.md`/`handoff.md` without the crewhaus marker is **never
+overwritten**. Why JSONL-adjacent formats: everything is inspectable with
+`cat`/`git diff`, and every write is tmp+rename atomic.
+
+```ts
+import { createContinuityStore } from "@crewhaus/continuity-store";
+
+const store = createContinuityStore({ specName: "support-bot" });
+await store.writeFocus("Ship CSV export");
+await store.createPlan({ title: "Ship CSV export", steps: ["Parse", "Export"] });
+await store.setStepStatus("plan-0001", 1, "claimed");            // always free
+await store.proveStep("plan-0001", 1, [{ toolUseId: "tu_…" }]);  // machine-checked
+await store.writeHandoff({ lastSessionId: "sess_…" });
+```
+
+## The proof ladder (§2.4)
+
+Statuses: `open → in_progress → claimed → proven`.
+
+- `claimed` never requires anything — zero friction, no gaming pressure.
+- `proven` is earned: `proveStep` / `updateGoal({status: "proven"})` resolve
+  each cited `toolUseId` against the append-only session JSONLs — including
+  **sub-agent child sessions**, discovered by walking the `sub_agent_start`
+  bracket events (`childSessionId`). Missing ids and `isError: true` results
+  reject with instructive errors (`no verified evidence for tu_…: run the
+  action first, then complete the step with its toolUseId.`).
+
+**Proof lifetime**: session transcripts are TTL-evicted, so on every proven
+transition the store (a) appends a retention pin for the cited session to
+`.crewhaus/retention.json` (the pin contract session-store and
+`crewhaus retention` honor) and (b) freezes a `{toolName, inputHash,
+resultDigest}` excerpt into the plan/goal record — evidence outlives the
+transcript.
+
+## Requirements ledger (§2.3)
+
+`appendRequirement({text, source: {sessionId, turn}, status?})` records the
+user's words **verbatim** (there is deliberately no paraphrase field) as
+`REQ-nnn` entries with `(user, sess_…, turn N)` attribution inside `focus.md`.
+Updating an existing id requires the identical text — paraphrase attempts are
+rejected. The ledger is byte-capped (16 KB) with oldest-first eviction and a
+`[ledger truncated]` marker.
+
+## Clearing (§2.6): trash + undo, never hard-delete
+
+`clear("focus" | "plans" | "goals" | "all")` moves files to
+`.crewhaus/trash/<ISO-ts>/…` preserving relative paths; `restore(ts)` puts
+them back (fail-closed on conflicts); `listTrash()` enumerates snapshots.
+The `moveToTrash(paths, crewhausDir)` helper is exported for other `.crewhaus`
+stores to adopt the same clearing story.
+
+## Locking (§7.6)
+
+Mutations take an advisory `.lock` (O_EXCL create): wait up to 2 s → steal if
+the lock's mtime is >30 s stale (a `lock_stolen` warning is recorded) → fail
+with an error naming the holder pid. Reads never lock; atomic writes keep
+readers consistent regardless.
+
+## Scoping + tenancy (§2.7)
+
+- `scope: {kind: "spec"}` (default) — one store per spec.
+- `scope: {kind: "session", sessionId}` — nests under
+  `<spec>/sessions/<sessionId>/` for per-conversation state (channel daemons).
+- Tenant contexts (ambient `withTenant` or an explicit `tenant` option) apply
+  the same fail-closed path fencing session-store enforces: any resolved path
+  outside the tenant's root throws (CWE-1230).
+
+## Consumers
+
+`@crewhaus/tool-plan` wraps this store as RegisteredTools (FocusRead/Write,
+PlanRead/Update/Complete, Goal*, MemoryClear). Runtime wiring (the mutable
+tail block, `context_evicted` externalization, handoff-at-teardown) lands in
+the runtime-core continuity PR; CLI verbs (`crewhaus memory clear|restore|show`)
+in the apps-cli PR.

package/dist/evidence.d.ts

@@ -0,0 +1,73 @@
+import { CrewhausError } from "@crewhaus/errors";
+export declare const DEFAULT_SESSION_ROOT_DIR = ".crewhaus/sessions";
+export type EvidenceRef = {
+    readonly toolUseId: string;
+    /** The session whose log carries the id. Optional when a default session
+     *  is supplied at verification time. */
+    readonly sessionId?: string;
+};
+export type EvidenceVerdict = "verified" | "missing" | "error_result";
+/** The proof excerpt frozen into the citing plan/goal record so evidence
+ *  outlives the transcript's TTL (design §2.4). */
+export type FrozenProof = {
+    readonly toolUseId: string;
+    /** The session (parent or child) whose log resolved the id. */
+    readonly sessionId: string;
+    readonly toolName: string;
+    /** `sha256:<hex>` over the verbatim `tool_use` input JSON. */
+    readonly inputHash: string;
+    /** Whitespace-collapsed excerpt (≤240 chars) of the `tool_result` text —
+     *  human-checkable even after the raw transcript is evicted. */
+    readonly resultDigest: string;
+    readonly verifiedAt: string;
+};
+export type EvidenceResolution = {
+    readonly ref: EvidenceRef;
+    readonly verdict: EvidenceVerdict;
+    /** Present iff `verdict === "verified"`. */
+    readonly proof?: FrozenProof;
+    /** Human-readable detail for rejected refs. */
+    readonly detail?: string;
+};
+/** Thrown by `verifyEvidence` on the first non-verified ref. Carries the
+ *  failing ref + verdict so callers (tool-plan) can emit an `action_proof`
+ *  event for the rejected attempt. */
+export declare class EvidenceError extends CrewhausError {
+    readonly name = "EvidenceError";
+    readonly toolUseId: string;
+    readonly verdict: EvidenceVerdict;
+    constructor(message: string, toolUseId: string, verdict: EvidenceVerdict);
+}
+export type VerifyEvidenceOptions = {
+    /** Where session `.jsonl` logs live. Default `.crewhaus/sessions`. */
+    readonly sessionRootDir?: string;
+    /** Session assumed for refs that omit `sessionId`. */
+    readonly defaultSessionId?: string;
+    /** Bracket-walk depth cap. Default 8. */
+    readonly maxDepth?: number;
+    readonly now?: () => Date;
+};
+/**
+ * Resolve each ref against the session logs WITHOUT throwing — one verdict
+ * per ref, in input order. `verifyEvidence` is the throwing wrapper the
+ * `proven` transition uses; this form exists so callers can audit rejected
+ * attempts (`action_proof` events with `verdict: "missing"`).
+ */
+export declare function resolveEvidence(refs: readonly EvidenceRef[], opts?: VerifyEvidenceOptions): Promise<readonly EvidenceResolution[]>;
+/**
+ * The `proven` gate: resolve every ref and throw an instructive
+ * `EvidenceError` on the first one that is missing or errored. Returns the
+ * frozen proofs (one per ref) on success.
+ */
+export declare function verifyEvidence(refs: readonly EvidenceRef[], opts?: VerifyEvidenceOptions): Promise<readonly FrozenProof[]>;
+/**
+ * Proof lifetime, mechanism (a): pin the cited sessions in
+ * `.crewhaus/retention.json` (the `pins` contract session-store's TTL
+ * eviction and `crewhaus retention` both honor) so a transcript cited by a
+ * live `proven` record is never TTL-evicted out from under it. Read-modify-
+ * write preserves every other key in the file verbatim; the write is
+ * tmp+rename atomic. Absent file → created with `{version: 1, pins: […]}`.
+ */
+export declare function appendRetentionPins(sessionIds: readonly string[], retentionPath: string): Promise<{
+    readonly added: readonly string[];
+}>;

package/dist/evidence.js

@@ -0,0 +1,238 @@
+/**
+ * The proof ladder's machine check (design §2.4): `proven` is earned by
+ * citing `toolUseId`s that RESOLVE against the append-only session event
+ * logs — the substrate runtime-core already writes verbatim (`tool_use` with
+ * full input, `tool_result` with full output + `isError`). Narration can
+ * never produce a ✓.
+ *
+ * Resolution walks the cited session's JSONL and, when the id is not found
+ * there, descends into child sessions via the `sub_agent_start` bracket
+ * events (whose payloads record `childSessionId`) — so a researcher
+ * sub-agent's tool calls are valid proof for the parent's plan.
+ *
+ * Proof-evidence lifetime (§2.4, judge-mandated): session JSONLs are
+ * TTL-evicted, which would silently degrade every `proven` to unverifiable.
+ * Verification therefore returns a FROZEN excerpt — `{toolName, inputHash,
+ * resultDigest}` — that the store writes into the citing plan/goal record,
+ * and the store additionally pins the cited session in
+ * `.crewhaus/retention.json` (see `appendRetentionPins`).
+ */
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+import { openEventLog } from "@crewhaus/event-log";
+export const DEFAULT_SESSION_ROOT_DIR = ".crewhaus/sessions";
+const SESSION_ID_REGEX = /^sess_[0-9a-f]{16}$/;
+/** How deep the sub-agent bracket walk descends before giving up. */
+const DEFAULT_MAX_DEPTH = 8;
+/** Frozen `resultDigest` excerpt length (chars). */
+const RESULT_DIGEST_MAX_CHARS = 240;
+/** Thrown by `verifyEvidence` on the first non-verified ref. Carries the
+ *  failing ref + verdict so callers (tool-plan) can emit an `action_proof`
+ *  event for the rejected attempt. */
+export class EvidenceError extends CrewhausError {
+    name = "EvidenceError";
+    toolUseId;
+    verdict;
+    constructor(message, toolUseId, verdict) {
+        super("runtime", message);
+        this.toolUseId = toolUseId;
+        this.verdict = verdict;
+    }
+}
+function collapse(text, maxChars) {
+    const t = text.replace(/\s+/g, " ").trim();
+    return t.length > maxChars ? `${t.slice(0, maxChars - 1).trimEnd()}…` : t;
+}
+function resultText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .filter((b) => b.type === "text" && typeof b.text === "string")
+            .map((b) => b.text)
+            .join("\n");
+    }
+    return "";
+}
+async function scanSession(sessionId, toolUseId, sessionRootDir) {
+    const log = await openEventLog(sessionId, { rootDir: sessionRootDir });
+    let toolUse;
+    let toolResult;
+    const childSessionIds = [];
+    for await (const ev of log.read()) {
+        if (ev.kind === "tool_use") {
+            const p = ev.payload;
+            if (p.id === toolUseId) {
+                toolUse = { name: typeof p.name === "string" ? p.name : "unknown", input: p.input };
+            }
+        }
+        else if (ev.kind === "tool_result") {
+            const p = ev.payload;
+            if (p.toolUseId === toolUseId) {
+                toolResult = { content: p.content, isError: p.isError === true };
+            }
+        }
+        else if (ev.kind === "sub_agent_start") {
+            const p = ev.payload;
+            if (typeof p.childSessionId === "string" && SESSION_ID_REGEX.test(p.childSessionId)) {
+                childSessionIds.push(p.childSessionId);
+            }
+        }
+    }
+    await log.close();
+    return {
+        ...(toolUse !== undefined ? { toolUse } : {}),
+        ...(toolResult !== undefined ? { toolResult } : {}),
+        childSessionIds,
+    };
+}
+/**
+ * Resolve each ref against the session logs WITHOUT throwing — one verdict
+ * per ref, in input order. `verifyEvidence` is the throwing wrapper the
+ * `proven` transition uses; this form exists so callers can audit rejected
+ * attempts (`action_proof` events with `verdict: "missing"`).
+ */
+export async function resolveEvidence(refs, opts = {}) {
+    const sessionRootDir = opts.sessionRootDir ?? DEFAULT_SESSION_ROOT_DIR;
+    const maxDepth = opts.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const now = opts.now ?? (() => new Date());
+    const resolutions = [];
+    for (const ref of refs) {
+        const rootSession = ref.sessionId ?? opts.defaultSessionId;
+        if (rootSession === undefined) {
+            resolutions.push({
+                ref,
+                verdict: "missing",
+                detail: `no verified evidence for ${ref.toolUseId}: no sessionId to resolve it against — cite {toolUseId, sessionId} explicitly.`,
+            });
+            continue;
+        }
+        if (!SESSION_ID_REGEX.test(rootSession)) {
+            resolutions.push({
+                ref,
+                verdict: "missing",
+                detail: `no verified evidence for ${ref.toolUseId}: "${rootSession}" is not a valid sessionId (expected sess_<16 hex>).`,
+            });
+            continue;
+        }
+        // Breadth-first over the session and its sub-agent children.
+        const queue = [
+            { sessionId: rootSession, depth: 0 },
+        ];
+        const visited = new Set();
+        let resolution;
+        while (queue.length > 0 && resolution === undefined) {
+            const item = queue.shift();
+            if (visited.has(item.sessionId))
+                continue;
+            visited.add(item.sessionId);
+            const scan = await scanSession(item.sessionId, ref.toolUseId, sessionRootDir);
+            if (scan.toolUse !== undefined && scan.toolResult !== undefined) {
+                if (scan.toolResult.isError) {
+                    resolution = {
+                        ref,
+                        verdict: "error_result",
+                        detail: `evidence ${ref.toolUseId} resolved in ${item.sessionId} but its tool_result has isError: true — a failed call cannot prove a step. Rerun the action and cite the successful toolUseId.`,
+                    };
+                }
+                else {
+                    const inputJson = JSON.stringify(scan.toolUse.input);
+                    resolution = {
+                        ref,
+                        verdict: "verified",
+                        proof: {
+                            toolUseId: ref.toolUseId,
+                            sessionId: item.sessionId,
+                            toolName: scan.toolUse.name,
+                            inputHash: `sha256:${createHash("sha256")
+                                .update(inputJson ?? "null")
+                                .digest("hex")}`,
+                            resultDigest: collapse(resultText(scan.toolResult.content), RESULT_DIGEST_MAX_CHARS),
+                            verifiedAt: now().toISOString(),
+                        },
+                    };
+                }
+            }
+            else if (item.depth < maxDepth) {
+                for (const child of scan.childSessionIds) {
+                    queue.push({ sessionId: child, depth: item.depth + 1 });
+                }
+            }
+        }
+        resolutions.push(resolution ?? {
+            ref,
+            verdict: "missing",
+            detail: `no verified evidence for ${ref.toolUseId}: run the action first, then complete the step with its toolUseId.`,
+        });
+    }
+    return resolutions;
+}
+/**
+ * The `proven` gate: resolve every ref and throw an instructive
+ * `EvidenceError` on the first one that is missing or errored. Returns the
+ * frozen proofs (one per ref) on success.
+ */
+export async function verifyEvidence(refs, opts = {}) {
+    if (refs.length === 0) {
+        throw new EvidenceError("no verified evidence: cite at least one {toolUseId} — run the action first, then complete the step with its toolUseId.", "", "missing");
+    }
+    const resolutions = await resolveEvidence(refs, opts);
+    const proofs = [];
+    for (const r of resolutions) {
+        if (r.verdict !== "verified" || r.proof === undefined) {
+            throw new EvidenceError(r.detail ??
+                `no verified evidence for ${r.ref.toolUseId}: run the action first, then complete the step with its toolUseId.`, r.ref.toolUseId, r.verdict);
+        }
+        proofs.push(r.proof);
+    }
+    return proofs;
+}
+/**
+ * Proof lifetime, mechanism (a): pin the cited sessions in
+ * `.crewhaus/retention.json` (the `pins` contract session-store's TTL
+ * eviction and `crewhaus retention` both honor) so a transcript cited by a
+ * live `proven` record is never TTL-evicted out from under it. Read-modify-
+ * write preserves every other key in the file verbatim; the write is
+ * tmp+rename atomic. Absent file → created with `{version: 1, pins: […]}`.
+ */
+export async function appendRetentionPins(sessionIds, retentionPath) {
+    const valid = [...new Set(sessionIds.filter((id) => SESSION_ID_REGEX.test(id)))];
+    if (valid.length === 0)
+        return { added: [] };
+    let config = { version: 1 };
+    if (existsSync(retentionPath)) {
+        let raw;
+        try {
+            raw = await readFile(retentionPath, "utf8");
+        }
+        catch (err) {
+            throw new CrewhausError("config", `continuity-store: cannot read ${retentionPath}`, err);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new CrewhausError("config", `continuity-store: ${retentionPath} is malformed JSON — fix it before pinning proof sessions (a half-understood retention policy must not be rewritten).`, err);
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new CrewhausError("config", `continuity-store: ${retentionPath} must be a JSON object — fix it before pinning proof sessions.`);
+        }
+        config = parsed;
+    }
+    const existing = Array.isArray(config["pins"])
+        ? config["pins"].filter((p) => typeof p === "string")
+        : [];
+    const added = valid.filter((id) => !existing.includes(id));
+    if (added.length === 0)
+        return { added: [] };
+    config["pins"] = [...existing, ...added];
+    await mkdir(dirname(retentionPath), { recursive: true });
+    const tmpPath = `${retentionPath}.tmp`;
+    await writeFile(tmpPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    await rename(tmpPath, retentionPath);
+    return { added };
+}

package/dist/handoff.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Deterministic handoff rendering (design §2.2/§2.8): `handoff.md` is rebuilt
+ * from store state at teardown with NO model call — same inputs, identical
+ * bytes (the determinism is test-pinned). It renders what session 2 needs to
+ * pick up: current focus, the active plan's steps with claimed-vs-proven
+ * marked DISTINCTLY (a claim is never conflated with a machine-verified ✓),
+ * open goals, unresolved requirements, derived next actions, and the last
+ * session id.
+ */
+import type { Goal, PlanRecord, Requirement } from "./types";
+export declare const HANDOFF_MARKER = "<!-- crewhaus:handoff -->";
+export type HandoffInput = {
+    readonly focusBody: string;
+    readonly activePlan: PlanRecord | null;
+    /** Every plan in the store (used for the "other open plans" section). */
+    readonly plans: readonly PlanRecord[];
+    readonly goals: readonly Goal[];
+    readonly requirements: readonly Requirement[];
+    readonly lastSessionId?: string;
+};
+/** `[proven]` vs `[claimed — unverified]`: the ladder's two top rungs are
+ *  never rendered alike (design §2.4). */
+export declare function renderStatus(status: string): string;
+/** Pure renderer — no clock, no filesystem, no model. */
+export declare function renderHandoff(input: HandoffInput): string;

package/dist/handoff.js

@@ -0,0 +1,100 @@
+export const HANDOFF_MARKER = "<!-- crewhaus:handoff -->";
+const NONE = "_none_";
+/** `[proven]` vs `[claimed — unverified]`: the ladder's two top rungs are
+ *  never rendered alike (design §2.4). */
+export function renderStatus(status) {
+    return status === "claimed" ? "[claimed — unverified]" : `[${status}]`;
+}
+function renderStepLine(step) {
+    const proofSuffix = step.status === "proven" && step.proofs.length > 0
+        ? ` — proof: ${step.proofs.map((p) => `${p.toolUseId} (${p.sessionId})`).join(", ")}`
+        : "";
+    return `${step.index}. ${renderStatus(step.status)} ${step.text}${proofSuffix}`;
+}
+function planSummary(plan) {
+    const proven = plan.steps.filter((s) => s.status === "proven").length;
+    return `${plan.id} — ${plan.title} (${proven}/${plan.steps.length} steps proven)`;
+}
+function renderGoalLine(goal) {
+    const progress = goal.target !== undefined
+        ? ` (${goal.current ?? 0}/${goal.target}${goal.unit !== undefined ? ` ${goal.unit}` : ""})`
+        : "";
+    return `- ${goal.id} ${renderStatus(goal.status)} ${goal.title}${progress}`;
+}
+function renderRequirementLine(req) {
+    return `- ${req.id} [${req.status}] ${JSON.stringify(req.text)} (user, ${req.source.sessionId}, turn ${req.source.turn})`;
+}
+function nextActions(plan) {
+    if (plan === null)
+        return [];
+    const actions = [];
+    for (const step of plan.steps) {
+        if (step.status === "claimed") {
+            actions.push(`Verify or redo: ${step.text} (${plan.id} step ${step.index} is claimed but unproven)`);
+        }
+    }
+    for (const step of plan.steps) {
+        if (step.status === "in_progress") {
+            actions.push(`Continue: ${step.text} (${plan.id} step ${step.index})`);
+        }
+    }
+    for (const step of plan.steps) {
+        if (step.status === "open") {
+            actions.push(`Do: ${step.text} (${plan.id} step ${step.index})`);
+        }
+    }
+    return actions.slice(0, 5);
+}
+/** Pure renderer — no clock, no filesystem, no model. */
+export function renderHandoff(input) {
+    const lines = [HANDOFF_MARKER, "# Handoff", "", "## Focus", ""];
+    lines.push(input.focusBody.trim() !== "" ? input.focusBody.trim() : "_no focus set_");
+    lines.push("", "## Active plan", "");
+    if (input.activePlan !== null) {
+        lines.push(planSummary(input.activePlan), "");
+        for (const step of input.activePlan.steps) {
+            lines.push(renderStepLine(step));
+        }
+        if (input.activePlan.steps.length === 0)
+            lines.push(NONE);
+    }
+    else {
+        lines.push(NONE);
+    }
+    const others = input.plans.filter((p) => p.id !== input.activePlan?.id && p.steps.some((s) => s.status !== "proven"));
+    if (others.length > 0) {
+        lines.push("", "## Other open plans", "");
+        for (const plan of others)
+            lines.push(`- ${planSummary(plan)}`);
+    }
+    lines.push("", "## Goals", "");
+    const openGoals = input.goals.filter((g) => g.status !== "proven");
+    if (openGoals.length > 0) {
+        for (const goal of openGoals)
+            lines.push(renderGoalLine(goal));
+    }
+    else {
+        lines.push(NONE);
+    }
+    lines.push("", "## Unresolved requirements", "");
+    const unresolved = input.requirements.filter((r) => r.status === "open");
+    if (unresolved.length > 0) {
+        for (const req of unresolved)
+            lines.push(renderRequirementLine(req));
+    }
+    else {
+        lines.push(NONE);
+    }
+    lines.push("", "## Next actions", "");
+    const actions = nextActions(input.activePlan);
+    if (actions.length > 0) {
+        actions.forEach((action, i) => lines.push(`${i + 1}. ${action}`));
+    }
+    else {
+        lines.push(NONE);
+    }
+    lines.push("", "## Last session", "");
+    lines.push(input.lastSessionId ?? "_unknown_");
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+import { CrewhausError } from "@crewhaus/errors";
+import { type Tenant } from "@crewhaus/tenancy";
+import { type EvidenceRef, type FrozenProof } from "./evidence";
+import { type AcquireLockOptions } from "./lock";
+import { type MoveToTrashResult, type RestoreResult, type TrashSnapshot } from "./trash";
+import type { ClaimableStatus, FocusState, Goal, LadderStatus, PlanRecord, Requirement, RequirementStatus } from "./types";
+export { type AcquireLockOptions, type LockHandle, type LockPolicy, ContinuityLockError, DEFAULT_LOCK_POLICY, acquireLock, withLock, } from "./lock";
+export { type MoveToTrashResult, type PurgeTrashResult, type RestoreResult, type TrashSnapshot, TRASH_DIR_NAME, TRASH_PURGE_AFTER_MS, TrashError, listTrash, moveToTrash, parseTrashTimestamp, purgeTrash, restoreFromTrash, } from "./trash";
+export { type EvidenceRef, type EvidenceResolution, type EvidenceVerdict, type FrozenProof, type VerifyEvidenceOptions, DEFAULT_SESSION_ROOT_DIR, EvidenceError, appendRetentionPins, resolveEvidence, verifyEvidence, } from "./evidence";
+export { type HandoffInput, HANDOFF_MARKER, renderHandoff, renderStatus } from "./handoff";
+export type { ClaimableStatus, FocusState, Goal, LadderStatus, PlanRecord, PlanStep, Requirement, RequirementStatus, } from "./types";
+export declare const DEFAULT_ROOT_DIR = ".crewhaus/state";
+export declare const DEFAULT_FOCUS_MAX_CHARS = 4096;
+/** §2.3 ledger cap: oldest-first eviction with a `[ledger truncated]` marker. */
+export declare const REQUIREMENTS_LEDGER_MAX_BYTES = 16384;
+export declare const FOCUS_MARKER = "<!-- crewhaus:focus -->";
+export declare class ContinuityStoreError extends CrewhausError {
+    readonly name = "ContinuityStoreError";
+    constructor(message: string, cause?: unknown);
+}
+export type ContinuityScope = {
+    readonly kind: "spec";
+} | {
+    readonly kind: "session";
+    readonly sessionId: string;
+};
+export type ClearScope = "focus" | "plans" | "goals" | "all";
+export interface ContinuityStoreOptions {
+    readonly specName: string;
+    /** Default `.crewhaus/state` (or `<tenantRoot>/state` under a tenant). */
+    readonly rootDir?: string;
+    /** Default `{kind: "spec"}`. Session scope nests the store under
+     *  `<spec>/sessions/<sessionId>/` (design §2.7). */
+    readonly scope?: ContinuityScope;
+    /** Explicit tenant to fence against (in addition to any ambient
+     *  `withTenant` context, which is always honored). */
+    readonly tenant?: Tenant;
+    /** Where session `.jsonl` event logs live, for proof verification.
+     *  Default: the `sessions` sibling of the state root
+     *  (`.crewhaus/sessions`). */
+    readonly sessionRootDir?: string;
+    /** Default session for evidence refs that omit `sessionId`. */
+    readonly sessionId?: string;
+    /** Hard cap on the focus body (design §2.1 `focusMaxChars`). Default 4096. */
+    readonly focusMaxChars?: number;
+    readonly now?: () => Date;
+    /** Lock policy overrides + warning sink (lock steals, §7.6). */
+    readonly lock?: AcquireLockOptions;
+}
+export type AppendRequirementInput = {
+    /** Existing `REQ-nnn` to update (status move), or omitted to mint the next
+     *  id. Updating requires `text` to match the stored entry VERBATIM. */
+    readonly id?: string;
+    /** The requirement, verbatim — never paraphrase. */
+    readonly text: string;
+    readonly source: {
+        readonly sessionId: string;
+        readonly turn: number;
+    };
+    readonly status?: RequirementStatus;
+};
+export type UpdateGoalInput = {
+    readonly title?: string;
+    readonly status?: LadderStatus;
+    readonly target?: number;
+    readonly current?: number;
+    readonly unit?: string;
+    /** Required when `status: "proven"` — verified like a plan step. */
+    readonly evidence?: readonly EvidenceRef[];
+};
+export interface ContinuityStore {
+    /** The scoped directory this store reads and writes. */
+    dir(): string;
+    readFocus(): Promise<FocusState | null>;
+    writeFocus(body: string): Promise<void>;
+    setActivePlan(planId: string | null): Promise<void>;
+    appendRequirement(input: AppendRequirementInput): Promise<Requirement>;
+    listRequirements(): Promise<readonly Requirement[]>;
+    createPlan(input: {
+        title: string;
+        steps?: readonly string[];
+    }): Promise<PlanRecord>;
+    getPlan(planId: string): Promise<PlanRecord | null>;
+    listPlans(): Promise<readonly PlanRecord[]>;
+    getActivePlan(): Promise<PlanRecord | null>;
+    addStep(planId: string, text: string): Promise<PlanRecord>;
+    /** Ladder moves below `proven` — always free (§2.4). */
+    setStepStatus(planId: string, step: number, status: ClaimableStatus): Promise<PlanRecord>;
+    /** The `proven` transition: verifies evidence against session event logs,
+     *  freezes proof excerpts into the plan record, and pins the cited
+     *  sessions in `.crewhaus/retention.json`. */
+    proveStep(planId: string, step: number, evidence: readonly EvidenceRef[]): Promise<PlanRecord>;
+    writeGoal(input: {
+        title: string;
+        target?: number;
+        current?: number;
+        unit?: string;
+    }): Promise<Goal>;
+    updateGoal(goalId: string, patch: UpdateGoalInput): Promise<Goal>;
+    listGoals(): Promise<readonly Goal[]>;
+    verifyEvidence(refs: readonly EvidenceRef[]): Promise<readonly FrozenProof[]>;
+    renderHandoff(opts?: {
+        lastSessionId?: string;
+    }): Promise<string>;
+    /** Renders and writes `handoff.md`; returns the file path. */
+    writeHandoff(opts?: {
+        lastSessionId?: string;
+    }): Promise<string>;
+    clear(scope: ClearScope): Promise<MoveToTrashResult>;
+    restore(ts: string): Promise<RestoreResult>;
+    listTrash(): Promise<readonly TrashSnapshot[]>;
+}
+/**
+ * Construct a continuity store. Lazy: directories and files are created on
+ * the first write. Reads never take the lock; every mutation runs under the
+ * advisory `.lock` (§7.6) and lands via tmp+rename.
+ */
+export declare function createContinuityStore(opts: ContinuityStoreOptions): ContinuityStore;