@forgezero/providers 0.1.5 → 0.1.7

package/dist/binance.js

@@ -144,7 +144,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.5";
+var VERSION = "0.1.6";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {

package/dist/chain.js

@@ -144,7 +144,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.5";
+var VERSION = "0.1.6";
 
 // src/chain.ts
 var hexToNumber = (value) => Number(BigInt(value));

package/dist/database.d.ts

@@ -43,11 +43,10 @@ export interface ArangoConfig {
     url?: string;
     /** Explicit authenticated private coordinators. Bounded to prevent config abuse. */
     urls?: readonly string[];
-    /**
-     * Optional bootstrap Coordinators already proven to be in Arango `readonly`
-     * server mode. Prefer signed, probed membership for production.
-     */
-    readOnlyUrls?: readonly string[];
+    /** Optional subset of `urls` preferred only by explicitly safe reads. */
+    readPreferredUrls?: readonly string[];
+    /** Whether a preferred read may fall back to the balanced writable pool. */
+    readPreferredFallback?: 'balanced' | 'error';
     /**
      * Dynamic membership is accepted only as a signed/attested envelope verified
      * by the host. A Worker/KV node list by itself is discovery data, not routing
@@ -65,8 +64,6 @@ export interface ArangoConfig {
     maxCoordinatorAttempts?: number;
     /** Local transport-failure quarantine. Primarily injectable for tests. */
     unhealthyForMs?: number;
-    /** What an explicit read-only preference does when no read-only coordinator can serve it. */
-    readOnlyFallback?: 'authoritative' | 'error';
     now?: () => number;
 }
 export interface Query {
@@ -77,29 +74,24 @@ export interface Query {
      * caller assertions; this adapter never guesses AQL semantics from text.
      */
     retrySafety?: 'read' | 'idempotent' | 'never';
-    /**
-     * `prefer-readonly` targets Coordinators whose actual Arango server mode is
-     * `readonly`. It is valid only with `retrySafety: 'read'`; ForgeZero does not
-     * infer AQL semantics. Community 3.11.14 dirty follower reads are not exposed:
-     * that server feature is Enterprise-only.
-     */
-    readPreference?: 'authoritative' | 'prefer-readonly';
+    /** Routing hint valid only with `retrySafety: read`; it never changes write routing. */
+    readPreference?: 'balanced' | 'prefer-designated';
     /** Required when `retrySafety` is `idempotent`; retained for audit correlation. */
     idempotencyKey?: string;
 }
 export interface ArangoCoordinatorMember {
     url: string;
-    /** ArangoDB has no read-only DBServer/client role. Clients address Coordinators. */
+    /** Clients address Coordinators; Community 3.11.14 has no read-only joiner role. */
     role: 'coordinator';
     /** Actual `/_admin/server/mode` state for this Coordinator. */
-    serverMode: 'default' | 'readonly';
-    /** ForgeZero request-routing capability, required to agree with `serverMode`. */
-    access: 'read-write' | 'read-only';
+    serverMode: 'default';
     capabilities: {
         /** Always false for the exact Community 3.11.14 contract. */
         dirtyFollowerReads: false;
     };
     status: 'healthy' | 'degraded' | 'unhealthy';
+    /** Signed operator preference for safe reads; this is not an ArangoDB role. */
+    readPreferred?: boolean;
     /** Milliseconds since epoch, covered by the membership signature/attestation. */
     observedAt: number;
     /** Enrolled hybrid identity. The node key is its Ed25519 public half. */
@@ -122,7 +114,7 @@ export interface ArangoMembershipSnapshot {
 export type ArangoMembershipVerifier = (snapshot: ArangoMembershipSnapshot, signal?: AbortSignal) => Promise<boolean>;
 export declare const MAX_ARANGO_COORDINATORS = 16;
 export declare const ARANGO_COMMUNITY_VERSION: "3.11.14";
-/** Protected per-server API used to attest/set `default` or `readonly` mode. */
+/** Protected API used to attest cluster-wide `default`/maintenance mode. */
 export declare const ARANGO_SERVER_MODE_PATH: "/_admin/server/mode";
 /**
  * Accept only an explicit, bounded set of private authenticated endpoints.

package/dist/database.js

@@ -144,7 +144,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.5";
+var VERSION = "0.1.6";
 
 // src/database.ts
 var pools = new Map;
@@ -187,30 +187,23 @@ function arangoCoordinatorUrls(config) {
 async function resolveMembership(config, signal) {
   if (!config.membership) {
     const urls = arangoCoordinatorUrls(config);
-    const readOnlyUrls = config.readOnlyUrls?.length ? arangoCoordinatorUrls({ urls: config.readOnlyUrls }) : [];
-    if (urls.length + readOnlyUrls.length > MAX_ARANGO_COORDINATORS || urls.some((url) => readOnlyUrls.includes(url))) {
-      throw new ProviderError("ARANGO_COORDINATORS_INVALID", `Writable and read-only ArangoDB coordinator URLs must be disjoint and total at most ${MAX_ARANGO_COORDINATORS}.`);
+    const preferred = config.readPreferredUrls?.length ? arangoCoordinatorUrls({ urls: config.readPreferredUrls }) : [];
+    if (preferred.some((url) => !urls.includes(url))) {
+      throw new ProviderError("ARANGO_READ_PREFERENCE_INVALID", "Read-preferred coordinators must be a subset of the verified writable coordinator list.");
     }
     return {
-      members: [...urls.map((url) => ({
+      members: urls.map((url) => ({
         url,
         role: "coordinator",
         serverMode: "default",
-        access: "read-write",
         capabilities: { dirtyFollowerReads: false },
-        status: "healthy"
-      })), ...readOnlyUrls.map((url) => ({
-        url,
-        role: "coordinator",
-        serverMode: "readonly",
-        access: "read-only",
-        capabilities: { dirtyFollowerReads: false },
-        status: "healthy"
-      }))],
-      identity: `static:${urls.join(",")}:readonly:${readOnlyUrls.join(",")}`
+        status: "healthy",
+        readPreferred: preferred.includes(url)
+      })),
+      identity: `static:${urls.join(",")}:preferred:${preferred.join(",")}`
     };
   }
-  if (config.url || config.urls || config.readOnlyUrls) {
+  if (config.url || config.urls || config.readPreferredUrls) {
     throw new ProviderError("ARANGO_MEMBERSHIP_AMBIGUOUS", "Configure static coordinator URLs or verified membership, not both.");
   }
   if (!config.clusterId || config.membership.clusterId !== config.clusterId) {
@@ -228,7 +221,7 @@ async function resolveMembership(config, signal) {
     throw new ProviderError("ARANGO_MEMBERSHIP_EXPIRED", "Dynamic ArangoDB membership is not currently valid.");
   }
   const validAuthority = snapshot.authority === "forgezero-platform-signed" || snapshot.authority === "node-attested";
-  const validNodes = snapshot.coordinators.every((node) => Number.isFinite(node.observedAt) && node.nodeKey.length > 0 && node.nodeKey === node.publicKeys?.ed25519 && Boolean(node.publicKeys.mlDsa) && (node.status === "healthy" || node.status === "degraded" || node.status === "unhealthy") && node.role === "coordinator" && (node.serverMode === "default" || node.serverMode === "readonly") && node.access === (node.serverMode === "readonly" ? "read-only" : "read-write") && node.capabilities?.dirtyFollowerReads === false);
+  const validNodes = snapshot.coordinators.every((node) => Number.isFinite(node.observedAt) && node.nodeKey.length > 0 && node.nodeKey === node.publicKeys?.ed25519 && Boolean(node.publicKeys.mlDsa) && (node.status === "healthy" || node.status === "degraded" || node.status === "unhealthy") && (node.readPreferred === undefined || typeof node.readPreferred === "boolean") && node.role === "coordinator" && node.serverMode === "default" && node.capabilities?.dirtyFollowerReads === false);
   if (!validAuthority || !snapshot.revision || !validNodes) {
     throw new ProviderError("ARANGO_MEMBERSHIP_INVALID", "Dynamic ArangoDB membership needs a revision and observed timestamps.");
   }
@@ -267,6 +260,12 @@ function boundedAttempts(config, available, safe) {
   return Math.min(requested, available);
 }
 function requestIsSafe(request) {
+  if (request.readPreference !== undefined && request.readPreference !== "balanced" && request.readPreference !== "prefer-designated") {
+    throw new ProviderError("ARANGO_READ_PREFERENCE_INVALID", "Unknown ArangoDB read preference.");
+  }
+  if (request.readPreference && request.retrySafety !== "read") {
+    throw new ProviderError("ARANGO_READ_PREFERENCE_UNSAFE", "ArangoDB read preference requires an explicit read retry-safety assertion.");
+  }
   if (request.retrySafety === "read")
     return true;
   if (request.retrySafety !== "idempotent")
@@ -291,20 +290,11 @@ function selectNode(pool, excluded, now, eligibleMember) {
   }
   return;
 }
-function assertReadPolicy(request) {
-  if (request.readPreference !== undefined && request.readPreference !== "authoritative" && request.readPreference !== "prefer-readonly") {
-    throw new ProviderError("ARANGO_READ_PREFERENCE_INVALID", "Unknown ArangoDB read preference.");
-  }
-  if (request.readPreference && request.retrySafety !== "read") {
-    throw new ProviderError("ARANGO_READ_PREFERENCE_UNSAFE", "ArangoDB read preference requires an explicit read retry-safety assertion.");
-  }
-}
 function nodeForRequest(pool, request, fallback, excluded, now) {
-  const writable = (node) => node.member.access === "read-write";
-  if (request.retrySafety === "read" && request.readPreference === "prefer-readonly") {
-    return selectNode(pool, excluded, now, (node) => node.member.access === "read-only") ?? (fallback === "error" ? undefined : selectNode(pool, excluded, now, writable));
+  if (request.retrySafety === "read" && request.readPreference === "prefer-designated") {
+    return selectNode(pool, excluded, now, (node) => node.member.readPreferred === true) ?? (fallback === "error" ? undefined : selectNode(pool, excluded, now, () => true));
   }
-  return selectNode(pool, excluded, now, writable);
+  return selectNode(pool, excluded, now, () => true);
 }
 var arangodb = defineProvider({
   id: "arangodb",
@@ -342,14 +332,19 @@ var arangodb = defineProvider({
         title: "Coordinator URLs",
         description: "Authenticated private coordinators in this one logical cluster."
       },
-      readOnlyUrls: {
+      readPreferredUrls: {
         type: "array",
         minItems: 1,
-        maxItems: MAX_ARANGO_COORDINATORS - 1,
+        maxItems: MAX_ARANGO_COORDINATORS,
         uniqueItems: true,
         items: { type: "string" },
-        title: "Read-only Coordinator URLs",
-        description: "Optional bootstrap endpoints whose protected Arango server mode was probed as readonly."
+        title: "Read-preferred Coordinator URLs",
+        description: "Optional verified coordinator subset preferred by explicitly safe reads."
+      },
+      readPreferredFallback: {
+        type: "string",
+        enum: ["balanced", "error"],
+        title: "Read-preferred fallback"
       },
       clusterId: {
         type: "string",
@@ -369,11 +364,6 @@ var arangodb = defineProvider({
         minimum: 1000,
         maximum: 300000,
         title: "Local coordinator quarantine (ms)"
-      },
-      readOnlyFallback: {
-        type: "string",
-        enum: ["authoritative", "error"],
-        title: "Read-only coordinator fallback"
       }
     }
   },
@@ -385,11 +375,10 @@ var arangodb = defineProvider({
     const membership = await resolveMembership(config, context.signal);
     const members = membership.members;
     const urls = members.map(({ url }) => url);
-    assertReadPolicy(request);
     const safe = requestIsSafe(request);
-    const available = request.retrySafety === "read" && request.readPreference === "prefer-readonly" && config.readOnlyFallback === "error" ? members.filter(({ serverMode }) => serverMode === "readonly").length : members.filter(({ serverMode }) => request.retrySafety === "read" && request.readPreference === "prefer-readonly" ? true : serverMode === "default").length;
+    const available = members.length;
     if (available === 0) {
-      throw new ProviderError("ARANGO_COORDINATORS_UNAVAILABLE", request.readPreference === "prefer-readonly" ? "No verified read-only ArangoDB coordinator is available under the configured fallback policy." : "No verified authoritative ArangoDB coordinator is available.");
+      throw new ProviderError("ARANGO_COORDINATORS_UNAVAILABLE", "No verified authoritative ArangoDB coordinator is available.");
     }
     const attempts = boundedAttempts(config, available, safe);
     const key = `${membership.identity}/${config.database}/${config.username}`;
@@ -462,7 +451,7 @@ var arangodb = defineProvider({
         throw context.signal.reason ?? new ProviderError("ARANGO_ABORTED", "ArangoDB request was cancelled.");
       }
       const now = (config.now ?? Date.now)();
-      const node = nodeForRequest(pool, request, config.readOnlyFallback, tried, now);
+      const node = nodeForRequest(pool, request, config.readPreferredFallback, tried, now);
       if (!node)
         break;
       tried.add(node.url);

package/dist/email.js

@@ -144,7 +144,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.5";
+var VERSION = "0.1.6";
 
 // src/email.ts
 var recipients = (to) => Array.isArray(to) ? [...to] : [to];

package/dist/http.js

@@ -144,7 +144,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.5";
+var VERSION = "0.1.6";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {

package/dist/index.d.ts

@@ -156,4 +156,4 @@ export interface EmailMessage {
     from?: string;
     replyTo?: string;
 }
-export declare const VERSION = "0.1.5";
+export declare const VERSION = "0.1.6";

package/dist/index.js

@@ -144,7 +144,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.5";
+var VERSION = "0.1.6";
 export {
   staticConfig,
   nextHealth,

package/dist/pool.js

@@ -144,7 +144,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.5";
+var VERSION = "0.1.6";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {

package/dist/storage.js

@@ -144,7 +144,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.5";
+var VERSION = "0.1.6";
 
 // src/storage.ts
 var encoder = new TextEncoder;

package/dist/translation.js

@@ -144,7 +144,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.5";
+var VERSION = "0.1.6";
 
 // src/translation.ts
 var GOOGLE_ENDPOINT = "https://generativelanguage.googleapis.com/v1beta/models";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgezero/providers",
-  "version": "0.1.5",
+	"version": "0.1.7",
   "type": "module",
   "publishConfig": {
     "access": "public",