@fabricorg/platform-host 7.3.0 → 7.4.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @fabricorg/platform-host
 
+## 7.4.0
+
+### Minor Changes
+
+- eac74a9: Adapter circuit breakers now work. `AdapterImplementation.circuitBreaker` was declared and documented, but nothing read it. Platform now implements the breaker, and Host enforces it (issue #22).
+
+  **Release note: new failure semantics.** An adapter that declares `circuitBreaker: { mode: "enforce", ... }` can now have calls refused. Before this release that config had no effect. Review every adapter that already declares `mode: "enforce"` before upgrading, or switch it to `"monitor"` to observe first.
+
+  - **`@fabricorg/platform` (adapters subpath and root).**
+    - New exports: `InMemoryAdapterCircuitBreaker`, `AdapterCircuitBreakerRegistry`, `AdapterCircuitOpenError`, `isAdapterCircuitOpenError`, `classifyCircuitBreakerOutcome`, `assertAdapterCircuitBreakerConfig`, and the types `AdapterCircuitBreaker`, `AdapterCircuitBreakerProvider`, `AdapterCircuitState`, `AdapterCircuitOutcome`, `AdapterCircuitAdmission`, `AdapterCircuitBreakerEvent` and `AdapterCircuitBreakerManualOverride`. `AdapterCircuitAdmission.generation` identifies the epoch an admission was granted in.
+    - `AdapterCircuitBreakerConfig` gains the optional `manualOverride` (`"force_open"` or `"force_closed"`) and `probeLeaseMs` fields. No existing field changed.
+    - The breaker is per process: state is in memory, is not shared between replicas and is lost on restart.
+    - It goes closed → open → half-open (one probe) → closed, over a rolling `windowMs` and a `cooldownMs`. At most one half-open probe is outstanding until it records or its lease expires. The lease is the new optional `probeLeaseMs` (default `max(cooldownMs, windowMs)`), independent of the cooldown. `check()` is a side-effect-free preview.
+    - Only outcomes from the current epoch change state. The breaker's epoch advances on every state change, manual-override change and probe grant, and each admission carries it as `generation`. An outcome admitted in an earlier epoch is dropped: it never closes or reopens the breaker, never resolves or frees the probe slot, and is not counted toward a later trip. For example, a replaced probe that fails after its replacement closed the breaker does not reopen it. A direct `record()` call without an admission, or with one that has no `generation`, is treated as current.
+    - `failureThreshold` is a failure count, matching the .NET port. Once `minimumSamples` (default `failureThreshold`) outcomes are in the window, the breaker opens on `failureThreshold` consecutive failures, or on a failure ratio of at least `failureThreshold / minimumSamples`.
+    - Outcomes `transient_failure`, `timeout`, `ambiguous` and unclassified thrown errors count as failures. `permanent_failure` is ignored.
+  - **`executeWithAdapterRetry`** takes an optional `circuitBreaker`. Without it, behaviour is unchanged.
+    - With it, admission is checked immediately before every attempt, with no await between admission and `execute`, and the outcome of every attempt that reached `execute` is recorded.
+    - New optional `prepareAttempt(attempt, maxAttempts)` hook, awaited before admission. If it throws, no admission is taken and no outcome is recorded; the error is classified and retried or rethrown like an error thrown by `execute`.
+    - In `enforce` mode, a refused attempt is not executed and `AdapterCircuitOpenError` is thrown (`code: "ADAPTER_CIRCUIT_OPEN"`, with `adapterKey`, `attempt` and `retryAfterMs` when known).
+    - When the breaker opens between attempts, retrying stops and the same error is thrown.
+    - `monitor` mode never blocks. It reports `would_reject` telemetry through `onEvent`, and the callback's errors are swallowed. Events are delivered after the breaker operation that produced them commits, never during a decision or a record, so a callback that calls back into the breaker (for example to force it open) sees committed state, and its change applies from the next decision on. A callback never revokes an admission that is already committed; the README lists the two edge cases this leaves (a breaker call made from inside a callback, and `cooldownMs: 0`).
+  - **`@fabricorg/platform-host`.**
+    - Each Host instance keeps one breaker per `adapterType:operation`. A breaker is created on the adapter's first call, and only for adapters that declare `circuitBreaker`.
+    - Host now writes each attempt number to the adapter invocation record in `prepareAttempt`, before breaker admission, instead of inside `execute`. A store failure there is classified and retried as before, and is not counted against the breaker.
+    - The new `adapterCircuitBreakers` option supplies a shared `AdapterCircuitBreakerRegistry` or a custom provider (shared breakers, telemetry, manual override).
+    - A circuit-open refusal means the adapter never ran. Host marks the adapter invocation `failed` and appends `AdapterInvocationFailed` with the additive payload fields `reason: "circuit_open"` and `retryAfterMs`. The invocation then fails with status `failed`, the same path as an unsuccessful adapter result.
+    - A refusal is never routed to `reconciliation_required`, and it is never classified as a timeout. Domain events already appended in the `before_adapters` phase are kept.
+    - `createGovernedActionHost()` now throws at construction if an adapter declares an invalid `circuitBreaker` config, for example a `failureThreshold` below 1. Such a config was previously ignored.
+    - **Peer range:** Host now requires `@fabricorg/platform` `^1.8.0` (was `^1.2.0`), because it imports the new breaker exports at runtime. The manifest declares it as `workspace:^`, like the other workspace packages that peer on Platform, so the published range is the Platform version released with Host. A literal `^1.8.0` would fail the packed-consumer check (`pnpm verify:packed`) until the version PR publishes 1.8.0. A side effect: each later Host release will require at least the Platform version that is current when that Host is released.
+
+### Patch Changes
+
+- e0f7ca7: Host now imports `canonicalJson` from `@fabricorg/platform` instead of defining its own copy (issue #24). The function moved unchanged, so parameter digests and the external-completion digest are byte-identical, and Host still exports `canonicalJson`, `digestParameters` and `PARAMETER_DIGEST_ALGORITHM`. Host's peer range on `@fabricorg/platform` stays `workspace:^`, so the published range is the Platform version released alongside this Host release, which includes `canonicalJson`.
+
 ## 7.3.0
 
 ### Minor Changes

package/README.md

@@ -65,6 +65,28 @@ may or may not have been applied — is routed to `reconciliation_required` with
 `ExternalReconciliation` evidence and an `AdapterInvocationAmbiguous` lifecycle event rather than
 blindly retrying an unsafe effect.
 
+### Adapter circuit breakers
+
+An adapter that declares `circuitBreaker` gets a breaker from Host. By default each Host instance
+keeps its own `AdapterCircuitBreakerRegistry`: one in-process breaker per `adapterType:operation`,
+created on the adapter's first call from that adapter's own config. Adapters without a config get
+none, and behave as before. `createGovernedActionHost()` throws if a declared config is invalid.
+Breaker state lives in the Host's process memory: it is not shared between replicas or workers and
+is lost on restart. Pass `adapterCircuitBreakers` to share a registry between Host instances in one
+process, to receive breaker telemetry (`new AdapterCircuitBreakerRegistry({ onEvent })`), to set a
+manual override (`registry.get(type, operation)?.setManualOverride("force_open")`), or to supply a
+custom `AdapterCircuitBreakerProvider`.
+
+The breaker is consulted immediately before every attempt, including retries. Host writes the attempt number to the adapter invocation record first, in `prepareAttempt`, so nothing awaits between admission and the adapter call; a store failure there is not counted against the breaker. In `monitor` mode it
+never blocks. In `enforce` mode, while it is open, Host does not call the adapter: the adapter
+invocation is marked `failed`, `AdapterInvocationFailed` is appended with
+`payload.reason: "circuit_open"` (and `retryAfterMs` when known), and the invocation fails with
+status `failed` exactly like an unsuccessful adapter result. Because the adapter never ran, a
+circuit-open refusal is never routed to `reconciliation_required`. Domain events already appended
+in the `before_adapters` phase stay appended. If the breaker opens between retry attempts, Host stops
+retrying and records the refusal. See the `@fabricorg/platform` README for thresholds and outcome
+mapping.
+
 ## Execution authorization
 
 Submission authorization proves that a caller may create an invocation. Applications that delegate

package/dist/index.cjs

@@ -45,18 +45,8 @@ var ExternalCompletionError = class extends Error {
   }
 };
 var PARAMETER_DIGEST_ALGORITHM = "fabric-canonical-json-sha256-v1";
-function canonicalJson(value) {
-  return JSON.stringify(sort(value));
-}
-function sort(value) {
-  if (Array.isArray(value)) return value.map(sort);
-  if (value && typeof value === "object") {
-    return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, child]) => [key, sort(child)]));
-  }
-  return value;
-}
 function digestParameters(parameters) {
-  return crypto.createHash("sha256").update(canonicalJson(parameters)).digest("hex");
+  return crypto.createHash("sha256").update(platform.canonicalJson(parameters)).digest("hex");
 }
 var ATTRIBUTE_NAME = /^[a-z][a-z0-9-]*(?:\.[A-Za-z][A-Za-z0-9_-]*)+$/;
 var INVOCATION_SOURCE = /^(?:ui|sdui|api|agent|worker|system|[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+)$/;
@@ -457,7 +447,7 @@ function createExternalCompletionLifecycle(deps) {
     return withConsistency(actionResult2({ ...invocation, ...patch }), invocation.actionId);
   }
   function completionDigest(completion, provider) {
-    return crypto.createHash("sha256").update(canonicalJson({
+    return crypto.createHash("sha256").update(platform.canonicalJson({
       provider: provider ?? null,
       externalReference: completion.externalReference,
       outcome: completion.outcome,
@@ -886,8 +876,12 @@ function createGovernedActionHost(options) {
     }
   }
   const adapters = new platform.AdapterRegistry();
-  for (const adapter of options.adapters ?? []) adapters.register(adapter);
+  for (const adapter of options.adapters ?? []) {
+    if (adapter.circuitBreaker) platform.assertAdapterCircuitBreakerConfig(adapter.circuitBreaker);
+    adapters.register(adapter);
+  }
   const now = options.now ?? (() => /* @__PURE__ */ new Date());
+  const circuitBreakers = options.adapterCircuitBreakers ?? new platform.AdapterCircuitBreakerRegistry({ now: () => now().getTime() });
   const extractEvents = options.extractEvents ?? DEFAULT_EXTRACT_EVENTS;
   const configuredActionResolver = options.resolveAction ?? options.registry?.resolveAction;
   if (!configuredActionResolver) throw new Error("Platform Host requires an explicit module registry or resolveAction function.");
@@ -1569,14 +1563,20 @@ function createGovernedActionHost(options) {
             );
             adapterDeadlineTimer.unref?.();
           }
+          const circuitBreaker = circuitBreakers.forAdapter(adapter);
           const result2 = await platform.executeWithAdapterRetry({
+            ...circuitBreaker ? { circuitBreaker } : {},
             policy: step.retryPolicy ?? adapter.retryPolicy,
             defaultIdempotent: adapter.idempotent,
-            execute: async (attempt, maxAttempts) => {
+            // Every await before the call happens here, before breaker
+            // admission, so nothing awaits between admission and the adapter.
+            prepareAttempt: async (attempt) => {
               await options.store.updateAdapterInvocation(adapterInvocationId, {
                 attempt,
                 updatedAt: now()
               });
+            },
+            execute: (attempt, maxAttempts) => {
               return adapter.execute(input, {
                 tenantId,
                 spaceId,
@@ -1594,6 +1594,7 @@ function createGovernedActionHost(options) {
             getError: (result3) => result3.error,
             classifyOutcome: (result3) => result3.outcome ?? "transient_failure",
             classifyThrownError: (error) => {
+              if (platform.isAdapterCircuitOpenError(error)) return "transient_failure";
               if (adapterController?.signal.aborted) return "timeout";
               const message = error instanceof Error ? error.message : String(error);
               if (/timeout|deadline|timed?\s*out/i.test(message)) return "timeout";
@@ -1771,6 +1772,19 @@ function createGovernedActionHost(options) {
             error: message,
             updatedAt: now()
           });
+          if (platform.isAdapterCircuitOpenError(error)) {
+            await appendEvent(invocation, {
+              eventType: "AdapterInvocationFailed",
+              subjectType: adapterEventSubject.subjectType,
+              subjectId: adapterEventSubject.subjectId,
+              payload: {
+                adapterType: step.adapterType,
+                operation: step.operation,
+                reason: "circuit_open",
+                ...error.retryAfterMs !== void 0 ? { retryAfterMs: error.retryAfterMs } : {}
+              }
+            }, `adapter:${stepIndex}:failed`);
+          }
           return fail2(invocation, "failed", message);
         } finally {
           if (adapterDeadlineTimer) clearTimeout(adapterDeadlineTimer);
@@ -4449,6 +4463,10 @@ async function runTenantIsolationChecks(subject) {
   return { passed: checks.every((check) => check.status !== "failed"), checks };
 }
 
+Object.defineProperty(exports, "canonicalJson", {
+  enumerable: true,
+  get: function () { return platform.canonicalJson; }
+});
 exports.ActionAdmissionError = ActionAdmissionError;
 exports.ExternalCompletionError = ExternalCompletionError;
 exports.IdempotencyConflictError = IdempotencyConflictError;
@@ -4459,7 +4477,6 @@ exports.PLATFORM_HOST_HEALTH_CONTRACT_VERSION = PLATFORM_HOST_HEALTH_CONTRACT_VE
 exports.PLATFORM_HOST_METRIC_NAMES = PLATFORM_HOST_METRIC_NAMES;
 exports.PostgresPlatformHostStore = PostgresPlatformHostStore;
 exports.applyPostgresMigrations = applyPostgresMigrations;
-exports.canonicalJson = canonicalJson;
 exports.cloneOutboxRecord = cloneOutboxRecord;
 exports.createDurableSagaParentLifecycle = createDurableSagaParentLifecycle;
 exports.createGovernedActionHost = createGovernedActionHost;