@hunterzhu/pulse-runtime 0.1.0

package/dist/storage/persistence.d.ts

@@ -0,0 +1,183 @@
+import type { JsonValue, RuntimeEvent, RuntimeState } from '../core/types.js';
+import { type FactInboxDedupeArchiveBatch, type FactInboxDedupeArchiveWriter, type FactInboxSnapshot } from '../core/inbox.js';
+import { FileRuntimeSessionStore, SqliteRuntimeSessionStore, type RuntimeSessionStore, type SessionSnapshot } from './session.js';
+import { EffectOutbox, type OutboxSnapshot } from './outbox.js';
+import { MutationLog, type MutationLogSnapshot } from './mutation-log.js';
+import type { QuarantineEntry, QuarantineScope } from '../lifecycle/scopes.js';
+import { SessionStoragePolicy, type StoragePolicySnapshot } from './policy.js';
+export interface RuntimePersistenceSnapshot {
+    schemaVersion: 1;
+    state: SessionSnapshot;
+    mutationLog: MutationLogSnapshot;
+    outbox: OutboxSnapshot;
+    quarantine?: QuarantineEntry[];
+    storage?: StoragePolicySnapshot;
+    factInbox?: FactInboxSnapshot;
+    snapshotBodies?: 'inline' | 'external';
+    externalSnapshotRefs?: string[];
+    checkpoint?: {
+        schemaVersion: 1;
+        logWatermark: number;
+        eventWatermark?: number;
+        state: SessionSnapshot;
+    };
+    resultBodies?: 'inline' | 'external';
+    externalResultRefs?: string[];
+    eventArchive?: {
+        through: number;
+    };
+    compatibility?: RuntimePersistenceCompatibility;
+    integrity?: {
+        algorithm: 'sha256';
+        digest: string;
+    };
+}
+export interface RuntimePersistenceCompatibility {
+    schemaVersion: 1;
+    programVersions: Record<string, string>;
+    toolVersions: Record<string, string>;
+    policyVersion?: string;
+    routerVersion?: string;
+}
+export interface RuntimeResultStore {
+    save(ref: string, value: JsonValue): Promise<void>;
+    load(ref: string): Promise<JsonValue | undefined>;
+}
+export interface RuntimeSnapshotStore {
+    save(ref: string, value: JsonValue): Promise<void>;
+    load(ref: string): Promise<JsonValue | undefined>;
+}
+export interface RuntimeEventArchive {
+    append(events: RuntimeEvent[]): Promise<void>;
+    read(fromSeq: number, toSeq?: number): Promise<RuntimeEvent[]>;
+}
+/** Atomic, idempotent file-backed body store usable as both ResultStore and SnapshotStore. */
+export declare class FileRuntimeContentStore implements RuntimeResultStore, RuntimeSnapshotStore {
+    readonly directory: string;
+    constructor(directory: string);
+    save(ref: string, value: JsonValue): Promise<void>;
+    load(ref: string): Promise<JsonValue | undefined>;
+    private pathFor;
+    private readEnvelope;
+    private withLock;
+}
+/** SQLite-backed result/snapshot body store with idempotent writes and conflict detection. */
+export declare class SqliteRuntimeContentStore implements RuntimeResultStore, RuntimeSnapshotStore {
+    readonly filePath: string;
+    readonly namespace: 'result' | 'snapshot';
+    private database;
+    private tail;
+    constructor(filePath: string, namespace: 'result' | 'snapshot');
+    save(ref: string, value: JsonValue): Promise<void>;
+    load(ref: string): Promise<JsonValue | undefined>;
+    close(): Promise<void>;
+    private open;
+    private enqueue;
+}
+/** SQLite-backed fact event archive with idempotent sequence append and range reads. */
+export declare class SqliteRuntimeEventArchive implements RuntimeEventArchive {
+    readonly filePath: string;
+    private database;
+    private tail;
+    constructor(filePath: string);
+    append(events: RuntimeEvent[]): Promise<void>;
+    read(fromSeq: number, toSeq?: number): Promise<RuntimeEvent[]>;
+    close(): Promise<void>;
+    private open;
+    private enqueue;
+}
+/** Atomic file-backed EventArchive with idempotent sequence append and range reads. */
+export declare class FileRuntimeEventArchive implements RuntimeEventArchive {
+    readonly directory: string;
+    private readonly filePath;
+    constructor(directory: string);
+    append(events: RuntimeEvent[]): Promise<void>;
+    read(fromSeq: number, toSeq?: number): Promise<RuntimeEvent[]>;
+    private readEnvelope;
+    private writeEnvelope;
+    private withLock;
+}
+/** Durable file-backed membership archive for compacted FactInbox ids. */
+export declare class FileRuntimeFactInboxDedupeArchive implements FactInboxDedupeArchiveWriter {
+    readonly directory: string;
+    readonly archiveId = "pulse.fact-inbox-dedupe.file.v1";
+    private readonly filePath;
+    private entries;
+    constructor(directory: string);
+    get watermark(): number;
+    contains(eventId: string, receivedSeq?: number): boolean;
+    digestThrough(through: number): string;
+    append(batch: FactInboxDedupeArchiveBatch): Promise<void>;
+    private withLock;
+}
+/** Durable SQLite membership archive for compacted FactInbox ids. */
+export declare class SqliteRuntimeFactInboxDedupeArchive implements FactInboxDedupeArchiveWriter {
+    readonly filePath: string;
+    readonly archiveId = "pulse.fact-inbox-dedupe.sqlite.v1";
+    private database;
+    private tail;
+    private entries;
+    constructor(filePath: string);
+    get watermark(): number;
+    contains(eventId: string, receivedSeq?: number): boolean;
+    digestThrough(through: number): string;
+    append(batch: FactInboxDedupeArchiveBatch): Promise<void>;
+    close(): Promise<void>;
+    private open;
+    private enqueue;
+}
+export interface RuntimePersistenceBackend {
+    load(): Promise<RuntimePersistenceSnapshot | undefined>;
+    save(snapshot: RuntimePersistenceSnapshot, expectedDigest?: string): Promise<void>;
+    sessionStore?: RuntimeSessionStore;
+    resultStore?: RuntimeResultStore;
+    snapshotStore?: RuntimeSnapshotStore;
+    eventArchive?: RuntimeEventArchive;
+    factInboxDedupeArchive?: FactInboxDedupeArchiveWriter;
+}
+export declare function withRuntimePersistenceIntegrity(snapshot: RuntimePersistenceSnapshot): RuntimePersistenceSnapshot;
+export declare function validateRuntimePersistenceSnapshot(snapshot: RuntimePersistenceSnapshot | JsonValue): void;
+export declare class FileRuntimePersistenceBackend implements RuntimePersistenceBackend {
+    readonly filePath: string;
+    private pending;
+    readonly sessionStore: FileRuntimeSessionStore;
+    readonly factInboxDedupeArchive: FileRuntimeFactInboxDedupeArchive;
+    constructor(filePath: string);
+    load(): Promise<RuntimePersistenceSnapshot | undefined>;
+    save(snapshot: RuntimePersistenceSnapshot, expectedDigest?: string): Promise<void>;
+}
+/** Durable single-snapshot backend using Node's built-in SQLite transaction support. */
+export declare class SqliteRuntimePersistenceBackend implements RuntimePersistenceBackend {
+    readonly filePath: string;
+    private database;
+    private tail;
+    readonly resultStore: SqliteRuntimeContentStore;
+    readonly snapshotStore: SqliteRuntimeContentStore;
+    readonly eventArchive: SqliteRuntimeEventArchive;
+    readonly factInboxDedupeArchive: SqliteRuntimeFactInboxDedupeArchive;
+    readonly sessionStore: SqliteRuntimeSessionStore;
+    constructor(filePath: string);
+    load(): Promise<RuntimePersistenceSnapshot | undefined>;
+    save(snapshot: RuntimePersistenceSnapshot, expectedDigest?: string): Promise<void>;
+    close(): Promise<void>;
+    private open;
+    private enqueue;
+}
+export declare function exportRuntimePersistence(state: RuntimeState, mutationLog: MutationLog, outbox: EffectOutbox, quarantine?: QuarantineScope, storagePolicy?: SessionStoragePolicy, factInbox?: FactInboxSnapshot, compatibility?: RuntimePersistenceCompatibility): RuntimePersistenceSnapshot;
+export declare function exportRuntimeCheckpoint(state: RuntimeState, mutationLog: MutationLog, outbox: EffectOutbox, quarantine?: QuarantineScope, storagePolicy?: SessionStoragePolicy, options?: {
+    compactEventsThrough?: number;
+}, factInbox?: FactInboxSnapshot, compatibility?: RuntimePersistenceCompatibility): RuntimePersistenceSnapshot;
+export declare function externalizeRuntimeResultBodies(snapshot: RuntimePersistenceSnapshot, store: RuntimeResultStore): Promise<RuntimePersistenceSnapshot>;
+export declare function externalizeRuntimeSnapshotBodies(snapshot: RuntimePersistenceSnapshot, store: RuntimeSnapshotStore): Promise<RuntimePersistenceSnapshot>;
+export declare function hydrateRuntimeSnapshotBodies(snapshot: RuntimePersistenceSnapshot, store: RuntimeSnapshotStore): Promise<RuntimePersistenceSnapshot>;
+export declare function hydrateRuntimeResultBodies(snapshot: RuntimePersistenceSnapshot, store: RuntimeResultStore): Promise<RuntimePersistenceSnapshot>;
+export declare function serializeRuntimePersistence(state: RuntimeState, mutationLog: MutationLog, outbox: EffectOutbox, storagePolicy?: SessionStoragePolicy): JsonValue;
+export declare function importRuntimePersistence(snapshot: RuntimePersistenceSnapshot | JsonValue): {
+    state: RuntimeState;
+    mutationLog: MutationLog;
+    outbox: EffectOutbox;
+    quarantine?: QuarantineEntry[];
+    storagePolicy?: SessionStoragePolicy;
+    factInbox?: FactInboxSnapshot;
+    compatibility?: RuntimePersistenceCompatibility;
+};