@feltdb/core 0.12.2 → 0.15.0

package/dist/http-db.js

@@ -1,6 +1,111 @@
 import { FeltDBErrorCode, FeltDBServiceError } from './error-codes.js';
+import { assertBrowserSafeCredential } from './deployment.js';
 import { conditionalRefusal } from './transaction.js';
 import { BoundedBackoff, SingleFlightValue, cancellableDelay, describeFailure, } from './managed-recovery.js';
+/** The origin of a URL, without any userinfo, for messages. */
+function displayOrigin(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return url.replace(/\/\/[^@/]*@/, '//');
+    }
+}
+const AUTHENTICATION_CODES = new Set(['AUTHENTICATION_REQUIRED', 'AUTHENTICATION_FAILED', 'UNAUTHORIZED', 'UNAUTHENTICATED']);
+const LOAD_CODES = new Set(['SERVICE_OVERLOADED', 'TOO_BUSY', 'RATE_LIMITED', 'TOO_MANY_REQUESTS', 'QUERY_LIMIT_EXCEEDED']);
+/**
+ * What to do next about a refusal the authority answered, or undefined when
+ * the authority's own message already says it. The code is never changed;
+ * this only adds the remedy a developer would otherwise have to look up.
+ */
+function refusalRemedy(code, status, message, context) {
+    const application = context.applicationId ? `application "${context.applicationId}"` : 'this authority';
+    const environment = context.environment ?? 'production';
+    if (code === 'AUTHORITY_SCOPE_MISMATCH') {
+        return `The tenant named in createFeltDB({ authorityScope }) does not own ${application}; use the tenant the application belongs to, or omit authorityScope.`;
+    }
+    if (status === 401 || AUTHENTICATION_CODES.has(code)) {
+        return context.hasToken
+            ? `${context.origin} did not accept the credential. Check FELTDB_TOKEN: it must be an unexpired, unrevoked data key${context.applicationId ? ` issued for ${application}` : ''}. Keep it server-side only.`
+            : 'No credential was sent. Set FELTDB_TOKEN in the server process (never in browser code), or pass createFeltDB({ server: { token } }).';
+    }
+    if (code === 'UNKNOWN_COLLECTION') {
+        const collection = context.collection ?? (/^[A-Za-z_][\w.-]*$/.test(message) ? message : undefined);
+        return `Collection ${collection ? `"${collection}" ` : ''}is not declared in the contract promoted to environment "${environment}" for ${application}. Add it to the contract and publish and promote a new revision.`;
+    }
+    if (status === 403 || code === 'FORBIDDEN') {
+        // Discovery checks application:read; a canonical read or write also
+        // resolves the promoted revision (application:revision:read).
+        const scope = context.operation === 'write' ? 'the application:revision:read and state:write scopes'
+            : context.operation === 'discover' ? 'the application:read scope'
+                : context.operation === 'read' ? 'the application:revision:read and state:read scopes'
+                    : 'the scopes this operation needs (state:read to read, state:write to write)';
+        return `The credential was accepted but is not authorized for ${application}${context.applicationId ? ` in environment "${environment}"` : ''}. Use a data key minted for this application with ${scope}`
+            + (context.operation === 'write' && context.collection
+                ? `; a write to a collection the promoted contract does not declare ("${context.collection}" may be one) is refused the same way.`
+                : '.');
+    }
+    if (status === 404 && context.applicationId) {
+        if (/no active contract/i.test(message)) {
+            return `No contract revision is promoted to environment "${environment}" for ${application}. Publish and promote one (feltdb publish --environment ${environment}), or set FELTDB_ENVIRONMENT to an environment that has one.`;
+        }
+        if (/application not found/i.test(message)) {
+            return `Check FELTDB_APPLICATION_ID: ${context.origin} has no ${application} visible to this credential.`;
+        }
+        if (/revision not found/i.test(message)) {
+            return `The revision promoted for ${application} is not readable; promote the revision again.`;
+        }
+    }
+    if ((code === 'VALIDATION_FAILED' || code === 'VALIDATION_ERROR') && /unknown field/i.test(message)) {
+        return `Declare the field on ${context.collection ? `collection "${context.collection}"` : 'the collection'} in the contract and promote it, or stop writing it.`;
+    }
+    if (code === FeltDBErrorCode.DURABILITY_FAILURE) {
+        return 'Whether the commit is durable is unknown: retry with the same transactionId, and never treat this as a refusal.';
+    }
+    if (status === 429 || LOAD_CODES.has(code) || (status === 503 && code === FeltDBErrorCode.SERVICE_UNAVAILABLE)) {
+        return context.operation === 'write'
+            ? 'The authority is shedding load: back off (honour Retry-After) and retry with the same transactionId.'
+            : 'The authority is shedding load: back off (honour Retry-After) and retry the read.';
+    }
+    return undefined;
+}
+/** The authority's message plus its code, status, request id and remedy. */
+function refusalMessage(message, code, status, requestId, context) {
+    if (!context)
+        return message;
+    const remedy = refusalRemedy(code, status, message, context);
+    const where = [status ? `HTTP ${status}` : undefined, code, requestId ? `request ${requestId}` : undefined].filter(Boolean).join(', ');
+    return `${message} (${where})${remedy ? `. ${remedy}` : ''}`;
+}
+/**
+ * The typed failure for a request that ended without an answer. A read is
+ * `SERVICE_UNAVAILABLE`; a mutation may have reached the authority and
+ * committed, so it is `COMMIT_OUTCOME_UNKNOWN`, never a refusal.
+ */
+function transportFailure(error, mutating, context) {
+    if (error instanceof FeltDBServiceError)
+        return error;
+    const raw = error instanceof Error ? error.message : String(error);
+    const cause = error?.cause;
+    const name = error?.name;
+    const timedOut = name === 'TimeoutError' || name === 'AbortError';
+    // Only a request that ended without an answer gets the connection advice;
+    // any other local error (a malformed key, say) keeps its own message.
+    const transport = timedOut || error instanceof TypeError || typeof cause?.code === 'string';
+    const detail = typeof cause?.code === 'string' ? cause.code : typeof cause?.message === 'string' ? cause.message : raw;
+    const message = !context || !transport ? raw
+        : `${timedOut ? `No answer from FeltDB at ${context.origin} within ${context.timeoutMs} ms` : `Could not reach FeltDB at ${context.origin} (${detail})`}. `
+            + (mutating
+                ? 'The write may have been applied: retry only with the same transactionId, never a new one. '
+                : 'Nothing was changed. ')
+            + `Check FELTDB_URL and the service: GET ${context.origin}/health answers while the process is up, ${context.origin}/ready only when it can serve.`;
+    return new FeltDBServiceError(message, mutating ? FeltDBErrorCode.COMMIT_OUTCOME_UNKNOWN : FeltDBErrorCode.SERVICE_UNAVAILABLE);
+}
+/** A failed `JsResult` that keeps the typed failure. */
+function failed(error, mutating, context) {
+    const cause = transportFailure(error, mutating, context);
+    return { success: false, error: cause.message, cause };
+}
 /**
  * A durable identity for one conditional write attempt.
  *
@@ -29,6 +134,19 @@ function managedCollectionRecord(value) {
     delete record._version;
     return record;
 }
+/** The collection a canonical request body addresses, for failure messages. */
+function requestCollection(body) {
+    if (typeof body !== 'string')
+        return undefined;
+    try {
+        const value = JSON.parse(body);
+        const collection = value.query?.collection ?? value.transaction?.operations?.[0]?.collection;
+        return typeof collection === 'string' ? collection : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Network adapter implementing the same collection runtime contract as WASM. */
 export class HttpJsDb {
     collection_queries_via_authority = true;
@@ -56,7 +174,12 @@ export class HttpJsDb {
     nextRetryAt;
     streamFailures = 0;
     authorityFailures = 0;
+    /** One entry per subscription, so the same callback subscribed twice is two subscriptions. */
+    changeListeners = new Set();
+    changeStream;
     constructor(options) {
+        if (!options.allowServiceKeyInBrowser)
+            assertBrowserSafeCredential(options.token, typeof window !== 'undefined' && typeof document !== 'undefined', 'the HTTP runtime token');
         this.url = options.url.replace(/\/$/, '');
         this.token = options.token || '';
         this.applicationId = options.applicationId;
@@ -124,6 +247,14 @@ export class HttpJsDb {
             ...(json ? { 'Content-Type': 'application/json' } : {}),
         };
     }
+    /** Where this client's requests go, for actionable failure messages. */
+    context(operation, collection) {
+        return {
+            origin: displayOrigin(this.url), timeoutMs: this.requestTimeoutMs, hasToken: !!this.token,
+            ...(this.applicationId ? { applicationId: this.applicationId, environment: this.environment } : {}),
+            ...(operation ? { operation } : {}), ...(collection ? { collection } : {}),
+        };
+    }
     updateToken(token) {
         this.token = token;
         // Credentials changed, so a permanent authorization failure may no longer
@@ -199,11 +330,16 @@ export class HttpJsDb {
     revisionState() {
         return this.revisionCache.state;
     }
+    /**
+     * A canonical *read* (`/query`, `/transactions/read-basis`). It is a POST
+     * only because its request has a body; an interrupted read changed nothing,
+     * so it is `SERVICE_UNAVAILABLE`, never `COMMIT_OUTCOME_UNKNOWN`.
+     */
     async canonical(path, payload) {
         const revisionId = await this.revisionId();
         return this.application_request(path, { method: 'POST', body: JSON.stringify({
                 application_id: this.applicationId, revision_id: revisionId, environment: this.environment, ...payload,
-            }) });
+            }) }, { read: true });
     }
     transactionDocument(revisionId, operations, transactionId = crypto.randomUUID(), preconditions = [], fences = []) {
         const tenantId = this.authorityScope?.kind === 'tenant' ? this.authorityScope.tenantId : '';
@@ -226,6 +362,7 @@ export class HttpJsDb {
             }
             const response = await fetch(`${this.url}/collections/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`, {
                 headers: this.headers(),
+                signal: AbortSignal.timeout(this.requestTimeoutMs),
             });
             if (response.status === 404)
                 return { success: true };
@@ -235,7 +372,7 @@ export class HttpJsDb {
             return { success: true, data: JSON.stringify(record.value) };
         }
         catch (error) {
-            return { success: false, error: String(error) };
+            return failed(error, false, this.context('read'));
         }
     }
     async query(collection) {
@@ -254,6 +391,7 @@ export class HttpJsDb {
             }
             const response = await fetch(`${this.url}/collections/${encodeURIComponent(collection)}`, {
                 headers: this.headers(),
+                signal: AbortSignal.timeout(this.requestTimeoutMs),
             });
             if (!response.ok)
                 return this.failure(response);
@@ -261,7 +399,7 @@ export class HttpJsDb {
             return { success: true, data: JSON.stringify(records.map(record => record.value)) };
         }
         catch (error) {
-            return { success: false, error: String(error) };
+            return failed(error, false, this.context('read'));
         }
     }
     async authority_query(query) {
@@ -286,17 +424,21 @@ export class HttpJsDb {
                 } });
             return { records: result.records.map(managedCollectionRecord), nextCursor: result.next_cursor, exhausted: !result.next_cursor, plan: result.plan };
         }
