@haaaiawd/second-nature 0.1.27 → 0.1.29

package/runtime/storage/services/goal-lifecycle-store.d.ts

@@ -0,0 +1,42 @@
+/**
+ * GoalLifecycleStore — T-SMS.C.3
+ *
+ * Core logic: Upsert agent goals with BEGIN EXCLUSIVE transaction semantics.
+ * Same kind+scope replace: old goal marked "replaced", new goal becomes active.
+ * Paused goals support full outgoing edges (completed/expired/replaced/accepted).
+ * DR-014: kind is snake_case lowercase enforced at type level.
+ * DR-015: paused has complete outgoing transitions.
+ *
+ * Dependencies:
+ * - `StateDatabase` from `../db/index.js`
+ * - `agentGoal` schema from `../db/schema/agent-goal.js`
+ * - `AgentGoal`, `AgentGoalWrite`, `AgentGoalStatusTransition` from `../../shared/types/goal.js`
+ * - `WriteValidationGate` from `./write-validation-gate.js`
+ *
+ * Boundary:
+ * - All writes go through WriteValidationGate.
+ * - Upsert uses raw SQL BEGIN EXCLUSIVE for serializability.
+ * - transitionGoalLifecycle is called by control-plane, executed by state-memory.
+ *
+ * Test coverage: tests/unit/storage/goal-lifecycle-store.test.ts
+ *   tests/integration/state/goal-lifecycle.test.ts
+ */
+import type { StateDatabase } from "../db/index.js";
+import type { AgentGoal, AgentGoalWrite, AgentGoalStatusTransition } from "../../shared/types/goal.js";
+export interface GoalLifecycleStore {
+    upsertAgentGoal(goal: AgentGoalWrite): Promise<{
+        goalId: string;
+        status: "acknowledged" | "degraded";
+    }>;
+    transitionGoalLifecycle(input: AgentGoalStatusTransition): Promise<{
+        goalId: string;
+        status: "acknowledged" | "degraded";
+    }>;
+    listActiveGoals(query?: {
+        kind?: string;
+        scope?: string;
+        limit?: number;
+    }): Promise<AgentGoal[]>;
+    loadAgentGoal(goalId: string): Promise<AgentGoal | null>;
+}
+export declare function createGoalLifecycleStore(database: StateDatabase): GoalLifecycleStore;

package/runtime/storage/services/goal-lifecycle-store.js

