@tinycloud/replica 0.2.4-beta.2 → 0.3.0-beta.4

package/dist/sqlite.d.cts

@@ -1,4 +1,5 @@
-import { R as ReplicaStore, j as ReplicaState, b as ReplicaStatus, h as ReplicaConfig, G as GrantRecord, i as ReplicaLastError, f as LeaseToken, l as VerifiedPage, g as LocalEntry, L as ListOpts } from './types-f3-kYLQZ.cjs';
+import { ReplicaConsentAnchor } from '@tinycloud/sdk-services/kv/replication';
+import { R as ReplicaStore, j as ReplicaState, b as ReplicaStatus, h as ReplicaConfig, G as GrantRecord, i as ReplicaLastError, c as LeaseToken, l as VerifiedPage, g as LocalEntry, L as ListOpts } from './types-CQ61VnsP.cjs';
 
 type SqlValue = string | number | null | Uint8Array;
 /** The synchronous SQLite surface shared by `node:sqlite` and `bun:sqlite`. */
@@ -22,7 +23,52 @@ declare function nodeSqliteSupported(version: string): boolean;
  */
 declare function loadSqlite(): Promise<SqliteOpener>;
 
+interface SqliteLayoutEntry {
+    path: string;
+    kind: "file" | "directory" | "symlink";
+    dev: string;
+    ino: string;
+}
+type SqliteLayoutIdentity = {
+    dev: string;
+    ino: string;
+};
+/** JSON-safe exact inventory of non-mirror entries for durable approval. */
+declare function inspectSqliteReplicaLayout(dir: string, options?: {
+    allowAdapterFence?: boolean;
+}): Promise<{
+    knownEntries: SqliteLayoutEntry[];
+    unknownPaths: string[];
+    unknownEntries: SqliteLayoutEntry[];
+    rootIdentity: SqliteLayoutIdentity;
+}>;
+/** Test-only interleaving seam for replacement races between enumerated unlinks. */
+declare const LAYOUT_FAULTS: unique symbol;
+/** Lease holder only: delete enumerated files, never recurse into an unapproved child. */
+declare function removeSqliteReplicaLayout(dir: string, options?: {
+    approvedUnknown?: readonly SqliteLayoutEntry[];
+    expectedKnown?: readonly SqliteLayoutEntry[];
+    allowMissingDatabase?: boolean;
+    expectedRoot?: SqliteLayoutIdentity;
+    allowAdapterFence?: boolean;
+    [LAYOUT_FAULTS]?: {
+        beforeUnlink?(path: string): void | Promise<void>;
+    };
+}): Promise<void>;
+
 declare const DURABILITY = "sqlite-wal-synchronous-full+fsynced-blobs";
+type SqliteGrantInstall = {
+    installedAt: number;
+    effectiveExpiresAt: number;
+    consentDeadline: number;
+    consentAnchor: ReplicaConsentAnchor;
+};
+type SqliteGrantPolicy = {
+    at: number;
+    ttlMs: number;
+    consentDeadline: number;
+    consentAnchor: ReplicaConsentAnchor;
+};
 /**
  * Runs a mutation section (every database write and every filesystem
  * change). The CLI passes one that holds the profile lock briefly and
@@ -63,16 +109,33 @@ declare class SqliteReplicaStore implements ReplicaStore {
     }): Promise<{
         state: ReplicaState;
         status: ReplicaStatus;
+        grantInstall: SqliteGrantInstall | null;
+        activeGrantInstall: SqliteGrantInstall | null;
     } | null>;
     /**
      * Open the replica store in `dir`. With `create: false` a missing replica is
      * REPLICA_NOT_FOUND and nothing is written to disk.
      */
     static open(dir: string, options: SqliteReplicaStoreOptions): Promise<SqliteReplicaStore>;
+    /**
+     * A gated read borrows this controller's already-verified writable handle.
+     * Borrow before the first await: the parent may close in the callback, but
+     * its pin and native handle remain live until the snapshot releases them.
+     * Serialize BEGIN through COMMIT/ROLLBACK with writes on the shared handle.
+     */
+    readTransaction<T>(generation: number, checkGate: () => Promise<void>, section: (store: SqliteReplicaStore) => Promise<T>): Promise<T>;
     open(): Promise<ReplicaState | null>;
     init(c: ReplicaConfig): Promise<void>;
     /** Update the retention opt-in; it takes effect at the next sync. */
     setRetentionGrant(cid: string | null): Promise<void>;