-        const response = await fetch(`${this.url}/query`, {
-            method: 'POST', headers: this.headers(true), body: JSON.stringify(query),
-        });
-        const body = await response.json();
-        if (!response.ok) {
-            const error = new Error(body.message || body.error || `authority query failed with HTTP ${response.status}`);
-            error.code = body.code;
-            error.status = response.status;
-            throw error;
+        let response;
+        try {
+            response = await fetch(`${this.url}/query`, {
+                method: 'POST', headers: this.headers(true), body: JSON.stringify(query),
+                signal: AbortSignal.timeout(this.requestTimeoutMs),
+            });
         }
-        return body;
+        catch (error) {
+            // A bounded query is a read: an interruption is SERVICE_UNAVAILABLE.
+            this.recordFailure(error);
+            throw transportFailure(error, false, this.context('read', query.collection));
+        }
+        if (!response.ok)
+            throw await this.refusal(response);
+        return await response.json();
     }
     async insert(key, value) {
         try {
@@ -310,13 +452,14 @@ export class HttpJsDb {
                 method: 'POST',
                 headers: this.headers(true),
                 body: JSON.stringify({ ...record, id }),
+                signal: AbortSignal.timeout(this.requestTimeoutMs),
             });
             if (!response.ok)
                 return this.failure(response);
             return { success: true, data: key };
         }
         catch (error) {
-            return { success: false, error: String(error) };
+            return failed(error, true, this.context('write'));
         }
     }
     async update(key, value) {
@@ -330,13 +473,14 @@ export class HttpJsDb {
                 method: 'PATCH',
                 headers: this.headers(true),
                 body: value,
+                signal: AbortSignal.timeout(this.requestTimeoutMs),
             });
             if (!response.ok)
                 return this.failure(response);
             return { success: true, data: key };
         }
         catch (error) {
-            return { success: false, error: String(error) };
+            return failed(error, true, this.context('write'));
         }
     }
     /**
@@ -392,7 +536,7 @@ export class HttpJsDb {
         }
         catch (error) {
             this.recordFailure(error);
-            throw new FeltDBServiceError(error instanceof Error ? error.message : String(error), FeltDBErrorCode.COMMIT_OUTCOME_UNKNOWN);
+            throw transportFailure(error, true, this.context('write', request.operations[0]?.collection));
         }
         if (!response.ok) {
             // The authority answers a refused transaction with a structured
@@ -404,12 +548,13 @@ export class HttpJsDb {
                 body = await response.json();
             }
             catch { /* not JSON */ }
