@askdkc/kiokuko 0.1.17 → 0.1.20

package/dist/db/transaction.js

@@ -1,39 +1,68 @@
-const LOCK_RETRY_LIMIT = 5;
-function isLockError(error) {
-    return error instanceof Error && /database is locked|database table is locked|busy/i.test(error.message);
-}
-function waitForRetry(attempt) {
-    const buffer = new Int32Array(new SharedArrayBuffer(4));
-    Atomics.wait(buffer, 0, 0, attempt * 25);
+import { withSqliteLockRetry } from './sqlite-retry.js';
+/**
+ * COMMIT threw and the subsequent ROLLBACK also threw. The caller must treat
+ * the transaction as possibly committed: compensating durable side effects
+ * could otherwise turn an uncertain outcome into split-brain state.
+ */
+export class TransactionCommitUncertainError extends AggregateError {
+    commitError;
+    rollbackError;
+    constructor(commitError, rollbackError) {
+        super([commitError, rollbackError], 'Transaction commit outcome is uncertain because commit and rollback both failed');
+        this.name = 'TransactionCommitUncertainError';
+        this.commitError = commitError;
+        this.rollbackError = rollbackError;
+    }
 }
-function rollback(database) {
+export function rollbackFailedTransaction(database, operationError) {
     try {
         database.exec('ROLLBACK');
     }
-    catch {
-        // Preserve the original operation error.
+    catch (rollbackError) {
+        throw new AggregateError([operationError, rollbackError], 'Transaction operation failed and rollback also failed');
+    }
+    throw operationError;
+}
+function commitOrRollback(database) {
+    try {
+        database.exec('COMMIT');
+    }
+    catch (commitError) {
+        try {
+            database.exec('ROLLBACK');
+        }
+        catch (rollbackError) {
+            throw new TransactionCommitUncertainError(commitError, rollbackError);
+        }
+        throw commitError;
     }
 }
 /** Run a synchronous write transaction with bounded retry for SQLite lock errors only. */
 export function withImmediateTransaction(database, operation) {
-    for (let attempt = 1;; attempt += 1) {
+    return withSqliteLockRetry(() => {
+        database.exec('BEGIN IMMEDIATE');
+        let result;
         try {
-            database.exec('BEGIN IMMEDIATE');
-            try {
-                const result = operation();
-                database.exec('COMMIT');
-                return result;
-            }
-            catch (error) {
-                rollback(database);
-                throw error;
-            }
+            result = operation();
         }
         catch (error) {
-            if (!isLockError(error) || attempt >= LOCK_RETRY_LIMIT)
-                throw error;
-            waitForRetry(attempt);
+            rollbackFailedTransaction(database, error);
         }
+        commitOrRollback(database);
+        return result;
+    });
+}
+/** Run synchronous reads against one SQLite snapshot without reserving a writer lock. */
+export function withDeferredReadTransaction(database, operation) {
+    database.exec('BEGIN DEFERRED');
+    let result;
+    try {
+        result = operation();
+    }
+    catch (error) {
+        rollbackFailedTransaction(database, error);
     }
+    commitOrRollback(database);
+    return result;
 }
 //# sourceMappingURL=transaction.js.map

package/dist/db/transaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../src/db/transaction.ts"],"names":[],"mappings":"AAEA,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAE3B,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,KAAK,YAAY,KAAK,IAAI,mDAAmD,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC3G,CAAC;AAED,SAAS,YAAY,CAAC,OAAe;IACnC,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,OAAO,GAAG,EAAE,CAAC,CAAC;AAC3C,CAAC;AAED,SAAS,QAAQ,CAAC,QAAwB;IACxC,IAAI,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,yCAAyC;IAC3C,CAAC;AACH,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,wBAAwB,CAAI,QAAwB,EAAE,SAAkB;IACtF,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC;YACH,QAAQ,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;YACjC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;gBAC3B,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACxB,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,QAAQ,CAAC,QAAQ,CAAC,CAAC;gBACnB,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,OAAO,IAAI,gBAAgB;gBAAE,MAAM,KAAK,CAAC;YACpE,YAAY,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../src/db/transaction.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD;;;;GAIG;AACH,MAAM,OAAO,+BAAgC,SAAQ,cAAc;IACxD,WAAW,CAAU;IACrB,aAAa,CAAU;IAEhC,YAAY,WAAoB,EAAE,aAAsB;QACtD,KAAK,CACH,CAAC,WAAW,EAAE,aAAa,CAAC,EAC5B,iFAAiF,CAClF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,iCAAiC,CAAC;QAC9C,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;CACF;AAED,MAAM,UAAU,yBAAyB,CAAC,QAAwB,EAAE,cAAuB;IACzF,IAAI,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,aAAa,EAAE,CAAC;QACvB,MAAM,IAAI,cAAc,CACtB,CAAC,cAAc,EAAE,aAAa,CAAC,EAC/B,uDAAuD,CACxD,CAAC;IACJ,CAAC;IACD,MAAM,cAAc,CAAC;AACvB,CAAC;AAED,SAAS,gBAAgB,CAAC,QAAwB;IAChD,IAAI,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,WAAW,EAAE,CAAC;QACrB,IAAI,CAAC;YACH,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,aAAa,EAAE,CAAC;YACvB,MAAM,IAAI,+BAA+B,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;QACxE,CAAC;QACD,MAAM,WAAW,CAAC;IACpB,CAAC;AACH,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,wBAAwB,CAAI,QAAwB,EAAE,SAAkB;IACtF,OAAO,mBAAmB,CAAC,GAAG,EAAE;QAC9B,QAAQ,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QACjC,IAAI,MAAS,CAAC;QACd,IAAI,CAAC;YACH,MAAM,GAAG,SAAS,EAAE,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,yBAAyB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC7C,CAAC;QACD,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAC3B,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,2BAA2B,CAAI,QAAwB,EAAE,SAAkB;IACzF,QAAQ,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAChC,IAAI,MAAS,CAAC;IACd,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,EAAE,CAAC;IACvB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,yBAAyB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC7C,CAAC;IACD,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC3B,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/db/upgrade-backup.d.ts

@@ -1,3 +1,59 @@
-import type { SqliteDatabase } from './adapter.js';
-export declare function createPreMigrationBackup(database: SqliteDatabase, databasePath: string, fromVersion: number, toVersion: number): Promise<string>;
+import { constants } from 'node:fs';
+import type { SqliteSerializationDatabase } from './adapter.js';
+export interface BackupArtifactAttestation {
+    readonly device: bigint;
+    readonly inode: bigint;
+    readonly owner: bigint;
+    readonly group: bigint;
+    readonly mode: bigint;
+    readonly size: bigint;
+    readonly linkCount: bigint;
+    readonly sha256: string;
+}
+export interface BackupDirectoryAttestation {
+    readonly path: string;
+    readonly device: bigint;
+    readonly inode: bigint;
+    readonly owner: bigint;
+    readonly group: bigint;
+    readonly mode: bigint;
+}
+export interface PreMigrationBackup {
+    readonly path: string;
+    readonly directory: BackupDirectoryAttestation;
+    readonly artifact: BackupArtifactAttestation;
+}
+export interface BackupCreationHooks {
+    /** Runs immediately before serializing the already-open source connection. */
+    readonly beforeSerialization?: () => void | Promise<void>;
+    /** Runs after the backup directory inode is bound, before the backup worker starts. */
+    readonly afterDirectoryBound?: () => void | Promise<void>;
+    /** Runs with the unpredictable output name before its create-only open. */
+    readonly beforeArtifactWrite?: (output: string) => void | Promise<void>;
+    /** Runs after the worker attests the artifact, before it is handed to init. */
+    readonly afterArtifactWritten?: (output: string) => void | Promise<void>;
+}
+export interface SerializedBackupCreationHooks extends BackupCreationHooks {
+    /** Runs with the canonical output path before source serialization or filesystem mutation. */
+    readonly validateDestination?: (output: string) => void | Promise<void>;
+}
+export interface PosixBackupOpenFlags {
+    readonly directory: number;
+    readonly noFollow: number;
+    readonly nonBlock: number;
+}
+type BackupOpenFlagConstants = Pick<typeof constants, 'O_DIRECTORY' | 'O_NOFOLLOW' | 'O_NONBLOCK'>;
+/**
+ * Resolve the pathname-safety flags as one mandatory POSIX capability. A
+ * supported non-Windows runtime must provide every flag; dropping one to zero
+ * would silently remove the directory, no-follow, or nonblocking guarantee.
+ */
+export declare function requirePosixBackupOpenFlags(platform?: NodeJS.Platform, openFlags?: Partial<BackupOpenFlagConstants>): PosixBackupOpenFlags | undefined;
+/**
+ * Serialize the exact already-open source and install one create-only backup.
+ * The output directory must already exist and is never chmodded by this path.
+ */
+export declare function createSerializedBackupArtifact(database: SqliteSerializationDatabase, destination: string, hooks?: SerializedBackupCreationHooks): Promise<PreMigrationBackup>;
+export declare function createPreMigrationBackup(database: SqliteSerializationDatabase, databasePath: string, fromVersion: number, toVersion: number, hooks?: BackupCreationHooks): Promise<PreMigrationBackup>;
+export {};
 //# sourceMappingURL=upgrade-backup.d.ts.map

package/dist/db/upgrade-backup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade-backup.d.ts","sourceRoot":"","sources":["../../src/db/upgrade-backup.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQnD,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CAiCjB"}
+{"version":3,"file":"upgrade-backup.d.ts","sourceRoot":"","sources":["../../src/db/upgrade-backup.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAMpC,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAgChE,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,0BAA0B,CAAC;IAC/C,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,CAAC;CAC9C;AAED,MAAM,WAAW,mBAAmB;IAClC,8EAA8E;IAC9E,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,uFAAuF;IACvF,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,2EAA2E;IAC3E,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,+EAA+E;IAC/E,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1E;AAED,MAAM,WAAW,6BAA8B,SAAQ,mBAAmB;IACxE,8FAA8F;IAC9F,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,KAAK,uBAAuB,GAAG,IAAI,CACjC,OAAO,SAAS,EAChB,aAAa,GAAG,YAAY,GAAG,YAAY,CAC5C,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,SAAS,GAAE,OAAO,CAAC,uBAAuB,CAAa,GACtD,oBAAoB,GAAG,SAAS,CAkBlC;AAwrBD;;;GAGG;AACH,wBAAsB,8BAA8B,CAClD,QAAQ,EAAE,2BAA2B,EACrC,WAAW,EAAE,MAAM,EACnB,KAAK,GAAE,6BAAkC,GACxC,OAAO,CAAC,kBAAkB,CAAC,CA2C7B;AAED,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,2BAA2B,EACrC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,mBAAwB,GAC9B,OAAO,CAAC,kBAAkB,CAAC,CAgD7B"}