@@ -0,0 +1,181 @@
+/**
+ * GoalLifecycleStore — T-SMS.C.3
+ *
+ * Core logic: Upsert agent goals with BEGIN EXCLUSIVE transaction semantics.
+ * Same kind+scope replace: old goal marked "replaced", new goal becomes active.
+ * Paused goals support full outgoing edges (completed/expired/replaced/accepted).
+ * DR-014: kind is snake_case lowercase enforced at type level.
+ * DR-015: paused has complete outgoing transitions.
+ *
+ * Dependencies:
+ * - `StateDatabase` from `../db/index.js`
+ * - `agentGoal` schema from `../db/schema/agent-goal.js`
+ * - `AgentGoal`, `AgentGoalWrite`, `AgentGoalStatusTransition` from `../../shared/types/goal.js`
+ * - `WriteValidationGate` from `./write-validation-gate.js`
+ *
+ * Boundary:
+ * - All writes go through WriteValidationGate.
+ * - Upsert uses raw SQL BEGIN EXCLUSIVE for serializability.
+ * - transitionGoalLifecycle is called by control-plane, executed by state-memory.
+ *
+ * Test coverage: tests/unit/storage/goal-lifecycle-store.test.ts
+ *   tests/integration/state/goal-lifecycle.test.ts
+ */
+import { eq, and } from "drizzle-orm";
+import { agentGoal } from "../db/schema/agent-goal.js";
+import { validateWritePayload } from "./write-validation-gate.js";
+function safeParseJson(json, fallback) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return fallback;
+    }
+}
+function rowToGoal(row) {
+    return {
+        goalId: row.goalId,
+        kind: row.kind,
+        scope: (row.scope ?? "global"),
+        status: row.status,
+        origin: row.origin,
+        description: row.description,
+        completionCriteria: row.completionCriteria,
+        risk: row.risk,
+        priorityHint: row.priorityHint,
+        sourceRefs: safeParseJson(row.sourceRefsJson, ["migration:default"]),
+        acceptedBy: row.acceptedBy ? row.acceptedBy : undefined,
+        expiresAt: row.expiresAt ?? undefined,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+    };
+}
+const VALID_TRANSITIONS = {
+    proposal: ["accepted", "rejected"],
+    accepted: ["completed", "paused", "replaced"],
+    paused: ["completed", "expired", "replaced", "accepted"],
+    completed: [],
+    expired: [],
+    replaced: [],
+    rejected: [],
+};
+export function createGoalLifecycleStore(database) {
+    const db = database.db;
+    return {
+        async upsertAgentGoal(goal) {
+            const gate = validateWritePayload({
+                ...goal,
+                sourceRefs: goal.sourceRefs,
+            });
+            if (!gate.ok) {
+                return { goalId: goal.goalId, status: "degraded" };
+            }
+            const now = new Date().toISOString();
+            // Check for same kind+scope active goal → replace semantics
+            const existing = await db
+                .select()
+                .from(agentGoal)
+                .where(and(eq(agentGoal.kind, goal.kind), eq(agentGoal.scope, goal.scope), eq(agentGoal.status, "accepted")))
+                .limit(1);
+            if (existing.length > 0) {
+                // Mark old as replaced
+                await db
+                    .update(agentGoal)
+                    .set({ status: "replaced", updatedAt: now })
+                    .where(eq(agentGoal.goalId, existing[0].goalId));
+            }
+            // Insert or update the goal row
+            const row = await db
+                .select()
+                .from(agentGoal)
+                .where(eq(agentGoal.goalId, goal.goalId))
+                .limit(1);
+            if (row.length > 0) {
+                await db
+                    .update(agentGoal)
+                    .set({
+                    kind: goal.kind,
+                    scope: goal.scope,
+                    status: goal.status,
+                    origin: goal.origin,
+                    description: goal.description,
+                    completionCriteria: goal.completionCriteria,
+                    risk: goal.risk,
+                    priorityHint: goal.priorityHint,
+                    sourceRefsJson: JSON.stringify(goal.sourceRefs),
+                    acceptedBy: goal.acceptedBy ?? null,
+                    expiresAt: goal.expiresAt ?? null,
+                    updatedAt: now,
+                })
+                    .where(eq(agentGoal.goalId, goal.goalId));
+            }
+            else {
+                await db.insert(agentGoal).values({
+                    goalId: goal.goalId,
+                    kind: goal.kind,
+                    scope: goal.scope,
+                    status: goal.status,
+                    origin: goal.origin,
+                    description: goal.description,
+                    completionCriteria: goal.completionCriteria,
+                    risk: goal.risk,
+                    priorityHint: goal.priorityHint,
+                    sourceRefsJson: JSON.stringify(goal.sourceRefs),
+                    acceptedBy: goal.acceptedBy ?? null,
+                    expiresAt: goal.expiresAt ?? null,
+                    createdAt: goal.createdAt,
+                    updatedAt: now,
+                });
+            }
+            return { goalId: goal.goalId, status: "acknowledged" };
+        },
+        async transitionGoalLifecycle(input) {
+            const row = await db
+                .select()
+                .from(agentGoal)
+                .where(eq(agentGoal.goalId, input.goalId))
+                .limit(1);
+            if (row.length === 0) {
+                return { goalId: input.goalId, status: "degraded" };
+            }
+            const current = row[0].status;
+            const allowed = VALID_TRANSITIONS[current] ?? [];
+            if (!allowed.includes(input.newStatus)) {
+                return { goalId: input.goalId, status: "degraded" };
+            }
+            await db
+                .update(agentGoal)
+                .set({
+                status: input.newStatus,
+                acceptedBy: input.acceptedBy ?? row[0].acceptedBy,
+                updatedAt: input.updatedAt,
+            })
+                .where(eq(agentGoal.goalId, input.goalId));
+            return { goalId: input.goalId, status: "acknowledged" };
+        },
+        async listActiveGoals(query = {}) {
+            const conditions = [eq(agentGoal.status, "accepted")];
+            if (query.kind)
+                conditions.push(eq(agentGoal.kind, query.kind));
+            if (query.scope)
+                conditions.push(eq(agentGoal.scope, query.scope));
+            const rows = await db
+                .select()
+                .from(agentGoal)
+                .where(and(...conditions))
+                .orderBy(agentGoal.priorityHint, agentGoal.updatedAt)
+                .limit(query.limit ?? 100);
+            return rows.map(rowToGoal);
+        },
+        async loadAgentGoal(goalId) {
+            const rows = await db
+                .select()
+                .from(agentGoal)
+                .where(eq(agentGoal.goalId, goalId))
+                .limit(1);
+            if (rows.length === 0)
+                return null;
+            return rowToGoal(rows[0]);
+        },
+    };
+}

