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

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, ReplicaAdmitHook } 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
@@ -42,6 +88,10 @@ type SqliteReplicaStoreOptions = {
     /** Clock for leases and status (ms since epoch). */
     now?: () => number;
     guard?: MutationGuard;
+    /** Quota admission, run inside applyPage's guarded mutation before any write (TC-858 S5). */
+    admit?: ReplicaAdmitHook;
+    /** Partition the store belongs to; reported to `admit`. */
+    partitionId?: string;
 };
 /**
  * The CLI replica store: SQLite (WAL, synchronous=FULL) for entries, cursor
@@ -63,16 +113,53 @@ declare class SqliteReplicaStore implements ReplicaStore {
     }): Promise<{
         state: ReplicaState;
         status: ReplicaStatus;
+        grantInstall: SqliteGrantInstall | null;
+        activeGrantInstall: SqliteGrantInstall | null;
     } | null>;
+    /**
+     * Blob content bytes on disk in the replica at `dir` (0 when absent): the writer's blob files under `blobs/`,
+     * including writer temp files and blobs no entry references any more, so garbage a failed sync
+     * left behind still counts. Counts exactly what `collectOrphans` may delete: foreign entries
+     * (stray files, symlinks, unknown names) are neither counted nor touched. Only blob content is counted: not the database, its WAL, rows or the
+     * pending store. Filesystem-only: it opens no
+     * database, so it can sum a profile's replicas under the caller's own mutation hold.
+     */
+    static contentBytes(dir: string): Promise<number>;
+    /**
+     * Remove blobs and temp files in the replica at `dir` that no committed row references: what a
+     * crash between writing blobs and committing (or between committing and collecting) leaves.
+     * Returns the number of files removed; 0 when the replica is absent or unreadable.
+     *
+     * The caller MUST hold the profile mutation guard, which every writer of this replica holds
+     * across its blob write and commit; that is what makes an unreferenced blob safe to delete
+     * (it cannot belong to an in-flight write). Never call it without that hold. The database is
+     * read only, so nothing here can take a lease or change committed state.
+     */
+    static collectOrphans(dir: string): Promise<number>;
     /**
      * 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 +174,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 +204,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, ReplicaAdmitHook } 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
@@ -42,6 +88,10 @@ type SqliteReplicaStoreOptions = {
     /** Clock for leases and status (ms since epoch). */
     now?: () => number;
     guard?: MutationGuard;
+    /** Quota admission, run inside applyPage's guarded mutation before any write (TC-858 S5). */
+    admit?: ReplicaAdmitHook;
+    /** Partition the store belongs to; reported to `admit`. */
+    partitionId?: string;
 };
 /**
  * The CLI replica store: SQLite (WAL, synchronous=FULL) for entries, cursor
@@ -63,16 +113,53 @@ declare class SqliteReplicaStore implements ReplicaStore {
     }): Promise<{
         state: ReplicaState;
         status: ReplicaStatus;
+        grantInstall: SqliteGrantInstall | null;
+        activeGrantInstall: SqliteGrantInstall | null;
     } | null>;
+    /**
+     * Blob content bytes on disk in the replica at `dir` (0 when absent): the writer's blob files under `blobs/`,
+     * including writer temp files and blobs no entry references any more, so garbage a failed sync
+     * left behind still counts. Counts exactly what `collectOrphans` may delete: foreign entries
+     * (stray files, symlinks, unknown names) are neither counted nor touched. Only blob content is counted: not the database, its WAL, rows or the
+     * pending store. Filesystem-only: it opens no
+     * database, so it can sum a profile's replicas under the caller's own mutation hold.
+     */
+    static contentBytes(dir: string): Promise<number>;
+    /**
+     * Remove blobs and temp files in the replica at `dir` that no committed row references: what a
+     * crash between writing blobs and committing (or between committing and collecting) leaves.
+     * Returns the number of files removed; 0 when the replica is absent or unreadable.
+     *
+     * The caller MUST hold the profile mutation guard, which every writer of this replica holds
+     * across its blob write and commit; that is what makes an unreferenced blob safe to delete
+     * (it cannot belong to an in-flight write). Never call it without that hold. The database is
+     * read only, so nothing here can take a lease or change committed state.
+     */
+    static collectOrphans(dir: string): Promise<number>;
     /**
      * 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 +174,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 +204,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 };