+    getGrantInstall(cid: string): Promise<SqliteGrantInstall | null>;
+    /** Every installed CID, including superseded ones, for an origin-wide purge floor. */
+    grantInstallTimes(): Promise<Array<{
+        cid: string;
+        installedAt: number;
+    }>>;
+    installGatedGrant(g: GrantRecord, policy: SqliteGrantPolicy): Promise<SqliteGrantInstall>;
+    recomputeGrantInstall(g: GrantRecord, policy: SqliteGrantPolicy): Promise<SqliteGrantInstall | null>;
     installGrant(g: GrantRecord): Promise<void>;
     discardPendingGrant(cid: string, detail: string): Promise<void>;
     recordPendingGrantError(cid: string, e: ReplicaLastError): Promise<void>;
@@ -87,13 +150,19 @@ declare class SqliteReplicaStore implements ReplicaStore {
         keepSource?: boolean;
     }): Promise<void>;
     /**
-     * Remove this replica's directory for good (`tc replica reset --purge`).
-     * Fenced like a commit: `t` must still be a live lease on the database this
-     * store opened, checked under the write lock, so a paused process can
-     * never remove a replica another process took over or recreated. Allowed
-     * on a revoked replica. The store is unusable afterwards; close it.
+     * Remove the source-created mirror layout under a live lease. Unknown files
+     * are removed only when their exact preflight identities were approved.
      */
-    destroy(t: LeaseToken): Promise<void>;
+    destroy(t: LeaseToken, options?: {
+        approvedUnknown?: readonly SqliteLayoutEntry[];
+        expectedKnown?: readonly SqliteLayoutEntry[];
+        expectedRoot?: {
+            dev: string;
+            ino: string;
+        };
+        allowMissingDatabase?: boolean;
+        allowAdapterFence?: boolean;
+    }): Promise<void>;
     /**
      * Record the revocation (durable before this returns: reads are blocked
      * from here on, also after a restart), then purge. A purge that fails
@@ -111,4 +180,4 @@ declare class SqliteReplicaStore implements ReplicaStore {
     close(): Promise<void>;
 }
 
-export { DURABILITY, type MutationGuard, type SqlValue, type SqliteDatabase, type SqliteOpener, SqliteReplicaStore, type SqliteReplicaStoreOptions, loadSqlite, nodeSqliteSupported };
+export { DURABILITY, type MutationGuard, type SqlValue, type SqliteDatabase, type SqliteLayoutEntry, type SqliteOpener, SqliteReplicaStore, type SqliteReplicaStoreOptions, inspectSqliteReplicaLayout, loadSqlite, nodeSqliteSupported, removeSqliteReplicaLayout };

package/dist/sqlite.d.ts

@@ -1,4 +1,5 @@
-import { R as ReplicaStore, j as ReplicaState, b as ReplicaStatus, h as ReplicaConfig, G as GrantRecord, i as ReplicaLastError, f as LeaseToken, l as VerifiedPage, g as LocalEntry, L as ListOpts } from './types-f3-kYLQZ.js';
+import { ReplicaConsentAnchor } from '@tinycloud/sdk-services/kv/replication';
+import { R as ReplicaStore, j as ReplicaState, b as ReplicaStatus, h as ReplicaConfig, G as GrantRecord, i as ReplicaLastError, c as LeaseToken, l as VerifiedPage, g as LocalEntry, L as ListOpts } from './types-CQ61VnsP.js';
 
 type SqlValue = string | number | null | Uint8Array;
 /** The synchronous SQLite surface shared by `node:sqlite` and `bun:sqlite`. */
@@ -22,7 +23,52 @@ declare function nodeSqliteSupported(version: string): boolean;
  */
 declare function loadSqlite(): Promise<SqliteOpener>;
 
+interface SqliteLayoutEntry {
+    path: string;
+    kind: "file" | "directory" | "symlink";
+    dev: string;
+    ino: string;
+}
+type SqliteLayoutIdentity = {
+    dev: string;
+    ino: string;
+};
+/** JSON-safe exact inventory of non-mirror entries for durable approval. */
+declare function inspectSqliteReplicaLayout(dir: string, options?: {
+    allowAdapterFence?: boolean;
+}): Promise<{
+    knownEntries: SqliteLayoutEntry[];
+    unknownPaths: string[];
+    unknownEntries: SqliteLayoutEntry[];
+    rootIdentity: SqliteLayoutIdentity;
+}>;
+/** Test-only interleaving seam for replacement races between enumerated unlinks. */
+declare const LAYOUT_FAULTS: unique symbol;
+/** Lease holder only: delete enumerated files, never recurse into an unapproved child. */
+declare function removeSqliteReplicaLayout(dir: string, options?: {
+    approvedUnknown?: readonly SqliteLayoutEntry[];
+    expectedKnown?: readonly SqliteLayoutEntry[];
+    allowMissingDatabase?: boolean;
+    expectedRoot?: SqliteLayoutIdentity;
+    allowAdapterFence?: boolean;
+    [LAYOUT_FAULTS]?: {
+        beforeUnlink?(path: string): void | Promise<void>;
+    };
+}): Promise<void>;
+
 declare const DURABILITY = "sqlite-wal-synchronous-full+fsynced-blobs";