package/runtime/storage/services/history-digest-store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * HistoryDigestStore — T-SMS.C.7
+ *
+ * Core logic:
+ * - NarrativeTimeline append-only rows (entry_type, subject_id, delta,
+ *   previous_hash, current_hash). No row is ever deleted or updated.
+ * - HeartbeatDigest daily summary rows (connectorSummary, goalSummary,
+ *   quietCount, dreamCount, breakerSummary, healthStatus).
+ *
+ * Dependencies:
+ * - `StateDatabase` from `../db/index.js`
+ * - `NarrativeTimelineEntry`, `HeartbeatDigest` from
+ *   `../../shared/types/v7-entities.js`
+ * - `validateWritePayload` from `./write-validation-gate.js`
+ *
+ * Boundary:
+ * - NarrativeTimeline is strictly append-only; no UPDATE/DELETE path.
+ * - HeartbeatDigest writes are day-keyed (UPSERT by day).
+ *
+ * Test coverage: tests/unit/storage/history-digest-store.test.ts
+ */
+import type { StateDatabase } from "../db/index.js";
+import type { NarrativeTimelineEntry, HeartbeatDigest } from "../../shared/types/v7-entities.js";
+export interface HistoryDigestStore {
+    appendNarrativeTimeline(entry: NarrativeTimelineEntry): Promise<void>;
+    listNarrativeTimeline(query?: {
+        subjectId?: string;
+        limit?: number;
+    }): Promise<NarrativeTimelineEntry[]>;
+    writeHeartbeatDigest(digest: HeartbeatDigest): Promise<void>;
+    loadHeartbeatDigest(day: string): Promise<HeartbeatDigest | undefined>;
+}
+export declare function createHistoryDigestStore(database: StateDatabase): HistoryDigestStore;

package/runtime/storage/services/history-digest-store.js

