@registrystack/client 0.39.0 → 0.41.0

package/README.md

@@ -1,7 +1,7 @@
 # @registrystack/client
 
 One versioned Node.js package for the Discovery, Evidence, Base Registry
-Engine, Casework, and Messaging client APIs in Registry Stack.
+Engine, Casework, Messaging, and Scheduling client APIs in Registry Stack.
 
 ## Install
 
@@ -9,15 +9,15 @@ Engine, Casework, and Messaging client APIs in Registry Stack.
 npm install "@registrystack/client@<version>"
 ```
 
-Requires Node.js 22.12 or newer. Supported targets are macOS arm64, Linux
+Requires Node.js 24.11 or newer. Supported targets are macOS arm64, Linux
 arm64 with glibc, and Linux x64 with glibc; installing the package pulls in
-one platform-specific optional dependency containing all five native
+one platform-specific optional dependency containing all six native
 bindings.
 
 ## Usage
 
 ```js
-const { discovery, evidence, breg, casework, messaging } = require('@registrystack/client');
+const { discovery, evidence, breg, casework, messaging, scheduling } = require('@registrystack/client');
 
 const registry = new breg.BaseRegistryClient({
   baseUrl: 'https://registry.example.invalid/',
@@ -28,6 +28,9 @@ const work = new casework.CaseworkClient({
 const messages = new messaging.MessagingClient({
   baseUrl: 'https://messaging.example.invalid/',
 });
+const appointments = new scheduling.SchedulingClient({
+  baseUrl: 'https://scheduling.example.invalid/',
+});
 ```
 
 ## Products
@@ -42,6 +45,8 @@ const messages = new messaging.MessagingClient({
   recovery, history, holdings, and directory bootstrap.
 - `messaging`: Registry Messaging, submit, inspect, cancel, and preview
   institution-owned messages.
+- `scheduling`: Registry Scheduling, published offerings, availability,
+  holds, and appointments over operator-anchored supply.
 
 Each product remains in its own namespace because its routing,
 authentication, errors, and verification rules are different.
@@ -79,11 +84,21 @@ descriptions grant no authority, so select the opaque create, patch, and
 lifecycle authorities from that same contract before executing a mutation.
 Methods ending in `Json` keep values exact across the Node number boundary:
 they accept domain JSON text and return `valueJson` alongside the usual
-trace, ETag, location, and opaque continuation. The client never retries a
-mutation automatically. See
+trace, ETag, location, and opaque continuation. See
 [Exact JSON in Node](https://docs.registrystack.org/reference/client-api/#exact-json-in-node)
 for the full rules.
 
+A keyed BReg, Casework, Messaging, or Scheduling mutation whose outcome is
+unknown is resent identically under the same idempotency key up to
+`maxMutationRetries` times, a client option: 0 to 2, default 2, and 0 sends it
+once. Reads, unkeyed calls, and every 4xx refusal are never resent. When the returned error
+still reports `outcomeUnknown`, the mutation may have taken effect: recover by
+sending it again under the same key, because a new key could apply it twice.
+`outcomeUnknown` is false for `410 idempotency.expired`, but there an earlier
+attempt under the key was answered and may have committed: reconcile that
+attempt before choosing a new key.
+See [Unknown outcomes](https://docs.registrystack.org/reference/client-api/#unknown-outcomes-and-the-same-key-retry).
+
 `breg.verifyWebhookDelivery({ method, path, headers, body, key })` authenticates
 the exact bytes of one Version 1 webhook delivery. The result returns
 `deliveryTime` and `idempotencyKey`; the receiver must bound clock skew and
@@ -106,6 +121,9 @@ Registry Stack v0.30.0.
 The `messaging` namespace is part of the unified package beginning with
 Registry Stack v0.38.0.
 
+The `scheduling` namespace is part of the unified package beginning with
+Registry Stack v0.40.0.
+
 ## Casework notes
 
 The Casework module is for a trusted server host. Each call takes that request's
@@ -114,9 +132,15 @@ selected source profile. The client does not retain them. Browsers should send
 only the host's session cookie. Claim, release, and decide consume the
 caller-filtered action returned on the item, including its exact route and
 `ifMatch` revision. Mutations require a caller-controlled idempotency key and
-are never retried automatically. After a lost response, use
+are resent only under the bounded same-key retry above; review request create
+and cancel are never resent. After a lost response, use
 `recoverDecisionByKey` with the original key so recovery does not depend on the
 attempt identifier being received.
+Reviewer inboxes accept an `ownership` filter before pagination.
+`supervisoryReviewTasks` returns only task and accountability references for
+queues the selected supervisor currently serves; its state is a holder-free
+string. A single decided-task read
+includes `decisionReceipt` only for the caller who recorded that decision.
 
 ## Documentation
 

package/breg/client.d.ts

@@ -8,10 +8,10 @@ export type JsonObject = { readonly [key: string]: JsonValue }
 export type SafeInteger = number
 
 export type WebhookVerificationRefusalCode =
-  | 'missing_header'
-  | 'malformed_signature'
-  | 'signature_mismatch'
-  | 'unsupported_version'
+  | 'missing-header'
+  | 'malformed-signature'
+  | 'signature-mismatch'
+  | 'unsupported-version'
 
 export interface WebhookDeliveryInput {
   method: string
@@ -137,10 +137,44 @@ export interface BaseRegistryClientConfig {
   maxResponseBytes?: SafeInteger | null
   userAgent?: string | null
   trustedRootCertificates?: string | null
+  /**
+   * How many times a keyed mutation (create, patch, attachment upload or
+   * delete, lifecycle action, immediate action, batch, tombstone, statistics
+   * publish or withdraw) whose outcome is unknown is resent, identically and
+   * under the same idempotency key, before its error is returned: a whole
+   * number from 0 to 2, default 2; 0 sends it once. Any other value is a
+   * `configuration` error.
+   */
+  maxMutationRetries?: SafeInteger | null
 }
 
 export type RecordFormat = 'json' | 'json-ld'
 
+export interface BRegStatisticalDimensionDescriptor {
+  readonly field: string
+  readonly vocabulary: string
+  readonly codes: ReadonlyArray<string>
+}
+
+export interface BRegStatisticalDatasetDescriptor {
+  readonly id: string
+  readonly unit: string
+  readonly periodKind: 'flow' | 'stock'
+  readonly granularity: 'day' | 'month' | 'quarter' | 'year'
+  readonly firstPeriod: string
+  readonly dimensions: ReadonlyArray<BRegStatisticalDimensionDescriptor>
+  readonly definitionDigest: string
+  readonly operations: ReadonlyArray<
+    | 'read-live'
+    | 'list-releases'
+    | 'read-released-series'
+    | 'read-latest-release'
+    | 'read-release-version'
+    | 'publish-release'
+    | 'withdraw-release'
+  >
+}
+
 export interface RecordProjectionOptions {
   select?: ReadonlyArray<string> | null
   accessProfile?: string | null
@@ -224,8 +258,8 @@ export type BRegRequestResultReferenceData = JsonObject & {
 }
 export type BRegRequestState = 'draft' | 'submitted' | 'cancelled' | 'applied'
 export type BRegRequestReviewRequirement =
-  | Readonly<{ mode: 'none' }>
-  | Readonly<{ authority: string; policyId: string }>
+  | Readonly<{ type: 'none' }>
+  | Readonly<{ type: 'required'; authority: string; policyId: string }>
 export type BRegExternalReviewStatus = Readonly<{
   submission: Readonly<{
     state: 'pending' | 'accepted' | 'uncertain' | 'cancelling' | 'cancelled' | 'failed'
@@ -460,9 +494,9 @@ export interface BRegQueryDescriptor {
   readonly sortableFields: ReadonlyArray<BRegQueryField>
   readonly allowCount: boolean
   readonly defaultPageSize: number
-  readonly maxPageSize: number
-  readonly maxFilterClauses: number
-  readonly maxInValues: number
+  readonly maximumPageSize: number
+  readonly maximumFilterClauses: number
+  readonly maximumInValues: number
   readonly pagination: { readonly parameter: string; readonly responsePath: string; readonly exclusive: boolean }
   readonly temporal: JsonObject | null
   readonly spatialQueries?: {
@@ -820,7 +854,7 @@ export interface BRegAttachmentState {
 
 /** What one record projection says about one slot. */
 export type BRegAttachmentSlotValue =
-  | { readonly kind: 'not_selected'; readonly value: null }
+  | { readonly kind: 'not-selected'; readonly value: null }
   | { readonly kind: 'empty'; readonly value: null }
   | { readonly kind: 'filled'; readonly value: BRegAttachmentState }
 
@@ -940,6 +974,18 @@ export declare class BRegLifecycleAction {
   readonly body: JsonObject
 }
 
+/**
+ * Inert bounded immediate-action evidence: inputs, saved target conditions,
+ * and the idempotency key. Persist these bytes with owner-only access before
+ * invoking.
+ */
+export declare class BRegPreparedAction {
+  private constructor()
+  private readonly __opaque: void
+  static fromBytes(bytes: Buffer): BRegPreparedAction
+  toBytes(): Buffer
+}
+
 /** Inert bounded Create evidence. Persist these bytes with owner-only access. */
 export declare class BRegPreparedCreate {
   private constructor()
@@ -956,6 +1002,12 @@ export declare class BRegPreparedLifecycle {
   toBytes(): Buffer
 }
 
+/** Revalidated action invocation and key. It still requires fresh metadata authority to send. */
+export declare class BRegRecoveredAction {
+  private constructor()
+  private readonly __opaque: void
+}
+
 /** Revalidated Create request. It still requires fresh metadata authority to send. */
 export declare class BRegRecoveredCreate {
   private constructor()
@@ -975,6 +1027,8 @@ export declare class BRegMetadata {
   readonly operations: ReadonlyArray<BRegOperationDescriptor>
   readonly immediateActions: ReadonlyArray<BRegImmediateActionDescriptor>
   readonly actionsJson: string | null
+  /** Validated caller-filtered inert descriptions. They never grant entity authority. */
+  readonly statisticalDatasets: ReadonlyArray<BRegStatisticalDatasetDescriptor> | null
   readonly registryIdentifier: string
   readonly registryVersion: string
   readonly registryRevision: string
@@ -1001,6 +1055,20 @@ export interface BaseRegistryClientFailure extends Error {
   readonly traceId?: string
   readonly transportKind?: string
   readonly tokenKind?: string
+  /**
+   * Whether the request may have taken effect although this error was raised:
+   * a timeout or broken exchange after sending, an unusable answer, or a 5xx
+   * other than `action.handler_failed` and
+   * `statistical_dataset.domain_violation`, which the engine returns only with
+   * the attempt rolled back. When true, recover a keyed mutation by sending it
+   * again under the same idempotency key; a new key could apply it twice.
+   * False for a configuration or request defect, a credential the token
+   * provider could not supply, a connection never established, and every 4xx
+   * refusal. It is false for `410 idempotency.expired` too, but there an
+   * earlier attempt under the key committed and only its held response is
+   * gone: read the resource before choosing a new key.
+   */
+  readonly outcomeUnknown: boolean
 }
 
 export declare class BaseRegistryClientError extends Error implements BaseRegistryClientFailure {
@@ -1014,6 +1082,20 @@ export declare class BaseRegistryClientError extends Error implements BaseRegist
   readonly traceId?: string
   readonly transportKind?: string
   readonly tokenKind?: string
+  /**
+   * Whether the request may have taken effect although this error was raised:
+   * a timeout or broken exchange after sending, an unusable answer, or a 5xx
+   * other than `action.handler_failed` and
+   * `statistical_dataset.domain_violation`, which the engine returns only with
+   * the attempt rolled back. When true, recover a keyed mutation by sending it
+   * again under the same idempotency key; a new key could apply it twice.
+   * False for a configuration or request defect, a credential the token
+   * provider could not supply, a connection never established, and every 4xx
+   * refusal. It is false for `410 idempotency.expired` too, but there an
+   * earlier attempt under the key committed and only its held response is
+   * gone: read the resource before choosing a new key.
+   */
+  readonly outcomeUnknown: boolean
 }
 
 export declare class BaseRegistryClient {
@@ -1052,6 +1134,14 @@ export declare class BaseRegistryClient {
   actionTargetConditionsJson(binding: BRegImmediateActionBinding, inputsJson: string): Promise<BRegActionTargetConditions>
   invokeAction(binding: BRegImmediateActionBinding, inputs: JsonObject, idempotencyKey: string, conditions?: BRegActionTargetConditions | null): Promise<CompleteOutcome<BRegActionReceipt>>
   invokeActionJson(binding: BRegImmediateActionBinding, inputsJson: string, idempotencyKey: string, conditions?: BRegActionTargetConditions | null): Promise<JsonOutcome>
+  /** Validate and retain one invocation before any I/O, for recovery after a lost response. */
+  prepareAction(binding: BRegImmediateActionBinding, inputs: JsonObject, idempotencyKey: string, conditions?: BRegActionTargetConditions | null): BRegPreparedAction
+  prepareActionJson(binding: BRegImmediateActionBinding, inputsJson: string, idempotencyKey: string, conditions?: BRegActionTargetConditions | null): BRegPreparedAction
+  /** Revalidate saved evidence against fresh authority and the original inputs and key. Performs no I/O. */
+  recoverAction(binding: BRegImmediateActionBinding, prepared: BRegPreparedAction, inputs: JsonObject, idempotencyKey: string): BRegRecoveredAction
+  recoverActionJson(binding: BRegImmediateActionBinding, prepared: BRegPreparedAction, inputsJson: string, idempotencyKey: string): BRegRecoveredAction
+  executeRecoveredAction(binding: BRegImmediateActionBinding, recovered: BRegRecoveredAction): Promise<CompleteOutcome<BRegActionReceipt>>
+  executeRecoveredActionJson(binding: BRegImmediateActionBinding, recovered: BRegRecoveredAction): Promise<JsonOutcome>
   createRecord(binding: BRegCreateBinding, data: JsonObject, idempotencyKey: string, format?: RecordFormat | null): Promise<CompleteOutcome<RecordEnvelope>>
   prepareCreate(binding: BRegCreateBinding, data: JsonObject, idempotencyKey: string, format?: RecordFormat | null): BRegPreparedCreate
   prepareCreateJson(binding: BRegCreateBinding, dataJson: string, idempotencyKey: string, format?: RecordFormat | null): BRegPreparedCreate

package/breg/client.js

@@ -12,6 +12,7 @@ class BaseRegistryClientError extends Error {
     super(envelope.message);
     this.name = 'BaseRegistryClientError';
     this.kind = envelope.kind;
+    this.outcomeUnknown = envelope.outcomeUnknown === true;
     for (const field of ['code', 'planRefusal', 'refusalCode', 'reasonCode', 'status', 'traceId', 'transportKind', 'tokenKind']) {
       if (envelope[field] !== undefined && envelope[field] !== null) this[field] = envelope[field];
     }
@@ -60,19 +61,19 @@ function inputError(kind) {
 
 function plainDataObject(value, expectedFields) {
   if (value === null || typeof value !== 'object' || Array.isArray(value) || isProxy(value)) {
-    throw inputError('invalid_request');
+    throw inputError('invalid-request');
   }
   const prototype = Object.getPrototypeOf(value);
-  if (prototype !== Object.prototype && prototype !== null) throw inputError('invalid_request');
+  if (prototype !== Object.prototype && prototype !== null) throw inputError('invalid-request');
   const keys = Reflect.ownKeys(value);
   if (keys.some((key) => typeof key !== 'string')
     || keys.length !== expectedFields.length
-    || keys.some((key) => !expectedFields.includes(key))) throw inputError('invalid_request');
+    || keys.some((key) => !expectedFields.includes(key))) throw inputError('invalid-request');
   const result = Object.create(null);
   for (const field of expectedFields) {
     const descriptor = Object.getOwnPropertyDescriptor(value, field);
     if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) {
-      throw inputError('invalid_request');
+      throw inputError('invalid-request');
     }
     result[field] = descriptor.value;
   }
@@ -81,19 +82,19 @@ function plainDataObject(value, expectedFields) {
 
 function webhookHeaders(value) {
   if (value === null || typeof value !== 'object' || Array.isArray(value) || isProxy(value)) {
-    throw inputError('invalid_request');
+    throw inputError('invalid-request');
   }
   const prototype = Object.getPrototypeOf(value);
-  if (prototype !== Object.prototype && prototype !== null) throw inputError('invalid_request');
+  if (prototype !== Object.prototype && prototype !== null) throw inputError('invalid-request');
   const keys = Reflect.ownKeys(value);
   if (keys.some((key) => typeof key !== 'string')) {
-    throw inputError('invalid_request');
+    throw inputError('invalid-request');
   }
   const result = Object.create(null);
   for (const name of keys) {
     const descriptor = Object.getOwnPropertyDescriptor(value, name);
     if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, 'value')
-      || typeof descriptor.value !== 'string') throw inputError('invalid_request');
+      || typeof descriptor.value !== 'string') throw inputError('invalid-request');
     result[name] = descriptor.value;
   }
   return result;
@@ -105,14 +106,14 @@ function verifyWebhookDelivery(value) {
     if (typeof input.method !== 'string' || typeof input.path !== 'string'
       || !Buffer.isBuffer(input.body) || !Buffer.isBuffer(input.key)
       || isSharedArrayBuffer(input.body.buffer) || isSharedArrayBuffer(input.key.buffer)) {
-      throw inputError('invalid_request');
+      throw inputError('invalid-request');
     }
     input.headers = webhookHeaders(input.headers);
     input.body = Buffer.from(input.body);
     input.key = Buffer.from(input.key);
     return native.verifyWebhookDelivery(input);
   } catch (error) {
-    throw normalize(error, 'invalid_request');
+    throw normalize(error, 'invalid-request');
   }
 }
 
@@ -184,10 +185,10 @@ function sanitizeArguments(args, jsonIndexes, requiredIndexes) {
   return args.map((value, index) => {
     if (!jsonIndexes.has(index)) return value;
     if (value === undefined || value === null) {
-      if (requiredIndexes.has(index)) throw inputError('invalid_request');
+      if (requiredIndexes.has(index)) throw inputError('invalid-request');
       return value;
     }
-    return cloneJson(value, budget, 0, 'invalid_request');
+    return cloneJson(value, budget, 0, 'invalid-request');
   });
 }
 
@@ -198,7 +199,7 @@ function wrapAsync(name, jsonIndexes = [], requiredIndexes = []) {
       const sanitized = sanitizeArguments(args, new Set(jsonIndexes), new Set(requiredIndexes));
       return original.apply(this, sanitized).catch((error) => { throw normalize(error); });
     } catch (error) {
-      throw normalize(error, 'invalid_request');
+      throw normalize(error, 'invalid-request');
     }
   };
 }
@@ -217,7 +218,7 @@ for (const [method, jsonIndexes, requiredIndexes] of [
   ['listRelationshipRecords', [3]], ['continueRelationshipList', [0], [0]],
   ['lookupRecord', [2, 3]], ['createRecord', [1], [1]],
   ['actionTargetConditions', [1], [1]], ['invokeAction', [1], [1]],
-  ['executeRecoveredCreate'],
+  ['executeRecoveredAction'], ['executeRecoveredCreate'],
   ['patchRecord', [3], [3]], ['batchRecords', [1], [1]], ['tombstoneRecord'],
   ['executeLifecycleAction'],
   ['executeRecoveredLifecycleAction'],
@@ -231,13 +232,16 @@ for (const [method, jsonIndexes, requiredIndexes] of [
   ['listRelationshipRecordsJson', [3]], ['continueRelationshipListJson', [0], [0]],
   ['lookupRecordJson', [3]], ['createRecordJson'], ['patchRecordJson'], ['executeLifecycleActionJson'],
   ['actionTargetConditionsJson'], ['invokeActionJson'], ['batchRecordsJson'], ['tombstoneRecordJson'],
-  ['executeRecoveredCreateJson'], ['executeRecoveredLifecycleActionJson'],
+  ['executeRecoveredActionJson'], ['executeRecoveredCreateJson'],
+  ['executeRecoveredLifecycleActionJson'],
   ['uploadAttachmentJson'], ['deleteAttachmentJson'],
   ['createIngestionRun', [1], [1]], ['listIngestionRuns', [1]],
   ['readIngestionRun'], ['submitIngestionChunk'], ['cancelIngestionRun'],
 ]) wrapAsync(method, jsonIndexes, requiredIndexes);
 
 for (const [method, jsonIndexes, requiredIndexes] of [
+  ['prepareAction', [1], [1]], ['prepareActionJson'],
+  ['recoverAction', [2], [2]], ['recoverActionJson'],
   ['prepareCreate', [1], [1]], ['prepareCreateJson'], ['recoverCreate'],
   ['prepareLifecycleAction', [1], [1]], ['prepareLifecycleActionJson'],
   ['recoverLifecycleAction'],
@@ -249,7 +253,7 @@ for (const [method, jsonIndexes, requiredIndexes] of [
         args, new Set(jsonIndexes), new Set(requiredIndexes),
       ));
     } catch (error) {
-      throw normalize(error, 'invalid_request');
+      throw normalize(error, 'invalid-request');
     }
   };
 }
@@ -269,10 +273,10 @@ function preparedClass(Class, label) {
     fromBytes: {
       value(bytes) {
         try {
-          if (!Buffer.isBuffer(bytes)) throw inputError('invalid_request');
+          if (!Buffer.isBuffer(bytes)) throw inputError('invalid-request');
           return Class.fromBytes(bytes);
         } catch (error) {
-          throw normalize(error, 'invalid_request');
+          throw normalize(error, 'invalid-request');
         }
       },
     },
@@ -284,6 +288,7 @@ function preparedClass(Class, label) {
   return Facade;
 }
 
+const BRegPreparedAction = preparedClass(native.BRegPreparedAction, 'BRegPreparedAction');
 const BRegPreparedCreate = preparedClass(native.BRegPreparedCreate, 'BRegPreparedCreate');
 const BRegPreparedLifecycle = preparedClass(
   native.BRegPreparedLifecycle, 'BRegPreparedLifecycle',
@@ -292,17 +297,17 @@ const BRegPreparedLifecycle = preparedClass(
 const withReason = native.BRegLifecycleAction.prototype.withReason;
 native.BRegLifecycleAction.prototype.withReason = function (reason) {
   try {
-    if (typeof reason !== 'string' || !reason.isWellFormed()) throw inputError('invalid_request');
+    if (typeof reason !== 'string' || !reason.isWellFormed()) throw inputError('invalid-request');
     return withReason.call(this, reason);
   } catch (error) {
-    throw normalize(error, 'invalid_request');
+    throw normalize(error, 'invalid-request');
   }
 };
 
 const lifecycleActionsJson = native.BaseRegistryClient.prototype.lifecycleActionsJson;
 native.BaseRegistryClient.prototype.lifecycleActionsJson = function (...args) {
   try { return lifecycleActionsJson.apply(this, args); }
-  catch (error) { throw normalize(error, 'invalid_request'); }
+  catch (error) { throw normalize(error, 'invalid-request'); }
 };
 
 const lifecycleActions = native.BaseRegistryClient.prototype.lifecycleActions;
@@ -311,7 +316,7 @@ native.BaseRegistryClient.prototype.lifecycleActions = function (...args) {
     const sanitized = sanitizeArguments(args, new Set([1]), new Set([1]));
     return lifecycleActions.apply(this, sanitized);
   } catch (error) {
-    throw normalize(error, 'invalid_request');
+    throw normalize(error, 'invalid-request');
   }
 };
 
@@ -321,7 +326,7 @@ native.BaseRegistryClient.prototype.requestHistory = function (...args) {
     const sanitized = sanitizeArguments(args, new Set([0]), new Set([0]));
     return requestHistory.apply(this, sanitized);
   } catch (error) {
-    throw normalize(error, 'invalid_request');
+    throw normalize(error, 'invalid-request');
   }
 };
 
@@ -332,11 +337,11 @@ for (const name of ['findProposal', 'findApplication']) {
       const proposalVersion = args[2];
       if (!Number.isSafeInteger(proposalVersion)
         || proposalVersion < 1 || proposalVersion > 0xffff_ffff) {
-        throw inputError('invalid_request');
+        throw inputError('invalid-request');
       }
       return original.apply(this, args);
     } catch (error) {
-      throw normalize(error, 'invalid_request');
+      throw normalize(error, 'invalid-request');
     }
   };
 }
@@ -346,7 +351,7 @@ native.BRegAttachmentSlot.prototype.valueIn = function (...args) {
   try {
     return valueIn.apply(this, sanitizeArguments(args, new Set([0]), new Set([0])));
   } catch (error) {
-    throw normalize(error, 'invalid_request');
+    throw normalize(error, 'invalid-request');
   }
 };
 
@@ -356,7 +361,7 @@ for (const name of ['prepareUpload', 'acceptsContentType']) {
     try {
       return original.apply(this, args);
     } catch (error) {
-      throw normalize(error, 'invalid_request');
+      throw normalize(error, 'invalid-request');
     }
   };
 }
@@ -370,20 +375,20 @@ for (const name of [
     try {
       return original.apply(this, args);
     } catch (error) {
-      throw normalize(error, 'invalid_request');
+      throw normalize(error, 'invalid-request');
     }
   };
 }
 
 function encodeIngestionChunk(chunkIndex, items, prefixDigest) {
   try {
-    if (!Number.isSafeInteger(chunkIndex)) throw inputError('invalid_request');
+    if (!Number.isSafeInteger(chunkIndex)) throw inputError('invalid-request');
     const sanitized = sanitizeArguments(
       [chunkIndex, items, prefixDigest], new Set([1]), new Set([1]),
     );
     return native.encodeIngestionChunk(...sanitized);
   } catch (error) {
-    throw normalize(error, 'invalid_request');
+    throw normalize(error, 'invalid-request');
   }
 }
 
@@ -392,10 +397,10 @@ function encodeIngestionChunk(chunkIndex, items, prefixDigest) {
 const ingestionChunkReceipt = native.BaseRegistryClient.prototype.ingestionChunkReceipt;
 native.BaseRegistryClient.prototype.ingestionChunkReceipt = function (...args) {
   try {
-    if (!Number.isSafeInteger(args[2])) throw inputError('invalid_request');
+    if (!Number.isSafeInteger(args[2])) throw inputError('invalid-request');
     return ingestionChunkReceipt.apply(this, args).catch((error) => { throw normalize(error); });
   } catch (error) {
-    throw normalize(error, 'invalid_request');
+    throw normalize(error, 'invalid-request');
   }
 };
 
@@ -403,11 +408,11 @@ const ingestionPrefixDigestUpdate = native.BRegIngestionPrefixDigest.prototype.u
 native.BRegIngestionPrefixDigest.prototype.update = function (data) {
   try {
     if (!Buffer.isBuffer(data) || isSharedArrayBuffer(data.buffer)) {
-      throw inputError('invalid_request');
+      throw inputError('invalid-request');
     }
     return ingestionPrefixDigestUpdate.call(this, data);
   } catch (error) {
-    throw normalize(error, 'invalid_request');
+    throw normalize(error, 'invalid-request');
   }
 };
 
@@ -456,8 +461,10 @@ module.exports = {
   BRegActionTargetConditions: native.BRegActionTargetConditions,
   BRegTombstoneBinding: native.BRegTombstoneBinding,
   BRegBatchBinding: native.BRegBatchBinding,
+  BRegPreparedAction,
   BRegPreparedCreate,
   BRegPreparedLifecycle,
+  BRegRecoveredAction: native.BRegRecoveredAction,
   BRegRecoveredCreate: native.BRegRecoveredCreate,
   BRegRecoveredLifecycle: native.BRegRecoveredLifecycle,
   BRegIngestionChunk: native.BRegIngestionChunk,

package/breg/index.d.ts

@@ -37,8 +37,29 @@ export declare class BaseRegistryClient {
   lookupRecord(entityRoute: string, selector: string, values?: any | undefined | null, options?: any | undefined | null): Promise<CompleteOutcome>
   /** Fetch opaque target conditions for one metadata-selected action. */
   actionTargetConditions(binding: BRegImmediateActionBinding, inputs: any): Promise<BRegActionTargetConditions>
-  /** Invoke one metadata-selected immediate action without automatic retry. */
+  /**
+   * Invoke one metadata-selected immediate action. An invocation whose
+   * outcome is unknown is resent identically under the same key, at most
+   * `maxMutationRetries` times.
+   */
   invokeAction(binding: BRegImmediateActionBinding, inputs: any, idempotencyKey: string, conditions?: BRegActionTargetConditions | undefined | null): Promise<CompleteOutcome>
+  /**
+   * Prepare inert invocation evidence before any token acquisition or I/O.
+   * Persist `toBytes` before invoking so a lost response can be recovered.
+   */
+  prepareAction(binding: BRegImmediateActionBinding, inputs: any, idempotencyKey: string, conditions?: BRegActionTargetConditions | undefined | null): BRegPreparedAction
+  /**
+   * Revalidate saved invocation evidence against freshly selected authority
+   * and the caller's original inputs and key. The saved target conditions
+   * are reused exactly; this never fetches conditions or sends a request.
+   */
+  recoverAction(binding: BRegImmediateActionBinding, prepared: BRegPreparedAction, inputs: any, idempotencyKey: string): BRegRecoveredAction
+  /**
+   * Explicitly send a recovered invocation under its original key. An
+   * invocation whose outcome is unknown is resent identically under that
+   * key, at most `maxMutationRetries` times.
+   */
+  executeRecoveredAction(binding: BRegImmediateActionBinding, recovered: BRegRecoveredAction): Promise<CompleteOutcome>
   createRecord(binding: BRegCreateBinding, data: any, idempotencyKey: string, formatValue?: string | undefined | null): Promise<CompleteOutcome>
   /** Prepare inert Create evidence before any token acquisition or I/O. */
   prepareCreate(binding: BRegCreateBinding, data: any, idempotencyKey: string, formatValue?: string | undefined | null): BRegPreparedCreate
@@ -47,7 +68,11 @@ export declare class BaseRegistryClient {
   /** Explicitly send a recovered Create request with fresh authority. */
   executeRecoveredCreate(binding: BRegCreateBinding, recovered: BRegRecoveredCreate): Promise<CompleteOutcome>
   patchRecord(binding: BRegPatchBinding, recordIdentifier: string, etag: string, operations: any, idempotencyKey: string, formatValue?: string | undefined | null): Promise<CompleteOutcome>
-  /** Execute one metadata-selected atomic batch without automatic retry. */
+  /**
+   * Execute one metadata-selected atomic batch. A batch whose outcome is
+   * unknown is resent identically under the same key, at most
+   * `maxMutationRetries` times.
+   */
   batchRecords(binding: BRegBatchBinding, request: any, idempotencyKey: string): Promise<CompleteOutcome>
   /**
    * Announce one whole input and open a durable ingestion run for it. The
@@ -116,6 +141,12 @@ export declare class BaseRegistryClient {
   actionTargetConditionsJson(binding: BRegImmediateActionBinding, inputsJson: string): Promise<BRegActionTargetConditions>
   /** Invoke an action from exact JSON and preserve exact receipt values. */
   invokeActionJson(binding: BRegImmediateActionBinding, inputsJson: string, idempotencyKey: string, conditions?: BRegActionTargetConditions | undefined | null): Promise<JsonOutcome>
+  /** Prepare inert invocation evidence from exact action-input JSON. */
+  prepareActionJson(binding: BRegImmediateActionBinding, inputsJson: string, idempotencyKey: string, conditions?: BRegActionTargetConditions | undefined | null): BRegPreparedAction
+  /** Revalidate saved invocation evidence against exact original input JSON. */
+  recoverActionJson(binding: BRegImmediateActionBinding, prepared: BRegPreparedAction, inputsJson: string, idempotencyKey: string): BRegRecoveredAction
+  /** Explicitly send a recovered invocation and preserve exact receipt values. */
+  executeRecoveredActionJson(binding: BRegImmediateActionBinding, recovered: BRegRecoveredAction): Promise<JsonOutcome>
   createRecordJson(binding: BRegCreateBinding, dataJson: string, idempotencyKey: string, formatValue?: string | undefined | null): Promise<JsonOutcome>
   /** Prepare inert Create evidence from exact JSON text. */
   prepareCreateJson(binding: BRegCreateBinding, dataJson: string, idempotencyKey: string, formatValue?: string | undefined | null): BRegPreparedCreate
@@ -231,6 +262,8 @@ export declare class BRegMetadata {
   get immediateActions(): any
   /** Original caller-filtered action metadata as exact JSON text. */
   get actionsJson(): string | null
+  /** Validated caller-filtered statistical dataset descriptions, without entity authority. */
+  get statisticalDatasets(): any | null
   /** Descriptive change-request capability for one entity, when advertised. */
   changeRequestCapability(entityIdentifier: string): any | null
   get registryIdentifier(): string
@@ -251,6 +284,19 @@ export type Metadata = BRegMetadata
 export declare class BRegPatchBinding {}
 export type PatchBinding = BRegPatchBinding
 
+/**
+ * Inert original immediate-action invocation evidence. The bytes carry the
+ * inputs, saved target conditions, and idempotency key, but no token or
+ * executable metadata authority.
+ */
+export declare class BRegPreparedAction {
+  /** Restore bounded inert evidence previously returned by `toBytes`. */
+  static fromBytes(bytes: Buffer): BRegPreparedAction
+  /** Copy the exact evidence bytes for owner-protected persistence. */
+  toBytes(): Buffer
+}
+export type PreparedAction = BRegPreparedAction
+
 /**
  * Inert original Create request evidence. The bytes carry values and an
  * idempotency key, but no token or executable metadata authority.
@@ -275,6 +321,14 @@ export declare class BRegPreparedLifecycle {
 }
 export type PreparedLifecycle = BRegPreparedLifecycle
 
+/**
+ * A recovered immediate-action invocation and key. This remains inert until
+ * `executeRecoveredAction` is explicitly called with freshly selected
+ * authority.
+ */
+export declare class BRegRecoveredAction {}
+export type RecoveredAction = BRegRecoveredAction
+
 /**
  * A recovered Create request, key, and representation. This remains inert
  * until `executeRecoveredCreate` is explicitly called with fresh authority.