+type SqliteGrantInstall = {
+    installedAt: number;
+    effectiveExpiresAt: number;
+    consentDeadline: number;
+    consentAnchor: ReplicaConsentAnchor;
+};
+type SqliteGrantPolicy = {
+    at: number;
+    ttlMs: number;
+    consentDeadline: number;
+    consentAnchor: ReplicaConsentAnchor;
+};
 /**
  * Runs a mutation section (every database write and every filesystem
  * change). The CLI passes one that holds the profile lock briefly and
@@ -63,16 +109,33 @@ declare class SqliteReplicaStore implements ReplicaStore {
     }): Promise<{
         state: ReplicaState;
         status: ReplicaStatus;
+        grantInstall: SqliteGrantInstall | null;
+        activeGrantInstall: SqliteGrantInstall | null;
     } | null>;
     /**
      * Open the replica store in `dir`. With `create: false` a missing replica is
      * REPLICA_NOT_FOUND and nothing is written to disk.
      */
     static open(dir: string, options: SqliteReplicaStoreOptions): Promise<SqliteReplicaStore>;
+    /**
+     * A gated read borrows this controller's already-verified writable handle.
+     * Borrow before the first await: the parent may close in the callback, but
+     * its pin and native handle remain live until the snapshot releases them.
+     * Serialize BEGIN through COMMIT/ROLLBACK with writes on the shared handle.
+     */
+    readTransaction<T>(generation: number, checkGate: () => Promise<void>, section: (store: SqliteReplicaStore) => Promise<T>): Promise<T>;
     open(): Promise<ReplicaState | null>;
     init(c: ReplicaConfig): Promise<void>;
     /** Update the retention opt-in; it takes effect at the next sync. */
     setRetentionGrant(cid: string | null): Promise<void>;
+    getGrantInstall(cid: string): Promise<SqliteGrantInstall | null>;
+    /** Every installed CID, including superseded ones, for an origin-wide purge floor. */
+    grantInstallTimes(): Promise<Array<{
+        cid: string;
+        installedAt: number;
+    }>>;
+    installGatedGrant(g: GrantRecord, policy: SqliteGrantPolicy): Promise<SqliteGrantInstall>;
+    recomputeGrantInstall(g: GrantRecord, policy: SqliteGrantPolicy): Promise<SqliteGrantInstall | null>;
     installGrant(g: GrantRecord): Promise<void>;
     discardPendingGrant(cid: string, detail: string): Promise<void>;
     recordPendingGrantError(cid: string, e: ReplicaLastError): Promise<void>;
@@ -87,13 +150,19 @@ declare class SqliteReplicaStore implements ReplicaStore {
         keepSource?: boolean;
     }): Promise<void>;
     /**
-     * Remove this replica's directory for good (`tc replica reset --purge`).
-     * Fenced like a commit: `t` must still be a live lease on the database this
-     * store opened, checked under the write lock, so a paused process can
-     * never remove a replica another process took over or recreated. Allowed
-     * on a revoked replica. The store is unusable afterwards; close it.
+     * Remove the source-created mirror layout under a live lease. Unknown files
+     * are removed only when their exact preflight identities were approved.
      */
-    destroy(t: LeaseToken): Promise<void>;
+    destroy(t: LeaseToken, options?: {
+        approvedUnknown?: readonly SqliteLayoutEntry[];
+        expectedKnown?: readonly SqliteLayoutEntry[];
+        expectedRoot?: {
+            dev: string;
+            ino: string;
+        };
+        allowMissingDatabase?: boolean;
+        allowAdapterFence?: boolean;
+    }): Promise<void>;
     /**
      * Record the revocation (durable before this returns: reads are blocked
      * from here on, also after a restart), then purge. A purge that fails
@@ -111,4 +180,4 @@ declare class SqliteReplicaStore implements ReplicaStore {
     close(): Promise<void>;
 }
 
-export { DURABILITY, type MutationGuard, type SqlValue, type SqliteDatabase, type SqliteOpener, SqliteReplicaStore, type SqliteReplicaStoreOptions, loadSqlite, nodeSqliteSupported };
+export { DURABILITY, type MutationGuard, type SqlValue, type SqliteDatabase, type SqliteLayoutEntry, type SqliteOpener, SqliteReplicaStore, type SqliteReplicaStoreOptions, inspectSqliteReplicaLayout, loadSqlite, nodeSqliteSupported, removeSqliteReplicaLayout };