@holmes-lab/holmes-kit 0.19.5 → 0.20.0

package/dist/holmes/spec/entity-transaction.d.ts

@@ -0,0 +1,89 @@
+import * as fs from 'node:fs';
+export declare class EntityStoreError extends Error {
+    readonly code: string;
+    readonly holmesRefusal = true;
+    constructor(code: string, message: string);
+}
+export declare function entityContentVersion(bytes: Buffer | string): string;
+export declare function entityStat(file: string): fs.Stats | undefined;
+export declare function entityDirectory(root: string, relative: string, create?: boolean): string;
+export declare function readEntityBytes(file: string): Buffer | undefined;
+/** Stage and fsync complete bytes, then publish without replacing any existing target. */
+export declare function publishEntityRecord(root: string, relative: string, bytes: string): void;
+export interface EntityByteChange {
+    locator: string;
+    before: string | null;
+    after: string | null;
+    beforeMode?: '100644' | '100755' | null;
+    afterMode?: '100644' | '100755' | null;
+}
+/**
+ * @implements A-SPEC-639 — roll an operation's own publications back. Steps are judged in reverse
+ * order, one verdict per locator (its last step): bytes equal to `after` are the operation's own
+ * publication and are restored to `before`; bytes equal to `before` were never published; anything
+ * else is a third state and is preserved untouched.
+ */
+export declare function abandonPublishedSteps(root: string, steps: EntityByteChange[]): {
+    restored: string[];
+    untouched: string[];
+    preserved: string[];
+};
+/** @implements A-SPEC-639 — retire a pending operation as ABANDONED: its journal and owners move under `.ax/state/entity-abandoned`. */
+export declare function abandonEntityOperation(root: string, operationId: string, locator: string, expectedJournalVersion: string, outcome: {
+    restored: string[];
+    untouched: string[];
+    preserved: string[];
+}): void;
+/** Keep the complete journal as a receipt; never expose an empty pending operation. */
+export declare function entityLockOwner(root: string, locator: string): {
+    token: string;
+    version: string;
+} | null;
+export declare function entityCompletionRecord(root: string, operationId: string, locator: string, journal: Buffer): string;
+export declare function retireEntityOperation(root: string, operationId: string, locator: string, expectedJournalVersion: string): void;
+export declare function assertEntityByteInput(root: string, change: EntityByteChange): void;
+export declare function isEntityTransientName(name: string): boolean;
+/**
+ * @implements A-SPEC-640 — read-only view of a target that sees through a lone aside: when the target
+ * is absent and exactly one aside exists beside it, the aside's bytes and mode are the target's current
+ * state (a crash between move-aside and link). Several asides are reported, not resolved.
+ */
+export declare function observeEntityTarget(root: string, locator: string): {
+    bytes?: Buffer;
+    mode: '100644' | '100755' | null;
+    aside?: string;
+    asides: string[];
+};
+/**
+ * @implements A-SPEC-640 — executor-side settlement under ownership: a lone aside goes back to its
+ * absent target; temps in the steps' directories holding a step's own `after` bytes are removed.
+ * Anything else is preserved.
+ */
+export declare function settleEntityTransients(root: string, steps: EntityByteChange[]): {
+    restored: string[];
+    removed: string[];
+};
+/**
+ * Changes are generated by the owning store, not executed from an untrusted recovery payload.
+ * @implements A-SPEC-640 — updates and deletions publish through a verified aside: the original is
+ * moved aside, checked byte-for-byte (and by mode) against the expected `before`, and only then the
+ * new bytes are linked into place (or the aside removed for a deletion). A foreign write inside the
+ * window is therefore refused with the original back in place; a file that appears at the target
+ * after the move-aside is refused and both files are preserved.
+ */
+export declare function applyEntityByteChange(root: string, change: EntityByteChange): void;
+/** The shared source-publication coordination namespace, independent of every configured spec store (A-SPEC-634: exported so recovery can release it without importing the renumber module). */
+export declare const SOURCE_PUBLICATION_LOCATOR = ".ax/state/entity-renumber-source-publication";
+/** Age after which a `.staging-*` entry beside the locks is treated as abandoned by a publisher that died before its rename (A-SPEC-633). */
+export declare const LOCK_STAGING_STALE_MS: number;
+export declare function withEntityStoreLock<T>(root: string, locator: string, act: () => T): T;
+/** Keep ownership through asynchronous repository lookups and final publication. */
+export declare function withEntityStoreLockAsync<T>(root: string, locator: string, act: () => T | Promise<T>): Promise<T>;
+/**
+ * @implements A-SPEC-638 — whether the current generation of a store lock is held by a live process.
+ * Follows the owner/successor chain the recovery lock follows; a missing, malformed or released
+ * chain end, or a holder that no longer answers a signal probe, is "not alive".
+ */
+export declare function entityLockHolderAlive(root: string, locator: string): boolean;
+/** Claim a dead owner's immutable generation without deleting or replacing its lock. */
+export declare function withEntityRecoveryLock<T>(root: string, locator: string, act: () => T): T;