@forgezero/providers 0.1.6 → 0.1.7

package/dist/database.d.ts

@@ -43,6 +43,10 @@ export interface ArangoConfig {
     url?: string;
     /** Explicit authenticated private coordinators. Bounded to prevent config abuse. */
     urls?: 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
@@ -70,6 +74,8 @@ export interface Query {
      * caller assertions; this adapter never guesses AQL semantics from text.
      */
     retrySafety?: 'read' | 'idempotent' | 'never';
+    /** 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;
 }
@@ -84,6 +90,8 @@ export interface ArangoCoordinatorMember {
         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. */

package/dist/database.js

@@ -187,18 +187,23 @@ function arangoCoordinatorUrls(config) {
 async function resolveMembership(config, signal) {
   if (!config.membership) {
     const urls = arangoCoordinatorUrls(config);
+    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) => ({
         url,
         role: "coordinator",
         serverMode: "default",
         capabilities: { dirtyFollowerReads: false },
-        status: "healthy"
+        status: "healthy",
+        readPreferred: preferred.includes(url)
       })),
-      identity: `static:${urls.join(",")}`
+      identity: `static:${urls.join(",")}:preferred:${preferred.join(",")}`
     };
   }
-  if (config.url || config.urls) {
+  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) {
@@ -216,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.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.");
   }
@@ -255,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")
@@ -279,7 +290,10 @@ function selectNode(pool, excluded, now, eligibleMember) {
   }
   return;
 }
-function nodeForRequest(pool, excluded, now) {
+function nodeForRequest(pool, request, fallback, excluded, now) {
+  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, () => true);
 }
 var arangodb = defineProvider({
@@ -318,6 +332,20 @@ var arangodb = defineProvider({
         title: "Coordinator URLs",
         description: "Authenticated private coordinators in this one logical cluster."
       },
+      readPreferredUrls: {
+        type: "array",
+        minItems: 1,
+        maxItems: MAX_ARANGO_COORDINATORS,
+        uniqueItems: true,
+        items: { type: "string" },
+        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",
         title: "Cluster ID",
@@ -423,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, tried, now);
+      const node = nodeForRequest(pool, request, config.readPreferredFallback, tried, now);
       if (!node)
         break;
       tried.add(node.url);

package/package.json

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