@harperfast/harper 5.2.13 → 5.3.0-beta.1

package/dist/resources/Table.d.ts

@@ -6,10 +6,14 @@
 import { type Database } from 'lmdb';
 import type { ResourceInterface, SubscriptionRequest, Id, Context, Sort, SubSelect, RequestTargetOrId } from './ResourceInterface.ts';
 import type { User } from '../security/user.ts';
+import { type WriteGeneration } from './DatabaseTransaction.ts';
+import { type RecordLockHandle, type RecordLockOptions } from './recordLock.ts';
+import { ASSERT_TRACKED_WRITABLE, GET_TRACKED_WRITE_GENERATION } from './tracked.ts';
+import { LockCoordinator, type LockControlEntry } from './recordLockCoordinator.ts';
 import { type EmbedAttribute, type Embedder } from './models/embedHook.ts';
-import { RecordObject, type Entry } from './RecordEncoder.ts';
+import { RecordObject, type Entry, type StructureCounts } from './RecordEncoder.ts';
 import { RequestTarget } from './RequestTarget.ts';
-import { Transaction as RocksTransaction } from '@harperfast/rocksdb-js';
+import { RocksDatabase, Transaction as RocksTransaction } from '@harperfast/rocksdb-js';
 import { type JsonSchemaFragment } from './jsonSchemaTypes.ts';
 export type Attribute = {
     name: string;
@@ -40,6 +44,12 @@ export type Attribute = {
     select?: any;
 };
 type MaybePromise<T> = T | Promise<T>;
+export declare const UPDATE_ATTRIBUTES_LOCK_TIMEOUT = 10000;
+export declare const UPDATE_ATTRIBUTES_LOCK_SLOW_WAIT = 1000;
+/** The wait blocks the event loop, so the locked section must stay synchronous. */
+export declare function acquireUpdateAttributesLock(rootStore: RocksDatabase, scopeDescription: string, timeout?: number): void;
+export declare function releaseUpdateAttributesLock(rootStore: RocksDatabase): void;
+export declare function withUpdateAttributesLock<Callback extends () => unknown>(rootStore: RocksDatabase, scopeDescription: string, callback: Callback & (ReturnType<Callback> extends PromiseLike<unknown> ? never : unknown)): ReturnType<Callback>;
 export declare function ignoreAlreadyDropped(error: any): void;
 export declare function freezeRecord(value: any): void;
 export declare function frozenRecordView(record: any): any;
@@ -73,7 +83,17 @@ export declare function makeTable(options: any): {
         "__#private@#version"?: number;
         "__#private@#entry"?: Entry;
         "__#private@#savingOperation"?: any;
+        "__#private@#lockHandle"?: RecordLockHandle;
+        "__#private@#lockWritable"?: boolean;
+        "__#private@#writeGeneration"?: WriteGeneration;
         getProperty: (name: string) => any;
+        /**
+         * Shared guard: if this instance is lock-writable but the handle is gone (expired or
+         * released), throw 409 before staging any write. Covers update/invalidate/relocate/delete
+         * in addition to the save() path. Every lock-writable instance carries its own handle in
+         * #lockHandle (scoped and hold alike), so we never need to search the registry here.
+         */
+        "__#private@#assertLiveHandle"(id: Id, allowClosed?: boolean): void;
         _loadRecord(target: RequestTarget, request: Context, resourceOptions?: any): MaybePromise</*elided*/ any>;
         /**
          * This is a request to explicitly ensure that the record is loaded from source, rather than only using the local record.
@@ -118,6 +138,7 @@ export declare function makeTable(options: any): {
          */
         save(): any;
         "__#private@#saveOperation"(operation: any): any;
+        "__#private@#closeWriteChain"(operation: any): void;
         addTo(property: any, value: any): void;
         subtractFrom(property: any, value: any): void;
         getMetadata(): Entry;
@@ -129,9 +150,25 @@ export declare function makeTable(options: any): {
         _writeInvalidate(id: Id, partialRecord?: any, options?: any): void;
         _writeRelocate(id: Id, options: any): void;
         /**
-         * This is intended to acquire a lock on a record from the whole cluster.
+         * Acquire an exclusive lock on this record (or on `target`'s) and return it ready for updates
+         * (harper#483, Phase 0: exclusive across every worker thread of this node). The lock is held
+         * in process memory only — no durable writes. Phase 0 contract: lock() is mutually exclusive
+         * with other lock() calls on the same key; plain writes (put/patch/delete/create) are never
+         * gated or blocked. The generation expires after `lease` if it is never released.
+         *
+         * Transaction-scoped (default): write through the returned record (or the table's static verbs
+         * in the same transaction), and the commit or abort releases it. `{ hold: true }`: the lock
+         * outlives the transaction; write through the returned record and release with `unlock()`, or
+         * let the lease expire.
+         */
+        lock(target?: RequestTargetOrId | RecordLockOptions, options?: RecordLockOptions): Promise<any>;
+        "__#private@#reloadLocked"(id: Id, holdHandle?: RecordLockHandle | null, preserveChanges?: boolean): any;
+        /**
+         * Release the lock this instance holds. Resolves true when this call cleared the native key lock.
+         * Works for both held (`{ hold: true }`) and transaction-scoped locks. After unlock() the
+         * instance is no longer lock-writable; writes through it require a fresh lock.
          */
-        lock(): void;
+        unlock(): Promise<boolean>;
         /**
          * Store the provided record data into the current resource. This is not written
          * until the corresponding transaction is committed.
@@ -156,6 +193,8 @@ export declare function makeTable(options: any): {
         _writePublish(id: Id, message: any, options?: any): void;
         validate(record: any, patch?: boolean): void;
         getUpdatedTime(): number;
+        [ASSERT_TRACKED_WRITABLE](generation?: WriteGeneration): void;
+        [GET_TRACKED_WRITE_GENERATION](): WriteGeneration;
         readonly "__#private@#id": Id;
         readonly "__#private@#context": Context | import("./ResourceInterface.ts").SourceContext;
         "__#private@#isCollection": boolean;
@@ -173,6 +212,15 @@ export declare function makeTable(options: any): {
     tableName: any;
     tableId: any;
     indices: any;
+    derivedIndexRuntime: {
+        close(dropping?: boolean): Promise<void>;
+        restoreAfterFailedDrop?(): {
+            close(dropping?: boolean): Promise<void>;
+            restoreAfterFailedDrop?(): /*elided*/ any;
+            completeDrop?(dropped?: boolean): void;
+        };
+        completeDrop?(dropped?: boolean): void;
+    } | undefined;
     audit: any;
     databasePath: any;
     databaseName: any;
@@ -237,7 +285,17 @@ export declare function makeTable(options: any): {
         "__#private@#version"?: number;
         "__#private@#entry"?: Entry;
         "__#private@#savingOperation"?: any;
+        "__#private@#lockHandle"?: RecordLockHandle;
+        "__#private@#lockWritable"?: boolean;
+        "__#private@#writeGeneration"?: WriteGeneration;
         getProperty: (name: string) => any;
+        /**
+         * Shared guard: if this instance is lock-writable but the handle is gone (expired or
+         * released), throw 409 before staging any write. Covers update/invalidate/relocate/delete
+         * in addition to the save() path. Every lock-writable instance carries its own handle in
+         * #lockHandle (scoped and hold alike), so we never need to search the registry here.
+         */
+        "__#private@#assertLiveHandle"(id: Id, allowClosed?: boolean): void;
         _loadRecord(target: RequestTarget, request: Context, resourceOptions?: any): MaybePromise</*elided*/ any>;
         /**
          * This is a request to explicitly ensure that the record is loaded from source, rather than only using the local record.
@@ -282,6 +340,7 @@ export declare function makeTable(options: any): {
          */
         save(): any;
         "__#private@#saveOperation"(operation: any): any;
+        "__#private@#closeWriteChain"(operation: any): void;
         addTo(property: any, value: any): void;
         subtractFrom(property: any, value: any): void;
         getMetadata(): Entry;
@@ -293,9 +352,25 @@ export declare function makeTable(options: any): {
         _writeInvalidate(id: Id, partialRecord?: any, options?: any): void;
         _writeRelocate(id: Id, options: any): void;
         /**
-         * This is intended to acquire a lock on a record from the whole cluster.
+         * Acquire an exclusive lock on this record (or on `target`'s) and return it ready for updates
+         * (harper#483, Phase 0: exclusive across every worker thread of this node). The lock is held
+         * in process memory only — no durable writes. Phase 0 contract: lock() is mutually exclusive
+         * with other lock() calls on the same key; plain writes (put/patch/delete/create) are never
+         * gated or blocked. The generation expires after `lease` if it is never released.
+         *
+         * Transaction-scoped (default): write through the returned record (or the table's static verbs
+         * in the same transaction), and the commit or abort releases it. `{ hold: true }`: the lock
+         * outlives the transaction; write through the returned record and release with `unlock()`, or
+         * let the lease expire.
+         */
+        lock(target?: RequestTargetOrId | RecordLockOptions, options?: RecordLockOptions): Promise<any>;
+        "__#private@#reloadLocked"(id: Id, holdHandle?: RecordLockHandle | null, preserveChanges?: boolean): any;
+        /**
+         * Release the lock this instance holds. Resolves true when this call cleared the native key lock.
+         * Works for both held (`{ hold: true }`) and transaction-scoped locks. After unlock() the
+         * instance is no longer lock-writable; writes through it require a fresh lock.
          */
-        lock(): void;
+        unlock(): Promise<boolean>;
         /**
          * Store the provided record data into the current resource. This is not written
          * until the corresponding transaction is committed.
@@ -320,6 +395,8 @@ export declare function makeTable(options: any): {
         _writePublish(id: Id, message: any, options?: any): void;
         validate(record: any, patch?: boolean): void;
         getUpdatedTime(): number;
+        [ASSERT_TRACKED_WRITABLE](generation?: WriteGeneration): void;
+        [GET_TRACKED_WRITE_GENERATION](): WriteGeneration;
         readonly "__#private@#id": Id;
         readonly "__#private@#context": Context | import("./ResourceInterface.ts").SourceContext;
         "__#private@#isCollection": boolean;
@@ -335,7 +412,17 @@ export declare function makeTable(options: any): {
         "__#private@#version"?: number;
         "__#private@#entry"?: Entry;
         "__#private@#savingOperation"?: any;
+        "__#private@#lockHandle"?: RecordLockHandle;
+        "__#private@#lockWritable"?: boolean;
+        "__#private@#writeGeneration"?: WriteGeneration;
         getProperty: (name: string) => any;
+        /**
+         * Shared guard: if this instance is lock-writable but the handle is gone (expired or
+         * released), throw 409 before staging any write. Covers update/invalidate/relocate/delete
+         * in addition to the save() path. Every lock-writable instance carries its own handle in
+         * #lockHandle (scoped and hold alike), so we never need to search the registry here.
+         */
+        "__#private@#assertLiveHandle"(id: Id, allowClosed?: boolean): void;
         _loadRecord(target: RequestTarget, request: Context, resourceOptions?: any): MaybePromise</*elided*/ any>;
         /**
          * This is a request to explicitly ensure that the record is loaded from source, rather than only using the local record.
@@ -380,6 +467,7 @@ export declare function makeTable(options: any): {
          */
         save(): any;
         "__#private@#saveOperation"(operation: any): any;
+        "__#private@#closeWriteChain"(operation: any): void;
         addTo(property: any, value: any): void;
         subtractFrom(property: any, value: any): void;
         getMetadata(): Entry;
@@ -391,9 +479,25 @@ export declare function makeTable(options: any): {
         _writeInvalidate(id: Id, partialRecord?: any, options?: any): void;
         _writeRelocate(id: Id, options: any): void;
         /**
-         * This is intended to acquire a lock on a record from the whole cluster.
+         * Acquire an exclusive lock on this record (or on `target`'s) and return it ready for updates
+         * (harper#483, Phase 0: exclusive across every worker thread of this node). The lock is held
+         * in process memory only — no durable writes. Phase 0 contract: lock() is mutually exclusive
+         * with other lock() calls on the same key; plain writes (put/patch/delete/create) are never
+         * gated or blocked. The generation expires after `lease` if it is never released.
+         *
+         * Transaction-scoped (default): write through the returned record (or the table's static verbs
+         * in the same transaction), and the commit or abort releases it. `{ hold: true }`: the lock
+         * outlives the transaction; write through the returned record and release with `unlock()`, or
+         * let the lease expire.
          */
-        lock(): void;
+        lock(target?: RequestTargetOrId | RecordLockOptions, options?: RecordLockOptions): Promise<any>;
+        "__#private@#reloadLocked"(id: Id, holdHandle?: RecordLockHandle | null, preserveChanges?: boolean): any;
+        /**
+         * Release the lock this instance holds. Resolves true when this call cleared the native key lock.
+         * Works for both held (`{ hold: true }`) and transaction-scoped locks. After unlock() the
+         * instance is no longer lock-writable; writes through it require a fresh lock.
+         */
+        unlock(): Promise<boolean>;
         /**
          * Store the provided record data into the current resource. This is not written
          * until the corresponding transaction is committed.
@@ -418,6 +522,8 @@ export declare function makeTable(options: any): {
         _writePublish(id: Id, message: any, options?: any): void;
         validate(record: any, patch?: boolean): void;
         getUpdatedTime(): number;
+        [ASSERT_TRACKED_WRITABLE](generation?: WriteGeneration): void;
+        [GET_TRACKED_WRITE_GENERATION](): WriteGeneration;
         readonly "__#private@#id": Id;
         readonly "__#private@#context": Context | import("./ResourceInterface.ts").SourceContext;
         "__#private@#isCollection": boolean;
@@ -435,12 +541,15 @@ export declare function makeTable(options: any): {
      * This also informs the scheduling for record eviction.
      * @param opts Time in seconds until records expire, or an options object with `expiration`, `eviction`,
      * and `scanInterval` (all in seconds, all optional). Number form preserves any previously configured
-     * eviction/scanInterval; object form replaces all three.
+     * eviction/scanInterval; object form replaces all three. An internal schema ownership-only call with
+     * none of those values preserves the settings already loaded from the catalog.
      */
     setTTLExpiration(opts: number | {
         expiration?: number;
         eviction?: number;
         scanInterval?: number;
+        fromSchema?: boolean;
+        isolatedApplicationOwner?: boolean;
     }): void;
     getResidencyRecord(id: Id): any;
     setResidency(getResidency?: (record: object, context: Context) => ResidencyDefinition): void;
@@ -456,6 +565,14 @@ export declare function makeTable(options: any): {
      * @returns
      */
     coerceId(id: string): number | string;
+    /**
+     * A branch's Table classes deliberately carry the BASE's logical database name so an
+     * application's schema and code resolve unchanged (harper#643). That makes every schema
+     * mutation resolve against the global catalog — a `dropTable()` through a branch would delete
+     * the live base table. Reads and writes are per-branch and unaffected; DDL is refused until a
+     * branch owns a schema identity of its own.
+     */
+    assertSchemaMutable(operation: string): void;
     dropTable(): Promise<void>;
     /**
      * Record the relocation of an entry (when a record is moved to a different node), return true if it is now located locally
@@ -467,6 +584,17 @@ export declare function makeTable(options: any): {
      * Evicting a record will remove it from a caching table. This is not considered a canonical data change, and it is assumed that retrieving this record from the source will still yield the same record, this is only removing the local copy of the record.
      */
     evict(id: any, existingRecord: any, existingVersion: any): any;
+    /**
+     * Static entry point: `Table.lock(id, options?, context?)` — creates an instance in the given,
+     * ambient, or a fresh context and delegates to the instance lock(). This shadows Resource.static
+     * lock so that both callers share the same transaction link (required for cross-instance upgrade
+     * detection).  lock() is an in-process API with no authorization hook of its own; it is not
+     * protocol-dispatched, so no allowUpdate/allowCreate check runs on acquisition.
+     *
+     * Dropping the trailing `context` leaks the key: the bare `{}` fallback is an
+     * ImmediateTransaction, which releases no record locks.
+     */
+    lock(target?: RequestTargetOrId | RecordLockOptions, options?: RecordLockOptions, context?: any): Promise<any>;
     operation(operation: any, context: any): any;
     /**
      * This is responsible for ordering and select()ing the attributes/properties from returned entries
@@ -511,6 +639,30 @@ export declare function makeTable(options: any): {
      * the table when it (re)subscribes.
      */
     writeReloadMarker(context?: any): void;
+    /**
+     * Write one cluster record-lock control entry (harper#483 Phase 1). Not local-only: replicating
+     * it IS the send.
+     *
+     * `recordId` must stay null. An entry carrying the locked key would share
+     * `(version, tableId, recordId, nodeId)` with the holder's own first write, which is stamped at
+     * exactly `ts_R`, and `RocksTransactionLogStore.getSync` answers with the FIRST entry at a
+     * timestamp and key — so `_writeUpdate`'s keyed dedup would find this one and drop that write.
+     * The payload goes in as bytes rather than through `recordUpdater`, which would run it through
+     * schema projection and the table's shared structure dictionary.
+     */
+    writeLockControlEntry(entry: LockControlEntry): Promise<number | undefined>;
+    /**
+     * The coordinator that holds this node's admissions, transport or not. Releasing and registering
+     * go here rather than through `lockCoordinator`, which answers undefined while a transport is
+     * momentarily unregistered — and a release dropped on that answer leaves the key's home holding
+     * its grant until the delegation's own deadline.
+     */
+    get admittingCoordinator(): LockCoordinator | undefined;
+    /**
+     * This table's cluster lock coordinator, created on first use and only while a transport is
+     * registered for the database. Nothing is allocated on the Phase 0 path.
+     */
+    get lockCoordinator(): LockCoordinator | undefined;
     addAttributes(attributesToAdd: Attribute[]): Promise<any>;
     removeAttributes(names: string[]): Promise<any>;
     /**
@@ -518,6 +670,8 @@ export declare function makeTable(options: any): {
      * @param options
      */
     getSize(): number;
+    /** Sizes of this table's durable record-structure dictionaries. */
+    getStructureCounts(): StructureCounts | undefined;
     getAuditSize(): number;
     /**
      * Get available/free/size storage stats for the table's underlying volume. Async because
@@ -556,8 +710,9 @@ export declare function makeTable(options: any): {
     }, void, unknown>;
     getHistoryOfRecord(id: any): Promise<any[]>;
     clear(): Promise<any[]>;
+    /** Release everything makeTable() registered process-wide; the class must not be used afterwards. */
     cleanup(): void;
-    _readTxnForContext(context: any): (RocksTransaction | import("lmdb").Transaction) & {
+    _readTxnForContext(context: any): (import("lmdb").Transaction | RocksTransaction) & {
         openTimer?: number;
         retryRisk?: number;
         isDone?: boolean;