-            const error = new Error(body.error || `transaction failed with HTTP ${response.status}`);
-            error.status = response.status;
-            if (body.code)
-                error.feltdbCode = body.code;
+            const code = body.code
+                ?? (response.status >= 500 ? FeltDBErrorCode.SERVICE_UNAVAILABLE : FeltDBErrorCode.INVALID_REQUEST);
+            const error = new FeltDBServiceError(refusalMessage((code === body.error ? body.message : body.error) || body.message || `transaction failed with HTTP ${response.status}`, code, response.status, body.request_id, this.context('write', request.operations[0]?.collection)), code, body.request_id, response.status);
+            error.feltdbCode = code;
             if (body.failure)
                 error.feltdbConflict = body.failure;
+            this.recordFailure(error);
             throw error;
         }
         const body = await response.json();
@@ -563,17 +708,28 @@ export class HttpJsDb {
         try {
             const [collection, id] = this.splitKey(params.key);
             const parsed = JSON.parse(params.value);
-            const response = await fetch(`${this.url}/collections/${encodeURIComponent(collection)}/${encodeURIComponent(id)}/cas`, {
-                method: 'POST',
-                headers: this.headers(true),
-                body: JSON.stringify({
-                    expectedVersion: params.expectedVersion,
-                    expectedEpoch: params.expectedEpoch,
-                    expectedLeaseId: params.expectedLeaseId,
-                    rejectIfDiverged: params.rejectIfDiverged,
-                    value: parsed,
-                }),
-            });
+            let response;
+            try {
+                response = await fetch(`${this.url}/collections/${encodeURIComponent(collection)}/${encodeURIComponent(id)}/cas`, {
+                    method: 'POST',
+                    headers: this.headers(true),
+                    body: JSON.stringify({
+                        expectedVersion: params.expectedVersion,
+                        expectedEpoch: params.expectedEpoch,
+                        expectedLeaseId: params.expectedLeaseId,
+                        rejectIfDiverged: params.rejectIfDiverged,
+                        value: parsed,
+                    }),
+                    signal: AbortSignal.timeout(this.requestTimeoutMs),
+                });
+            }
+            catch (error) {
+                // The request may have reached the authority and committed. A CAS
+                // carries no identity to retry by, so the caller reconciles by
+                // re-reading: a retried CAS is refused by the version it advanced.
+                this.recordFailure(error);
+                throw new FeltDBServiceError(error instanceof Error ? error.message : String(error), FeltDBErrorCode.COMMIT_OUTCOME_UNKNOWN);
+            }
             // Handle conflict response (structured error)
             if (response.status === 409) {
                 const body = await response.json();
@@ -587,10 +743,14 @@ export class HttpJsDb {
                     };
                 }
             }
-            // Other errors
+            // Other errors, typed by the authority's code.
             if (!response.ok) {
-                const failure = await this.failure(response);
-                throw new Error(failure.error || 'HTTP CAS failed');
+                let body = {};
+                try {
+                    body = await response.json();
+                }
+                catch { /* not JSON */ }
+                throw new FeltDBServiceError(body.message || body.error || `HTTP CAS failed with ${response.status}`, body.code || (response.status >= 500 ? FeltDBErrorCode.SERVICE_UNAVAILABLE : FeltDBErrorCode.INVALID_REQUEST), body.request_id, response.status);
             }
             // Success response
             const result = await response.json();
@@ -610,11 +770,12 @@ export class HttpJsDb {
             const response = await fetch(`${this.url}/collections/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`, {
                 method: 'DELETE',
                 headers: this.headers(),
+                signal: AbortSignal.timeout(this.requestTimeoutMs),
             });
             return response.ok ? { success: true, data: key } : this.failure(response);
         }
         catch (error) {
-            return { success: false, error: String(error) };
+            return failed(error, true, this.context('write'));
         }
     }
     /** Acquire a reference through the server's causal peer fabric. */