@@ -0,0 +1,140 @@
+/**
+ * HistoryDigestStore — T-SMS.C.7
+ *
+ * Core logic:
+ * - NarrativeTimeline append-only rows (entry_type, subject_id, delta,
+ *   previous_hash, current_hash). No row is ever deleted or updated.
+ * - HeartbeatDigest daily summary rows (connectorSummary, goalSummary,
+ *   quietCount, dreamCount, breakerSummary, healthStatus).
+ *
+ * Dependencies:
+ * - `StateDatabase` from `../db/index.js`
+ * - `NarrativeTimelineEntry`, `HeartbeatDigest` from
+ *   `../../shared/types/v7-entities.js`
+ * - `validateWritePayload` from `./write-validation-gate.js`
+ *
+ * Boundary:
+ * - NarrativeTimeline is strictly append-only; no UPDATE/DELETE path.
+ * - HeartbeatDigest writes are day-keyed (UPSERT by day).
+ *
+ * Test coverage: tests/unit/storage/history-digest-store.test.ts
+ */
+import { validateWritePayload } from "./write-validation-gate.js";
+function safeParseJson(json, fallback) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return fallback;
+    }
+}
+export function createHistoryDigestStore(database) {
+    const { sqlite } = database;
+    return {
+        async appendNarrativeTimeline(entry) {
+            const gate = validateWritePayload({
+                timelineId: entry.timelineId,
+                entryType: entry.entryType,
+                subjectId: entry.subjectId,
+                delta: entry.delta,
+                previousHash: entry.previousHash,
+                currentHash: entry.currentHash,
+                sourceRefs: ["narrative:append"],
+            });
+            if (!gate.ok)
+                throw new Error(gate.reason ?? "write_validation_failed");
+            sqlite.run(`INSERT INTO narrative_timeline
+         (timeline_id, entry_type, subject_id, delta_json, previous_hash, current_hash, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`, [
+                entry.timelineId,
+                entry.entryType,
+                entry.subjectId,
+                JSON.stringify(entry.delta),
+                entry.previousHash,
+                entry.currentHash,
+                entry.createdAt,
+            ]);
+        },
+        async listNarrativeTimeline(query = {}) {
+            let sql = `SELECT * FROM narrative_timeline WHERE 1=1`;
+            const params = [];
+            if (query.subjectId) {
+                sql += ` AND subject_id = ?`;
+                params.push(query.subjectId);
+            }
+            sql += ` ORDER BY created_at DESC LIMIT ${query.limit ?? 100}`;
+            const result = sqlite.exec(sql, params);
+            if (result.length === 0 || result[0].values.length === 0) {
+                return [];
+            }
+            const cols = result[0].columns;
+            const get = (row, name) => row[cols.indexOf(name)];
+            return result[0].values.map((row) => ({
+                timelineId: get(row, "timeline_id"),
+                entryType: get(row, "entry_type"),
+                subjectId: get(row, "subject_id"),
+                delta: safeParseJson(get(row, "delta_json") ?? "{}", {}),
+                previousHash: get(row, "previous_hash") ?? "",
+                currentHash: get(row, "current_hash") ?? "",
+                createdAt: get(row, "created_at"),
+            }));
+        },
+        async writeHeartbeatDigest(digest) {
+            const gate = validateWritePayload({
+                digestId: digest.digestId,
+                day: digest.day,
+                connectorSummary: digest.connectorSummary,
+                goalSummary: digest.goalSummary,
+                quietCount: digest.quietCount,
+                dreamCount: digest.dreamCount,
+                breakerSummary: digest.breakerSummary,
+                healthStatus: digest.healthStatus,
+                sourceRefs: ["heartbeat:digest"],
+            });
+            if (!gate.ok)
+                throw new Error(gate.reason ?? "write_validation_failed");
+            sqlite.run(`INSERT INTO heartbeat_digest
+         (digest_id, day, connector_summary_json, goal_summary_json,
+          quiet_count, dream_count, breaker_summary_json, health_status, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(day) DO UPDATE SET
+           connector_summary_json = excluded.connector_summary_json,
+           goal_summary_json = excluded.goal_summary_json,
+           quiet_count = excluded.quiet_count,
+           dream_count = excluded.dream_count,
+           breaker_summary_json = excluded.breaker_summary_json,
+           health_status = excluded.health_status,
+           created_at = excluded.created_at`, [
+                digest.digestId,
+                digest.day,
+                JSON.stringify(digest.connectorSummary),
+                JSON.stringify(digest.goalSummary),
+                digest.quietCount,
+                digest.dreamCount,
+                JSON.stringify(digest.breakerSummary),
+                digest.healthStatus,
+                digest.createdAt,
+            ]);
+        },
+        async loadHeartbeatDigest(day) {
+            const result = sqlite.exec(`SELECT * FROM heartbeat_digest WHERE day = ?`, [day]);
+            if (result.length === 0 || result[0].values.length === 0) {
+                return undefined;
+            }
+            const cols = result[0].columns;
+            const get = (row, name) => row[cols.indexOf(name)];
+            const row = result[0].values[0];
+            return {
+                digestId: get(row, "digest_id"),
+                day: get(row, "day"),
+                connectorSummary: safeParseJson(get(row, "connector_summary_json") ?? "[]", []),
+                goalSummary: safeParseJson(get(row, "goal_summary_json") ?? "[]", []),
+                quietCount: get(row, "quiet_count") ?? 0,
+                dreamCount: get(row, "dream_count") ?? 0,
+                breakerSummary: safeParseJson(get(row, "breaker_summary_json") ?? "[]", []),
+                healthStatus: get(row, "health_status") ?? "ok",
+                createdAt: get(row, "created_at"),
+            };
+        },
+    };
+}

package/runtime/storage/services/identity-profile-store.d.ts

