@feltdb/core 0.13.0 → 0.15.0

package/dist/embedded-transaction.js

@@ -95,6 +95,10 @@ export function recordKey(collection, id) {
     return `${collection}:${id}`;
 }
 const SEGMENT = /^[A-Za-z0-9._-]{1,128}$/;
+/** The version a guard fences on, whichever spelling supplied it. */
+function fencedVersion(guard) {
+    return guard.expectedVersion ?? guard.ifVersion;
+}
 /**
  * Whether the request is well-formed, judged without any stored state.
  *
@@ -109,6 +113,11 @@ function structuralRefusal(request) {
     if (request.operations.length === 0)
         return invalid('a transaction requires at least one operation');
     const seen = new Set();
+    for (const guarded of [...request.operations, ...(request.preconditions ?? [])]) {
+        if (guarded.ifVersion !== undefined && guarded.expectedVersion !== undefined && guarded.ifVersion !== guarded.expectedVersion) {
+            return invalid(`${guarded.collection}:${guarded.id} supplies ifVersion ${guarded.ifVersion} and expectedVersion ${guarded.expectedVersion}; they are the same predicate`);
+        }
+    }
     for (const operation of request.operations) {
         if (!SEGMENT.test(operation.collection) || !SEGMENT.test(operation.id)) {
             return invalid(`invalid collection or id: ${operation.collection}:${operation.id}`);
@@ -195,16 +204,24 @@ export function decideTransaction(request, state, digest) {
     }
     // Preconditions first, before any operation is staged, so a failure cannot
     // leave a prefix of the transaction decided.
+    //
+    // `ifVersion` is the public spelling of `expectedVersion` and reaches this
+    // boundary unnormalised from callers below `db.transaction` (collections,
+    // agent state, composition). It is the same predicate, so it is evaluated
+    // here rather than counted as "constrains something" and then skipped.
     const guards = [
-        ...(request.preconditions ?? []).map(condition => ({ ...condition })),
+        ...(request.preconditions ?? []).map(condition => ({
+            ...condition,
+            expectedVersion: fencedVersion(condition),
+        })),
         ...request.operations
-            .filter(operation => operation.expectedVersion !== undefined
+            .filter(operation => fencedVersion(operation) !== undefined
             || operation.expectedEpoch !== undefined
             || operation.expectedLeaseId !== undefined)
             .map(operation => ({
             collection: operation.collection,
             id: operation.id,
-            expectedVersion: operation.expectedVersion,
+            expectedVersion: fencedVersion(operation),
             expectedEpoch: operation.expectedEpoch,
             expectedLeaseId: operation.expectedLeaseId,
         })),
@@ -214,11 +231,12 @@ export function decideTransaction(request, state, digest) {
             kind: 'reject',
             reason: 'this runtime cannot evaluate transaction preconditions, so it refuses the '
                 + 'transaction rather than committing it unconditionally',
+            code: 'CONTRACT_UNSUPPORTED',
         };
     }
     for (const guard of guards) {
         if (!SEGMENT.test(guard.collection) || !SEGMENT.test(String(guard.id))) {
-            return { kind: 'reject', reason: `invalid collection or id: ${guard.collection}:${guard.id}` };
+            return { kind: 'reject', reason: `invalid collection or id: ${guard.collection}:${guard.id}`, code: 'INVALID_REQUEST' };
         }
         const constrains = guard.requireAbsent === true
             || guard.expectedVersion !== undefined
@@ -228,6 +246,7 @@ export function decideTransaction(request, state, digest) {
             return {
                 kind: 'reject',
                 reason: `precondition on ${guard.collection}:${guard.id} constrains nothing`,
+                code: 'INVALID_REQUEST',
             };
         }
         const key = recordKey(guard.collection, String(guard.id));
@@ -237,7 +256,7 @@ export function decideTransaction(request, state, digest) {
                 return {
                     kind: 'reject',
                     reason: `PRECONDITION_FAILED:${key}:record already exists`,
-                    failure: { predicate: 'present', collection: guard.collection, key },
+                    failure: { predicate: 'present', collection: guard.collection, id: String(guard.id), key },
                 };
             }
             continue;
@@ -246,7 +265,7 @@ export function decideTransaction(request, state, digest) {
             return {
                 kind: 'reject',
                 reason: `PRECONDITION_FAILED:${key}:record does not exist`,
-                failure: { predicate: 'missing', collection: guard.collection, key },
+                failure: { predicate: 'missing', collection: guard.collection, id: String(guard.id), key },
             };
         }
         if (guard.expectedVersion !== undefined) {
@@ -258,6 +277,7 @@ export function decideTransaction(request, state, digest) {
                     failure: {
                         predicate: 'version',
                         collection: guard.collection,
+                        id: String(guard.id),
                         key,
                         expected: guard.expectedVersion,
                         actual,
@@ -275,6 +295,7 @@ export function decideTransaction(request, state, digest) {
                     failure: {
                         predicate: 'epoch',
                         collection: guard.collection,
+                        id: String(guard.id),
                         key,
                         expected: guard.expectedEpoch,
                         actual,
@@ -293,6 +314,7 @@ export function decideTransaction(request, state, digest) {
                     failure: {
                         predicate: 'lease',
                         collection: guard.collection,
+                        id: String(guard.id),
                         key,
                         expected: guard.expectedLeaseId,
                         actual: held ?? null,
@@ -310,18 +332,19 @@ export function decideTransaction(request, state, digest) {
                 kind: 'reject',
                 reason: 'this runtime cannot evaluate read-basis fences inside its commit boundary, so it refuses the '
                     + 'transaction rather than committing it unfenced',
+                code: 'CONTRACT_UNSUPPORTED',
             };
         }
         for (const fence of fences) {
             if (typeof fence?.token !== 'string' || !fence.token.startsWith(EMBEDDED_READ_BASIS_PREFIX)) {
-                return { kind: 'reject', reason: 'a read basis was not issued by this authority' };
+                return { kind: 'reject', reason: 'a read basis was not issued by this authority', code: 'INVALID_REQUEST' };
             }
             let actual;
             try {
                 actual = readBasisToken(fence.reads, { read: state.read, scan: state.scan });
             }
             catch (error) {
-                return { kind: 'reject', reason: `invalid read basis: ${error instanceof Error ? error.message : String(error)}` };
+                return { kind: 'reject', reason: `invalid read basis: ${error instanceof Error ? error.message : String(error)}`, code: 'INVALID_REQUEST' };
             }
             if (actual !== fence.token) {
                 const first = normaliseReadSet(fence.reads);
@@ -345,6 +368,7 @@ export function decideTransaction(request, state, digest) {
             return {
                 kind: 'reject',
                 reason: `invalid collection or id: ${operation.collection}:${operation.id}`,
+                code: 'INVALID_REQUEST',
             };
         }
         const key = recordKey(operation.collection, operation.id);
@@ -352,30 +376,38 @@ export function decideTransaction(request, state, digest) {
             return {
                 kind: 'reject',
                 reason: `PRECONDITION_FAILED:${key}:record already exists`,
-                failure: { predicate: 'present', collection: operation.collection, key },
+                failure: { predicate: 'present', collection: operation.collection, id: operation.id, key },
             };
         }
         // A requireAbsent create begins the authority-owned version lifecycle at
-        // 1. A write fenced by expectedVersion is validated at N and written at
-        // N + 1. Both are resolved in the same decision the runtime applies
-        // atomically. An unconditional write remains verbatim, and a delete has no
-        // record left to carry a version.
+        // 1. A write fenced by expectedVersion -- on the operation itself or by a
+        // transaction-level precondition on the same record -- is validated at N
+        // and written at N + 1. Both are resolved in the same decision the runtime
+        // applies atomically. An unconditional write remains verbatim, and a
+        // delete has no record left to carry a version.
+        //
+        // Where the fence is declared does not matter, and must not: a guard
+        // `preconditions: [{ A, ifVersion: N }]` beside a write of A that left the
+        // version alone would let a second transaction guarded on N commit after
+        // the first, which is the exclusive progression the guard exists to
+        // provide. The Rust authority applies the same rule.
         //
         // The value the caller supplied for __version is replaced rather than
         // honoured, because a caller that computes a different next version must
         // not be able to install it.
         // See docs/architecture/transaction-version-contract.md.
+        const sameRecord = (guard) => guard.collection === operation.collection
+            && String(guard.id) === operation.id;
         const guardedCreate = operation.requireAbsent === true
-            || guards.some(guard => guard.requireAbsent === true
-                && guard.collection === operation.collection
-                && String(guard.id) === operation.id);
+            || guards.some(guard => guard.requireAbsent === true && sameRecord(guard));
+        const fencedAt = guards.find(guard => guard.expectedVersion !== undefined && sameRecord(guard))?.expectedVersion;
         const value = operation.value === undefined
             ? undefined
             : guardedCreate
                 ? { ...operation.value, id: operation.id, __version: 1 }
-                : operation.expectedVersion === undefined
+                : fencedAt === undefined
                     ? { ...operation.value, id: operation.id }
-                    : { ...operation.value, id: operation.id, __version: operation.expectedVersion + 1 };
+                    : { ...operation.value, id: operation.id, __version: fencedAt + 1 };
         mutations.push({
             key,
             collection: operation.collection,
@@ -437,7 +469,11 @@ export function embeddedDuplicate(request, plan) {
 export class EmbeddedTransactionRejected extends Error {
     feltdbCode;
     feltdbConflict;
-    /** Set when the request itself was malformed, as opposed to refused by state. */
+    /**
+     * Set when the request itself was malformed (`INVALID_REQUEST`) or asks for
+     * something this runtime cannot evaluate (`CONTRACT_UNSUPPORTED`), as
+     * opposed to refused by state.
+     */
     code;
     constructor(reason, failure, code) {
         super(reason);

package/dist/error-codes.d.ts

@@ -53,13 +53,42 @@ export declare enum FeltDBErrorCode {
     SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
     AUTHORITY_SCOPE_REQUIRED = "AUTHORITY_SCOPE_REQUIRED",
     AUTHORITY_SCOPE_INVALID = "AUTHORITY_SCOPE_INVALID",
-    AUTHORITY_SCOPE_MISMATCH = "AUTHORITY_SCOPE_MISMATCH"
+    AUTHORITY_SCOPE_MISMATCH = "AUTHORITY_SCOPE_MISMATCH",
+    /** A local state directory is open exclusively by another live process. */
+    STATE_LOCKED = "STATE_LOCKED",
+    /** Stored content no longer hashes to its address. The bytes were not returned. */
+    CONTENT_INTEGRITY_FAILURE = "CONTENT_INTEGRITY_FAILURE"
 }
 export declare class FeltDBServiceError extends Error {
     readonly code: FeltDBErrorCode | string;
     readonly requestId?: string | undefined;
     readonly status?: number | undefined;
-    constructor(message: string, code: FeltDBErrorCode | string, requestId?: string | undefined, status?: number | undefined);
+    /** The authority's structured error body, when it answered with one. */
+    readonly body?: Record<string, unknown>;
+    constructor(message: string, code: FeltDBErrorCode | string, requestId?: string | undefined, status?: number | undefined, body?: Record<string, unknown>);
+    /** The body's structured `details`, when it carried any (e.g. a reused idempotency key's reason). */
+    get details(): Record<string, unknown> | undefined;
+}
+/**
+ * The local file runtime's state directory is held exclusively by another
+ * process. Nothing was opened, read, or modified.
+ *
+ * `owner` is what the lock file records about its holder. Close the other
+ * process, or, if it is gone and its lock could not be judged stale (another
+ * host, an unreadable lock), remove `lockPath` by hand.
+ */
+export declare class LocalStateLockedError extends FeltDBServiceError {
+    readonly lockPath: string;
+    readonly owner: {
+        pid?: number;
+        host?: string;
+        acquiredAt?: string;
+    };
+    constructor(lockPath: string, owner: {
+        pid?: number;
+        host?: string;
+        acquiredAt?: string;
+    }, detail?: string);
 }
 /**
  * Error response structure that all FeltDB APIs must return

package/dist/error-codes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../src/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,oBAAY,eAAe;IACzB,eAAe,oBAAoB;IACnC,YAAY,iBAAiB;IAC7B,gBAAgB,qBAAqB;IACrC,eAAe,oBAAoB;IACnC,cAAc,mBAAmB;IACjC,sBAAsB,2BAA2B;IACjD,kBAAkB,uBAAuB;IACzC,gBAAgB,qBAAqB;IACrC,oBAAoB,yBAAyB;IAC7C,6BAA6B;IAC7B,EAAE,OAAO;IAET,wEAAwE;IACxE,QAAQ,aAAa;IAErB,2DAA2D;IAC3D,mBAAmB,wBAAwB;IAE3C,gEAAgE;IAChE,QAAQ,aAAa;IAErB,6DAA6D;IAC7D,cAAc,mBAAmB;IACjC,uBAAuB,4BAA4B;IACnD,qBAAqB,0BAA0B;IAC/C,SAAS,cAAc;IACvB,SAAS,cAAc;IACvB,gBAAgB,qBAAqB;IACrC,oBAAoB,yBAAyB;IAC7C,gFAAgF;IAChF,wBAAwB,6BAA6B;IACrD;sEACkE;IAClE,sBAAsB,2BAA2B;IACjD,aAAa,kBAAkB;IAC/B,oBAAoB,yBAAyB;IAC7C,kBAAkB,uBAAuB;IACzC,eAAe,oBAAoB;IACnC,oBAAoB,yBAAyB;IAC7C,gBAAgB,qBAAqB;IACrC,mBAAmB,wBAAwB;IAC3C,wBAAwB,6BAA6B;IACrD,uBAAuB,4BAA4B;IACnD,wBAAwB,6BAA6B;CACtD;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;gBAHxB,OAAO,EAAE,MAAM,EACN,IAAI,EAAE,eAAe,GAAG,MAAM,EAC9B,SAAS,CAAC,EAAE,MAAM,YAAA,EAClB,MAAM,CAAC,EAAE,MAAM,YAAA;CAE3B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,wCAAwC;IACxC,IAAI,EAAE,eAAe,GAAG,MAAM,CAAC;IAE/B,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAEhB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IAEnB,mCAAmC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IAEpB,gEAAgE;IAChE,aAAa,CAAC,EAAE,eAAe,GAAG,YAAY,GAAG,mBAAmB,GAAG,iBAAiB,CAAC;CAC1F;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,GAAG,OAAO,CAGxE;AAED,MAAM,MAAM,yBAAyB,GACjC,WAAW,GACX,eAAe,GACf,yBAAyB,GACzB,4BAA4B,CAAC;AAEjC,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,GAAG,yBAAyB,CAevF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,GAAG,qBAAqB,GAAG,gBAAgB,GAAG,YAAY,CAQxH"}
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../src/error-codes.ts"],"names":[],"mappings":"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"}

package/dist/error-codes.js

@@ -55,17 +55,53 @@ export var FeltDBErrorCode;
     FeltDBErrorCode["AUTHORITY_SCOPE_REQUIRED"] = "AUTHORITY_SCOPE_REQUIRED";
     FeltDBErrorCode["AUTHORITY_SCOPE_INVALID"] = "AUTHORITY_SCOPE_INVALID";
     FeltDBErrorCode["AUTHORITY_SCOPE_MISMATCH"] = "AUTHORITY_SCOPE_MISMATCH";
+    /** A local state directory is open exclusively by another live process. */
+    FeltDBErrorCode["STATE_LOCKED"] = "STATE_LOCKED";
+    /** Stored content no longer hashes to its address. The bytes were not returned. */
+    FeltDBErrorCode["CONTENT_INTEGRITY_FAILURE"] = "CONTENT_INTEGRITY_FAILURE";
 })(FeltDBErrorCode || (FeltDBErrorCode = {}));
 export class FeltDBServiceError extends Error {
     code;
     requestId;
     status;
-    constructor(message, code, requestId, status) {
+    /** The authority's structured error body, when it answered with one. */
+    body;
+    constructor(message, code, requestId, status, body) {
         super(message);
         this.code = code;
         this.requestId = requestId;
         this.status = status;
         this.name = 'FeltDBServiceError';
+        if (body !== undefined)
+            this.body = body;
+    }
+    /** The body's structured `details`, when it carried any (e.g. a reused idempotency key's reason). */
+    get details() {
+        const details = this.body?.details;
+        return details && typeof details === 'object' && !Array.isArray(details) ? details : undefined;
+    }
+}
+/**
+ * The local file runtime's state directory is held exclusively by another
+ * process. Nothing was opened, read, or modified.
+ *
+ * `owner` is what the lock file records about its holder. Close the other
+ * process, or, if it is gone and its lock could not be judged stale (another
+ * host, an unreadable lock), remove `lockPath` by hand.
+ */
+export class LocalStateLockedError extends FeltDBServiceError {
+    lockPath;
+    owner;
+    constructor(lockPath, owner, detail) {
+        super(`STATE_LOCKED: ${lockPath.replace(/[\\/][^\\/]+$/, '')} is open exclusively by `
+            + `${owner.pid === undefined ? 'another process' : `process ${owner.pid}`}`
+            + `${owner.host ? ` on ${owner.host}` : ''}${owner.acquiredAt ? ` since ${owner.acquiredAt}` : ''}. `
+            + (detail ? `${detail} ` : '')
+            + 'Close that process first, or open with createFeltDB({ path, access: \'shared\' }) if several '
+            + 'processes are meant to share this state.', FeltDBErrorCode.STATE_LOCKED);
+        this.lockPath = lockPath;
+        this.owner = owner;
+        this.name = 'LocalStateLockedError';
     }
 }
 /**
@@ -81,7 +117,10 @@ export function classifyError(code) {
         return 'retryable';
     if (code === FeltDBErrorCode.CONFLICT || code === FeltDBErrorCode.VERSION_CONFLICT
         || code === FeltDBErrorCode.IDEMPOTENCY_CONFLICT
-        || code === FeltDBErrorCode.COMMIT_OUTCOME_UNKNOWN)
+        || code === FeltDBErrorCode.COMMIT_OUTCOME_UNKNOWN
+        // A commit the authority could not make durable has an unknown outcome:
+        // reconcile by retrying with the same transaction id, never by assuming.
+        || code === FeltDBErrorCode.DURABILITY_FAILURE)
         return 'requires_reconciliation';
     if (code === FeltDBErrorCode.PRECONDITION_FAILED
         || code === FeltDBErrorCode.VALIDATION_ERROR

package/dist/feltdb.d.ts

@@ -67,6 +67,13 @@ export interface JsDb {
     delete?(key: string): any | Promise<any>;
     /** Subscribe to runtime-originated changes, including remote mutations. */
     subscribe_changes?(callback: (collection: string) => void, collection?: string): () => void;
+    /** Content-addressed immutable bytes (server and local file runtimes). */
+    storeContent?(content: Uint8Array): Promise<{
+        hash: string;
+        bytes: number;
+        ref: string;
+    }>;
+    acquireContent?(hash: string): Promise<Uint8Array | null>;
     close?(): void | Promise<void>;
     /**
      * Get capability records

package/dist/feltdb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feltdb.d.ts","sourceRoot":"","sources":["../src/feltdb.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"feltdb.d.ts","sourceRoot":"","sources":["../src/feltdb.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,GAAG,GAAG,GAAG,CAAC;IAEhC;;OAEG;IACH,SAAS,IAAI,GAAG,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC;IAE/B;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC;IAEpC;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC;IAEvC;;OAEG;IACH,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,GAAG,CAAC;IAEnE;;OAEG;IACH,2BAA2B,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC;IAEpE;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEzC,iEAAiE;IACjE,eAAe,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnD;;;;;OAKG;IACH,gCAAgC,CAAC,EAAE,OAAO,CAAC;IAE3C,oDAAoD;IACpD,aAAa,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE3D,mEAAmE;IACnE,eAAe,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAErC;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEvD,6DAA6D;IAC7D,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAExD,qDAAqD;IACrD,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEzC,2EAA2E;IAC3E,iBAAiB,CAAC,CAAC,QAAQ,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IAC5F,0EAA0E;IAC1E,YAAY,CAAC,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1F,cAAc,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAC1D,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/B;;OAEG;IACH,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC;IAEhD;;OAEG;IACH,WAAW,IAAI,MAAM,CAAC;IAEtB;;;;;;;;;OASG;IACH,YAAY,IAAI,MAAM,CAAC;IAEvB;;;;;;;OAOG;IACH,SAAS,CAAC,IAAI,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEjE;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE/B,0EAA0E;IAC1E,YAAY,CAAC,IAAI,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEpC,6DAA6D;IAC7D,iBAAiB,CAAC,CAAC,cAAc,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/D,uBAAuB,CAAC,CAAC,UAAU,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEhE;;;;;;OAMG;IACH,WAAW,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAExF;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IAErQ,8EAA8E;IAC9E,cAAc,CAAC,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAE1C,kFAAkF;IAClF,mBAAmB,CAAC,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAE/C;;;;;;OAMG;IACH;;;;OAIG;IACH,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,kBAAkB,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,kBAAkB,EAAE,oBAAoB,CAAC,CAAC;IAE5H,kBAAkB,CAAC,CAAC,OAAO,EAAE;QAC3B,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,KAAK,CAAC;YAChB,UAAU,EAAE,MAAM,CAAC;YACnB,EAAE,EAAE,MAAM,CAAC;YACX,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAChC,aAAa,CAAC,EAAE,OAAO,CAAC;YACxB;;;eAGG;YACH,eAAe,CAAC,EAAE,MAAM,CAAC;YACzB,aAAa,CAAC,EAAE,MAAM,CAAC;YACvB,eAAe,CAAC,EAAE,MAAM,CAAC;SAC1B,CAAC,CAAC;QACH,4DAA4D;QAC5D,aAAa,CAAC,EAAE,KAAK,CAAC;YACpB,UAAU,EAAE,MAAM,CAAC;YACnB,EAAE,EAAE,MAAM,CAAC;YACX,aAAa,CAAC,EAAE,OAAO,CAAC;YACxB,eAAe,CAAC,EAAE,MAAM,CAAC;YACzB,aAAa,CAAC,EAAE,MAAM,CAAC;YACvB,eAAe,CAAC,EAAE,MAAM,CAAC;SAC1B,CAAC,CAAC;QACH,+EAA+E;QAC/E,MAAM,CAAC,EAAE,OAAO,kBAAkB,EAAE,oBAAoB,EAAE,CAAC;KAC5D,GAAG,OAAO,CAAC,OAAO,kBAAkB,EAAE,uBAAuB,CAAC,CAAC;CACjE;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB"}

package/dist/file-db.d.ts

@@ -57,6 +57,15 @@ export interface FileJsDbOptions {
     };
     /** Collect persistence timings. Also enabled by `FELTDB_PERSISTENCE_PROFILE=1`. */
     profile?: boolean;
+    /**
+     * `shared` (the default for a directly constructed `FileJsDb`): any number
+     * of processes may open the directory; each commit is serialized by
+     * `state.lock`. `exclusive` (the default of `createFeltDB({ path })`): this
+     * process takes `owner.lock` at open and another process opening the same
+     * directory exclusively *or shared* is refused with `LocalStateLockedError`
+     * until `close()` or process exit. Handles in one process share the lock.
+     */
+    access?: 'shared' | 'exclusive';
 }
 export interface PersistenceStatus {
     format: 'none' | 'legacy-snapshot' | 'snapshot+journal';
@@ -91,7 +100,16 @@ export declare class FileJsDb implements JsDb {
     private readonly profiler;
     private readonly compaction;
     private compactionScheduled;
+    private releaseOwnerLock;
+    /** How this handle opened its directory. */
+    readonly access: 'shared' | 'exclusive';
     constructor(path: string, options?: FileJsDbOptions);
+    /**
+     * A shared open still respects an exclusive owner in another process: a
+     * process that asked for exclusive access must not find a second writer.
+     * Probing takes no lock of its own.
+     */
+    private assertNotHeldExclusively;
     private journalPath;
     private snapshotKey;
     private parseSnapshot;
@@ -283,6 +301,15 @@ export declare class FileJsDb implements JsDb {
         conflictCode?: string;
         item?: any;
     }>;
+    private contentDirectory;
+    private static sha256;
+    storeContent(content: Uint8Array): Promise<{
+        hash: string;
+        bytes: number;
+        ref: string;
+    }>;
+    acquireContent(hash: string): Promise<Uint8Array | null>;
+    private fsyncDirectory;
     close(): void;
 }
 //# sourceMappingURL=file-db.d.ts.map

package/dist/file-db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-db.d.ts","sourceRoot":"","sources":["../src/file-db.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file-db.d.ts","sourceRoot":"","sources":["../src/file-db.ts"],"names":[],"mappings":"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"}

package/dist/file-db.js

@@ -2,9 +2,11 @@ import { validateOperationAdmissionInput, operationsConflict, generateOperationI
 import { FeltDBErrorCode, FeltDBServiceError } from './error-codes.js';
 import * as nodeFs from 'fs';
 import * as nodePath from 'path';
+import { createHash as nodeCreateHash } from 'crypto';
 import { TransactionIdConflictError, TransactionIdUnverifiableError, normaliseReadSet } from './transaction.js';
 import { decideTransaction, readBasisToken, scanRows, embeddedDuplicate, embeddedResult, prepareTransaction, refusalError, } from './embedded-transaction.js';
 import { EmbeddedQueryEngine } from './embedded-query.js';
+import { LOCAL_STATE_LOCK_FILE, acquireLocalStateLock } from './local-state-lock.js';
 import { encodeRecord, scanJournal, JournalCorruptionError, PersistenceProfiler, } from './file-journal.js';
 export { JournalCorruptionError } from './file-journal.js';
 /** The newest local file snapshot format this build reads and writes. */
@@ -71,6 +73,9 @@ export class FileJsDb {
     profiler;
     compaction;
     compactionScheduled = false;
+    releaseOwnerLock = null;
+    /** How this handle opened its directory. */
+    access;
     constructor(path, options = {}) {
         const nodePath = getPathSync();
         const nodeFs = getFsSync();
@@ -96,13 +101,43 @@ export class FileJsDb {
         }
         // Generate stable instance ID based on path
         this.origin = `file:${this.dataPath}`;
-        // Clean up any stale locks from previous crashes on startup
-        this.cleanupStaleLock();
-        // Load or initialize state
-        this.state = this.initializeState();
-        this.loadDurableState();
-        this.queryEngine = new EmbeddedQueryEngine(() => Object.entries(this.state.rows));
-        this.indexedSequence = this.state.sequence;
+        this.access = options.access ?? 'shared';
+        if (this.access !== 'shared' && this.access !== 'exclusive') {
+            throw new Error(`access must be 'shared' or 'exclusive', not ${String(options.access)}`);
+        }
+        if (this.access === 'exclusive') {
+            this.releaseOwnerLock = acquireLocalStateLock(this.dataPath);
+        }
+        else {
+            this.assertNotHeldExclusively(nodePath.join(this.dataPath, LOCAL_STATE_LOCK_FILE));
+        }
+        try {
+            // Clean up any stale locks from previous crashes on startup
+            this.cleanupStaleLock();
+            // Load or initialize state
+            this.state = this.initializeState();
+            this.loadDurableState();
+            this.queryEngine = new EmbeddedQueryEngine(() => Object.entries(this.state.rows));
+            this.indexedSequence = this.state.sequence;
+        }
+        catch (error) {
+            this.releaseOwnerLock?.();
+            this.releaseOwnerLock = null;
+            throw error;
+        }
+    }
+    /**
+     * A shared open still respects an exclusive owner in another process: a
+     * process that asked for exclusive access must not find a second writer.
+     * Probing takes no lock of its own.
+     */
+    assertNotHeldExclusively(lockPath) {
+        const nodeFs = getFsSync();
+        if (!nodeFs.existsSync(lockPath))
+            return;
+        // acquire-then-release judges liveness and recovers a stale lock exactly
+        // as an exclusive open would; it refuses when a live process holds it.
+        acquireLocalStateLock(this.dataPath)();
     }
     /* ------------------------------------------------------------------------
      * Durable layout
@@ -1442,8 +1477,111 @@ export class FileJsDb {
                 console.log(`[CAS-${casId}] lock released, EXIT`);
         }
     }
+    /* ------------------------------------------------------------------------
+     * Content store
+     *
+     * Immutable bytes addressed by SHA-256, under `<state dir>/content/<hash>`:
+     * the same contract as the server's `PUT /content` / `GET /content/{hash}`.
+     * A blob is written to a temporary file, fsynced, renamed into place, and
+     * the directory fsynced, so it is durable before `storeContent` returns and
+     * never visible half-written. Every read is re-hashed; bytes that no longer
+     * match their address are refused, never returned. Content is not indexed
+     * state and is never deleted by FeltDB.
+     * ---------------------------------------------------------------------- */
+    contentDirectory() {
+        return getPathSync().join(this.dataPath, 'content');
+    }
+    static sha256(bytes) {
+        return nodeCreateHash('sha256').update(bytes).digest('hex');
+    }
+    async storeContent(content) {
+        if (!(content instanceof Uint8Array)) {
+            throw new FeltDBServiceError('INVALID_REQUEST: content must be a Uint8Array', FeltDBErrorCode.INVALID_REQUEST);
+        }
+        if (content.byteLength === 0) {
+            throw new FeltDBServiceError('INVALID_REQUEST: content body must not be empty', FeltDBErrorCode.INVALID_REQUEST);
+        }
+        const nodeFs = getFsSync();
+        const nodePath = getPathSync();
+        const bytes = Buffer.from(content.buffer, content.byteOffset, content.byteLength);
+        const hash = FileJsDb.sha256(bytes);
+        const directory = this.contentDirectory();
+        const target = nodePath.join(directory, hash);
+        if (!nodeFs.existsSync(directory)) {
+            nodeFs.mkdirSync(directory, { recursive: true });
+            this.fsyncDirectory(this.dataPath);
+        }
+        try {
+            const existing = nodeFs.readFileSync(target);
+            if (FileJsDb.sha256(existing) === hash)
+                return { hash, bytes: bytes.length, ref: `sha256:${hash}` };
+            // A damaged copy is replaced by the verified bytes now in hand.
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+        }
+        const temporary = nodePath.join(directory, `.${hash}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`);
+        const fd = nodeFs.openSync(temporary, 'wx', 0o600);
+        try {
+            writeFully(fd, bytes, 0);
+            nodeFs.fsyncSync(fd);
+        }
+        finally {
+            nodeFs.closeSync(fd);
+        }
+        try {
+            nodeFs.renameSync(temporary, target);
+        }
+        catch (error) {
+            try {
+                nodeFs.unlinkSync(temporary);
+            }
+            catch { /* best effort */ }
+            throw error;
+        }
+        this.fsyncDirectory(directory);
+        return { hash, bytes: bytes.length, ref: `sha256:${hash}` };
+    }
+    async acquireContent(hash) {
+        // The bare lowercase hex digest, exactly as the server's GET /content/{hash} takes it.
+        const address = hash;
+        if (typeof address !== 'string' || !/^[0-9a-f]{64}$/.test(address)) {
+            throw new FeltDBServiceError('INVALID_REQUEST: invalid sha256 content hash', FeltDBErrorCode.INVALID_REQUEST);
+        }
+        let bytes;
+        try {
+            bytes = getFsSync().readFileSync(getPathSync().join(this.contentDirectory(), address));
+        }
+        catch (error) {
+            if (isMissing(error))
+                return null;
+            throw error;
+        }
+        if (FileJsDb.sha256(bytes) !== address) {
+            throw new FeltDBServiceError(`CONTENT_INTEGRITY_FAILURE: stored content ${address} failed verification; it was not returned`, FeltDBErrorCode.CONTENT_INTEGRITY_FAILURE);
+        }
+        return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    }
+    fsyncDirectory(directory) {
+        const nodeFs = getFsSync();
+        let fd;
+        try {
+            fd = nodeFs.openSync(directory, 'r');
+            nodeFs.fsyncSync(fd);
+        }
+        catch {
+            // Some platforms cannot fsync a directory; the rename is still atomic.
+        }
+        finally {
+            if (fd !== undefined)
+                nodeFs.closeSync(fd);
+        }
+    }
     close() {
         // Mutations are durable before they return. Closing a stale handle must
         // never rewrite authority state produced by another process.
+        this.releaseOwnerLock?.();
+        this.releaseOwnerLock = null;
     }
 }