@@ -623,7 +784,7 @@ export class HttpJsDb {
         if (response.status === 404)
             return null;
         if (!response.ok)
-            throw new Error((await this.failure(response)).error);
+            throw await this.refusal(response);
         return (await response.json()).value;
     }
     /** Execute the built-in state-derived search capability remotely. */
@@ -632,19 +793,19 @@ export class HttpJsDb {
             method: 'POST', headers: this.headers(true), body: JSON.stringify({ query, limit }),
         });
         if (!response.ok)
-            throw new Error((await this.failure(response)).error);
+            throw await this.refusal(response);
         return (await response.json()).map(record => record.value);
     }
     async provenance(collection, id) {
         const response = await fetch(`${this.url}/provenance/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`, { headers: this.headers() });
         if (!response.ok)
-            throw new Error((await this.failure(response)).error);
+            throw await this.refusal(response);
         return (await response.json()).value;
     }
     async storeContent(content) {
         const response = await fetch(`${this.url}/content`, { method: 'PUT', headers: this.headers(), body: content });
         if (!response.ok)
-            throw new Error((await this.failure(response)).error);
+            throw await this.refusal(response);
         return response.json();
     }
     async acquireContent(hash) {
@@ -652,7 +813,7 @@ export class HttpJsDb {
         if (response.status === 404)
             return null;
         if (!response.ok)
-            throw new Error((await this.failure(response)).error);
+            throw await this.refusal(response);
         return new Uint8Array(await response.arrayBuffer());
     }
     async command(path, body) {
@@ -660,19 +821,28 @@ export class HttpJsDb {
             method: 'POST', headers: this.headers(true), body: JSON.stringify(body),
         });
         if (!response.ok)
-            throw new Error((await this.failure(response)).error);
+            throw await this.refusal(response);
         return response.status === 204 ? undefined : response.json();
     }