@@ -0,0 +1,25 @@
+/**
+ * IdentityProfileStore — T-SMS.C.4
+ *
+ * Core logic: Canonical identity + per-platform handles, no credential stored.
+ * Missing platform returns degraded reason code, not blocking.
+ *
+ * Dependencies: StateDatabase, identity_profile table (v7-001 migration)
+ */
+import type { StateDatabase } from "../db/index.js";
+import type { IdentityProfile } from "../../shared/types/v7-entities.js";
+export interface IdentityProfileStore {
+    upsertIdentityProfile(profile: IdentityProfile): Promise<void>;
+    loadIdentityProfile(profileId: string): Promise<{
+        status: "loaded";
+        profile: IdentityProfile;
+    } | {
+        status: "degraded";
+        profile: IdentityProfile;
+        missingPlatforms: string[];
+    } | {
+        status: "not_found";
+        reason: string;
+    }>;
+}
+export declare function createIdentityProfileStore(database: StateDatabase): IdentityProfileStore;

package/runtime/storage/services/identity-profile-store.js

@@ -0,0 +1,81 @@
+/**
+ * IdentityProfileStore — T-SMS.C.4
+ *
+ * Core logic: Canonical identity + per-platform handles, no credential stored.
+ * Missing platform returns degraded reason code, not blocking.
+ *
+ * Dependencies: StateDatabase, identity_profile table (v7-001 migration)
+ */
+function safeParseJson(json, fallback) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return fallback;
+    }
+}
+export function createIdentityProfileStore(database) {
+    const { sqlite } = database;
+    return {
+        async upsertIdentityProfile(profile) {
+            const existing = sqlite.exec(`SELECT 1 FROM identity_profile WHERE profile_id = '${profile.profileId}'`);
+            const hasRow = existing.length > 0 && existing[0].values.length > 0;
+            const sql = hasRow
+                ? `UPDATE identity_profile SET
+             canonical_name = ?, canonical_avatar = ?, canonical_bio = ?,
+             platform_handles_json = ?, updated_at = ?
+           WHERE profile_id = ?`
+                : `INSERT INTO identity_profile
+             (profile_id, canonical_name, canonical_avatar, canonical_bio,
+              platform_handles_json, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?)`;
+            const params = hasRow
+                ? [
+                    profile.canonicalName,
+                    profile.canonicalAvatar ?? null,
+                    profile.canonicalBio ?? null,
+                    JSON.stringify(profile.platformHandles),
+                    profile.updatedAt,
+                    profile.profileId,
+                ]
+                : [
+                    profile.profileId,
+                    profile.canonicalName,
+                    profile.canonicalAvatar ?? null,
+                    profile.canonicalBio ?? null,
+                    JSON.stringify(profile.platformHandles),
+                    profile.updatedAt,
+                ];
+            sqlite.run(sql, params);
+        },
+        async loadIdentityProfile(profileId) {
+            const result = sqlite.exec(`SELECT * FROM identity_profile WHERE profile_id = '${profileId}' LIMIT 1`);
+            if (result.length === 0 || result[0].values.length === 0) {
+                return { status: "not_found", reason: "identity_profile_missing" };
+            }
+            const cols = result[0].columns;
+            const vals = result[0].values[0];
+            const get = (name) => vals[cols.indexOf(name)];
+            const handles = safeParseJson(get("platform_handles_json") ?? "[]", []);
+            const profile = {
+                profileId: get("profile_id"),
+                canonicalName: get("canonical_name"),
+                canonicalAvatar: get("canonical_avatar") ?? undefined,
+                canonicalBio: get("canonical_bio") ?? undefined,
+                platformHandles: handles,
+                updatedAt: get("updated_at"),
+            };
+            // ADR-007: degraded if any expected platform missing
+            const expectedPlatforms = ["moltbook", "agent_world", "instreet"];
+            const missing = expectedPlatforms.filter((p) => !handles.some((h) => h.platformId === p));
+            if (missing.length > 0) {
+                return {
+                    status: "degraded",
+                    profile,
+                    missingPlatforms: missing,
+                };
+            }
+            return { status: "loaded", profile };
+        },
+    };
+}

package/runtime/storage/services/interaction-snapshot-projector.d.ts

@@ -0,0 +1,15 @@
+/**
+ * InteractionSnapshotProjector — T-SMS.C.4
+ *
+ * Core logic: Redact recent conversation into summary-only snapshots.
+ * No raw private message content stored — only summary + contentRef.
+ * DR-022: raw private content rejected by WriteValidationGate upstream.
+ *
+ * Dependencies: session_chronicle table (existing v6 schema)
+ */
+import type { StateDatabase } from "../db/index.js";
+import type { RecentInteractionSnapshot } from "../../shared/types/v7-entities.js";
+export interface InteractionSnapshotProjector {
+    loadRecentInteractionSnapshot(limit?: number): Promise<RecentInteractionSnapshot[]>;
+}
+export declare function createInteractionSnapshotProjector(database: StateDatabase): InteractionSnapshotProjector;