-    async application_request(path, init = {}) {
+    /**
+     * One request to the canonical application service. A request without a
+     * body-carrying method is a read; a POST is treated as a mutation unless the
+     * caller declares it a read (`{ read: true }`), because only a mutation can
+     * leave an uncertain commit behind.
+     */
+    async application_request(path, init = {}, options = {}) {
         const separator = path.includes('?') ? '&' : '?';
-        const context = this.applicationId
+        const query = this.applicationId
             ? `${separator}application_id=${encodeURIComponent(this.applicationId)}&environment=${encodeURIComponent(this.environment)}`
             : '';
         if (this.availabilityState === 'degraded')
             this.availabilityState = 'recovering';
+        const mutating = !options.read && !['GET', 'HEAD', 'OPTIONS'].includes((init.method ?? 'GET').toUpperCase());
+        // Built only on failure: parsing the request body is not free.
+        const context = () => this.context(path.startsWith('/application') ? 'discover' : mutating ? 'write' : 'read', requestCollection(init.body));
         let response;
         try {
-            response = await fetch(`${this.url}/v1${path}${context}`, {
+            response = await fetch(`${this.url}/v1${path}${query}`, {
                 ...init,
                 signal: init.signal ?? AbortSignal.timeout(this.requestTimeoutMs),
                 headers: { ...this.headers(init.body !== undefined), ...(init.headers || {}) },
@@ -680,10 +850,17 @@ export class HttpJsDb {
         }
         catch (error) {
             this.recordFailure(error);
-            const mutating = !['GET', 'HEAD', 'OPTIONS'].includes((init.method ?? 'GET').toUpperCase());
-            throw new FeltDBServiceError(error instanceof Error ? error.message : String(error), mutating ? FeltDBErrorCode.COMMIT_OUTCOME_UNKNOWN : FeltDBErrorCode.SERVICE_UNAVAILABLE);
+            throw transportFailure(error, mutating, context());
+        }
+        let text;
+        try {
+            text = await response.text();
+        }
+        catch (error) {
+            // The answer started and was cut off: for a mutation, still unknown.
+            this.recordFailure(error);
+            throw transportFailure(error, mutating, context());
         }
-        const text = await response.text();
         let body;
         try {
             body = text ? JSON.parse(text) : undefined;
@@ -692,7 +869,8 @@ export class HttpJsDb {
             body = { message: text };
         }
         if (!response.ok) {
-            const error = new FeltDBServiceError(body?.message || body?.error || `FeltDB service request failed: HTTP ${response.status}`, body?.code || body?.error || 'REQUEST_FAILED', body?.request_id, response.status);
+            const code = body?.code || body?.error || 'REQUEST_FAILED';
+            const error = new FeltDBServiceError(refusalMessage(body?.message || body?.error || `FeltDB service request failed: HTTP ${response.status}`, code, response.status, body?.request_id, context()), code, body?.request_id, response.status, body && typeof body === 'object' && !Array.isArray(body) ? body : undefined);
             // The same structured refusal the direct route carries, so a lost race
             // is typed the same way on every route.
             if (body?.failure)
@@ -730,7 +908,7 @@ export class HttpJsDb {
             const error = new FeltDBServiceError(body?.message || body?.error || `FeltDB request failed: HTTP ${response.status}`, body?.code || (response.status === 401 ? FeltDBErrorCode.UNAUTHORIZED
                 : response.status === 403 ? FeltDBErrorCode.FORBIDDEN
                     : response.status === 404 ? FeltDBErrorCode.NOT_FOUND
-                        : 'INVALID_REQUEST'), body?.request_id, response.status);
+                        : 'INVALID_REQUEST'), body?.request_id, response.status, body && typeof body === 'object' && !Array.isArray(body) ? body : undefined);
             this.recordFailure(error);
             throw error;
         }
@@ -749,14 +927,40 @@ export class HttpJsDb {
      * a timer that wakes up after the caller has unsubscribed and opens a new
      * connection to an authority nobody is listening to.
      */
+    /**
+     * One event stream per client, shared by every subscriber.
+     *
+     * A browser holds at most six HTTP/1.1 connections to one host, and an event
+     * stream holds its connection for as long as it is open. A stream per live
+     * collection therefore lets an application with six live collections occupy
+     * every connection to its authority, after which each other request — the
+     * next write included — waits forever. Subscribers are fanned out here
+     * instead, and the stream closes with the last of them.
+     */
     subscribe_changes(callback) {
-        const controller = new AbortController();
-        this.connectionState = 'connecting';
-        void this.consumeEvents(controller, callback);
+        const subscription = { callback };
+        this.changeListeners.add(subscription);
+        if (!this.changeStream) {
+            const controller = new AbortController();
+            this.changeStream = controller;
+            this.connectionState = 'connecting';
+            void this.consumeEvents(controller, collection => {
+                for (const listener of [...this.changeListeners]) {
+                    // One subscriber's failure is its own; the others still hear the change.
+                    try {
+                        listener.callback(collection);
+                    }
+                    catch { /* reported by the subscriber */ }
+                }
+            });
+        }
         return () => {
+            if (!this.changeListeners.delete(subscription) || this.changeListeners.size > 0 || !this.changeStream)
+                return;
             // `abort()` reaches both: the in-flight fetch through its signal, and
             // the pending backoff through the listener `cancellableDelay` installs.
-            controller.abort();
+            this.changeStream.abort();
+            this.changeStream = undefined;
             this.connectionState = 'closed';
             this.nextRetryAt = undefined;
         };
@@ -848,15 +1052,38 @@ export class HttpJsDb {
         this.connectionState = 'closed';
         this.nextRetryAt = undefined;
     }
+    /** A refused response as a failed `JsResult` carrying the typed refusal. */
     async failure(response) {
-        let detail = `HTTP ${response.status}`;
+        const cause = await this.refusal(response);
+        return { success: false, error: cause.message, cause };
+    }
+    /**
+     * The authority's refusal, typed: its stable `code` (or one derived from the
+     * status when the body carries none), status, request id and body.
+     */
+    async refusal(response) {
+        let body;
         try {
-            const body = await response.json();
-            if (body.error)
-                detail = body.error;
+            const parsed = await response.json();
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                body = parsed;
         }
         catch { /* response was not JSON */ }
-        return { success: false, error: detail };
+        const text = (name) => (typeof body?.[name] === 'string' ? body[name] : undefined);
+        // An `error` field is a code only when it is spelled like one; older
+        // answers put prose there.
+        const errorField = text('error');
+        const errorCode = errorField && /^[A-Z][A-Z0-9_]+$/.test(errorField) ? errorField : undefined;
+        const code = text('code') ?? errorCode ?? (response.status === 401 ? FeltDBErrorCode.AUTHENTICATION_REQUIRED
+            : response.status === 403 ? FeltDBErrorCode.FORBIDDEN
+                : response.status === 404 ? FeltDBErrorCode.NOT_FOUND
+                    : response.status === 409 ? FeltDBErrorCode.CONFLICT
+                        : response.status >= 500 ? FeltDBErrorCode.SERVICE_UNAVAILABLE
+                            : FeltDBErrorCode.INVALID_REQUEST);
+        const message = refusalMessage(text('message') ?? (errorField !== code ? errorField : undefined) ?? `HTTP ${response.status}`, code, response.status, text('request_id'), this.context());
+        const error = new FeltDBServiceError(message, code, text('request_id'), response.status, body);
+        this.recordFailure(error);
+        return error;
     }
     get_capability_records(capability) { return this.query(capability); }
     execute_op() { return { success: false, error: 'Raw operation execution is internal to the server fabric' }; }

package/dist/index.js

@@ -15,7 +15,7 @@ import { registerDeploymentConfigLoader } from './deployment.js';
 import { FileJsDb } from './file-db.js';
 import * as nodeFs from 'fs';
 import * as nodePath from 'path';
-registerRuntime('file', path => new FileJsDb(path));
+registerRuntime('file', (path, options) => new FileJsDb(path, options?.access ? { access: options.access } : {}));
 registerDeploymentConfigLoader(() => {
     const configPath = nodePath.join(process.cwd(), 'feltdb.config.json');
     if (!nodeFs.existsSync(configPath))

package/dist/local-state-lock.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Exclusive ownership of a local state directory.
+ *
+ * The local file runtime is safe for several processes at the level of a
+ * single commit (each mutation takes `state.lock`). An application usually
+ * wants more: that no *other* process opens its state at all, because two
+ * application processes over one directory each believe they are the only
+ * writer of their caches, schedules, and in-process subscriptions.
+ *
+ * `acquire` creates `owner.lock` in the directory with `O_EXCL` and records
+ * the holder (`pid`, `host`, a random token). A second process finds it and is
+ * refused with `LocalStateLockedError`. Handles in the same process share the
+ * lock and the last `release` removes it; process exit removes it too.
+ *
+ * A lock whose holder is gone is recoverable: when the recorded host is this
+ * host and `process.kill(pid, 0)` reports no such process, the lock is taken
+ * over. The takeover renames the old lock aside and checks it is the one that
+ * was judged stale before deleting it, so two processes recovering the same
+ * stale lock cannot both win. A lock recorded by another host, or one that
+ * cannot be read, is never judged stale (it is refused, and the error names
+ * the file to remove by hand). A lock records its directory's real path, so a
+ * lock copied with the directory (a backup, an upgrade's verification copy)
+ * does not hold the copy.
+ *
+ * This is not authority state: it holds no data, and removing it never
+ * changes what the store contains.
+ */
+export declare const LOCAL_STATE_LOCK_FILE = "owner.lock";
+/**
+ * Take exclusive ownership of `directory` for this process.
+ * Throws `LocalStateLockedError` when another live process holds it.
+ */
+export declare function acquireLocalStateLock(directory: string): () => void;
+//# sourceMappingURL=local-state-lock.d.ts.map

package/dist/local-state-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-state-lock.d.ts","sourceRoot":"","sources":["../src/local-state-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAOH,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAiHlD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,IAAI,CAoDnE"}