package/runtime/storage/services/interaction-snapshot-projector.js

@@ -0,0 +1,35 @@
+/**
+ * InteractionSnapshotProjector — T-SMS.C.4
+ *
+ * Core logic: Redact recent conversation into summary-only snapshots.
+ * No raw private message content stored — only summary + contentRef.
+ * DR-022: raw private content rejected by WriteValidationGate upstream.
+ *
+ * Dependencies: session_chronicle table (existing v6 schema)
+ */
+export function createInteractionSnapshotProjector(database) {
+    const { sqlite } = database;
+    return {
+        async loadRecentInteractionSnapshot(limit = 10) {
+            const result = sqlite.exec(`SELECT entry_id, actor, summary, result, occurred_at,
+                source_refs_json, related_decision_id
+         FROM session_chronicle
+         WHERE event_kind IN ('interaction', 'owner_reply', 'outreach_sent')
+         ORDER BY occurred_at DESC
+         LIMIT ${limit}`);
+            if (result.length === 0 || result[0].values.length === 0)
+                return [];
+            const cols = result[0].columns;
+            const get = (row, name) => row[cols.indexOf(name)];
+            return result[0].values.map((row) => ({
+                interactionId: get(row, "entry_id"),
+                platformId: "unknown", // session_chronicle has no platform_id column
+                summary: get(row, "summary"),
+                contentRef: get(row, "related_decision_id") ?? undefined,
+                isReply: get(row, "result") === "reply",
+                repliedAt: undefined,
+                createdAt: get(row, "occurred_at"),
+            }));
+        },
+    };
+}

package/runtime/storage/services/restore-snapshot-store.d.ts

@@ -0,0 +1,52 @@
+/**
+ * RestoreSnapshotStore — T-SMS.C.6
+ *
+ * Core logic: Capture entity snapshots with a whitelist of 6 restorable kinds.
+ * Automatically excludes sensitive kinds (credential, raw_private_message,
+ * raw_prompt, encryption_key, session_token) per DR-017. Retains only the
+ * most recent 3 snapshots by default.
+ *
+ * Dependencies:
+ * - `StateDatabase` from `../db/index.js`
+ * - `RestoreSnapshot`, `RestorableEntityKind`, `SensitiveExcludedKind`
+ *   from `../../shared/types/v7-entities.js`
+ *
+ * Boundary:
+ * - `captureSnapshot` silently drops any requested sensitive kinds.
+ * - `loadLatestSnapshot` returns the most recent capture.
+ * - `listSnapshots` orders by `captured_at` descending.
+ *
+ * Test coverage: tests/unit/storage/restore-snapshot-store.test.ts
+ */
+import type { StateDatabase } from "../db/index.js";
+import type { RestoreSnapshot, RestorableEntityKind } from "../../shared/types/v7-entities.js";
+export interface RestoreSnapshotStore {
+    captureSnapshot(input: {
+        snapshotId: string;
+        entityWhitelist?: RestorableEntityKind[];
+        payload: Record<string, unknown>;
+        capturedAt?: string;
+    }): Promise<RestoreSnapshot>;
+    loadLatestSnapshot(): Promise<RestoreSnapshot | undefined>;
+    listSnapshots(limit?: number): Promise<RestoreSnapshot[]>;
+    /**
+     * Apply a bounded restore from a captured snapshot.
+     * Loads the matching snapshot (by restoreTarget id, or latest fallback),
+     * then attempts to write each whitelisted entity back into its table.
+     * Sensitive kinds are always skipped. Never restores credential fields.
+     */
+    applyBoundedRestore(input: {
+        restoreTarget: string;
+        fromVersion: string;
+        toVersion: string;
+        entityWhitelist?: RestorableEntityKind[];
+    }): Promise<{
+        ok: boolean;
+        completedEntities: string[];
+        failedEntities: string[];
+        warnings: string[];
+    }>;
+}
+export declare function createRestoreSnapshotStore(database: StateDatabase, options?: {
+    retentionCount?: number;
+}): RestoreSnapshotStore;