@registrystack/client 0.43.0 → 0.45.0

package/README.md

@@ -1,7 +1,12 @@
 # @registrystack/client
 
 One versioned Node.js package for the Discovery, Evidence, Base Registry
-Engine, Casework, Messaging, and Scheduling client APIs in Registry Stack.
+Engine, Casework, Messaging, Scheduling, and Coordinator client APIs in Registry Stack.
+
+Coordinator joins the client roster at v0.44.0. Its imports below require a
+Coordinator-enabled v0.44.0 candidate or published package; published v0.43.0
+contains the earlier six products. Check the version-specific release assets
+before installing. Source integration does not establish publication.
 
 ## Install
 
@@ -11,13 +16,13 @@ npm install "@registrystack/client@<version>"
 
 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 six native
+one platform-specific optional dependency containing all seven native
 bindings.
 
 ## Usage
 
 ```js
-const { discovery, evidence, breg, casework, messaging, scheduling } = require('@registrystack/client');
+const { discovery, evidence, breg, casework, messaging, scheduling, coordinator } = require('@registrystack/client');
 
 const registry = new breg.BaseRegistryClient({
   baseUrl: 'https://registry.example.invalid/',
@@ -31,6 +36,9 @@ const messages = new messaging.MessagingClient({
 const appointments = new scheduling.SchedulingClient({
   baseUrl: 'https://scheduling.example.invalid/',
 });
+const workflows = new coordinator.CoordinatorClient({
+  baseUrl: 'https://coordinator.example.invalid/',
+});
 ```
 
 ## Products
@@ -48,9 +56,22 @@ const appointments = new scheduling.SchedulingClient({
 - `scheduling`: Registry Scheduling, published offerings, availability,
   holds, and appointments over operator-anchored supply.
 
+- `coordinator`: Registry Coordinator, workflow contracts, admission, run status,
+  inspection, and operator recovery. It is optional for direct product composition.
+
 Each product remains in its own namespace because its routing,
 authentication, errors, and verification rules are different.
 
+## Compatibility metadata
+
+The package includes the tested server baseline and compatible patch line for
+the Discovery namespace. Read the version-matched record through the exported
+JSON path:
+
+```js
+const compatibility = require('@registrystack/client/compatibility.json');
+```
+
 ## TypeScript
 
 A TypeScript consumer also needs the Node type definitions, and must name
@@ -90,7 +111,7 @@ 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
+`maximumMutationRetries` times, a client option: 0 to 2, default 2, and 0 sends it
 once. Casework review-request create and cancel are excluded from this retry.
 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
@@ -100,12 +121,12 @@ 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
+`breg.verifyHookDelivery({ method, path, headers, body, key })` authenticates
+the exact bytes of one Version 1 hook delivery. The result returns
 `deliveryTime` and `idempotencyKey`; the receiver must bound clock skew and
 deduplicate once-only effects on authenticated `source` plus `id`, or on an
 application business key. See
-[Verify a webhook delivery](https://docs.registrystack.org/reference/client-api/#verify-a-webhook-delivery)
+[Verify a hook delivery](https://docs.registrystack.org/reference/client-api/#verify-a-hook-delivery)
 for a receiver example.
 
 ## Versioning
@@ -163,3 +184,12 @@ without the cursor after `410 review.result-expired`.
 ## License
 
 Apache-2.0
+
+Coordinator joins the seven-product roster at v0.44.0. The source facade also
+contains held `render` and `@registrystack/client/render` namespaces. Default
+assembly omits Render; `--include-render` adds it to an explicit local candidate
+and does not authorize publication. Render takes a token or a resource-bound provider with
+`bearerToken()` and performs one bounded render exchange. A correlation key is
+not a durable idempotency promise. `outcomeUnknown` and `transportKind` preserve
+whether an exchange may have completed; provider errors keep their own class.
+Coordinator is optional.

package/breg/client.d.ts

@@ -7,7 +7,7 @@ export type JsonObject = { readonly [key: string]: JsonValue }
 /** An integer that satisfies `Number.isSafeInteger` and the option's documented bounds. */
 export type SafeInteger = number
 
-export type WebhookVerificationRefusalCode =
+export type HookVerificationRefusalCode =
   | 'missing-header'
   | 'invalid-delivery-time'
   | 'duplicate-header'
@@ -17,7 +17,7 @@ export type WebhookVerificationRefusalCode =
   | 'signature-mismatch'
   | 'unsupported-version'
 
-export interface WebhookDeliveryInput {
+export interface HookDeliveryInput {
   method: string
   path: string
   headers: Readonly<Record<string, string>>
@@ -27,7 +27,7 @@ export interface WebhookDeliveryInput {
   key: Buffer
 }
 
-export interface VerifiedWebhookDelivery {
+export interface VerifiedHookDelivery {
   readonly id: string
   readonly source: string
   readonly type: string
@@ -41,10 +41,21 @@ export interface VerifiedWebhookDelivery {
 }
 
 /**
- * Authenticate one exact Base Registry Engine Version 1 webhook delivery.
+ * Authenticate one exact Base Registry Engine Version 1 hook delivery.
  * Apply delivery-time skew and idempotency policy before acting on the body.
  */
-export declare function verifyWebhookDelivery(input: WebhookDeliveryInput): VerifiedWebhookDelivery
+export declare function verifyHookDelivery(input: HookDeliveryInput): VerifiedHookDelivery
+
+/**
+ * Project one record revision into the event record view. `argumentsJson` is a
+ * JSON object with `registryRevision`, `recordType`, `descriptor`, `record`
+ * and optional `creationRevision`, `actionReceipts` and
+ * `proposalApplications`. The result is the view document as JSON text.
+ * Failures carry kind `event-record` and one of the codes `not-an-event-record`,
+ * `unsupported-version`, `malformed-descriptor`, `wrong-record-evidence`,
+ * `revision-mismatch`, `incompatible-metadata` or `invalid-input`.
+ */
+export declare function eventRecordView(argumentsJson: string): string
 
 export interface PrivateJwk {
   readonly kty: string
@@ -62,24 +73,24 @@ export interface PrivateKeyJwtConfig {
    * authentication). Defaults to the token endpoint URL. This is not the
    * `resource` of the token request.
    */
-  audience?: string | null
+  audience?: string
   /**
    * The RFC 8707 resource indicator the token is requested for: the resource
    * server's registered identifier, not a URL to fetch.
    */
-  resource?: string | null
+  resource?: string
   /**
    * The scopes requested for the token, sent as one space-delimited `scope`
    * parameter. A requested scope may narrow the client's registered
    * permission set; it can never widen it.
    */
-  scopes?: ReadonlyArray<string> | null
-  assertionLifetimeSeconds?: SafeInteger | null
-  refreshMarginSeconds?: SafeInteger | null
-  requestTimeoutMilliseconds?: SafeInteger | null
-  connectTimeoutMilliseconds?: SafeInteger | null
-  userAgent?: string | null
-  trustedRootCertificates?: string | null
+  scopes?: ReadonlyArray<string>
+  assertionLifetimeSeconds?: SafeInteger
+  refreshMarginSeconds?: SafeInteger
+  attemptTimeoutMilliseconds?: SafeInteger
+  connectTimeoutMilliseconds?: SafeInteger
+  userAgent?: string
+  trustedRootCertificates?: string
 }
 
 /** OAuth credentials are returned to the caller. Keep them out of logs and persistence. */
@@ -98,7 +109,7 @@ export interface ExchangeContext {
   audience: string
   generation: string
   deadlineSeconds: SafeInteger
-  grantId?: string | null
+  grantId?: string
 }
 
 export type ExchangePrivateKeyJwtConfig = PrivateKeyJwtConfig & {
@@ -118,10 +129,10 @@ export interface RemoteExchangeSource {
   bootstrap: ExchangePrivateKeyJwtConfig
   bootstrapResource: string
   bootstrapScope: string
-  requestTimeoutMilliseconds?: SafeInteger | null
-  connectTimeoutMilliseconds?: SafeInteger | null
-  userAgent?: string | null
-  trustedRootCertificates?: string | null
+  attemptTimeoutMilliseconds?: SafeInteger
+  connectTimeoutMilliseconds?: SafeInteger
+  userAgent?: string
+  trustedRootCertificates?: string
 }
 
 export type ExchangeAuthorizationConfig =
@@ -135,12 +146,12 @@ export type BaseRegistryAuthorization =
 
 export interface BaseRegistryClientConfig {
   baseUrl: string
-  authorization?: BaseRegistryAuthorization | null
-  requestTimeoutMilliseconds?: SafeInteger | null
-  connectTimeoutMilliseconds?: SafeInteger | null
-  maxResponseBytes?: SafeInteger | null
-  userAgent?: string | null
-  trustedRootCertificates?: string | null
+  authorization?: BaseRegistryAuthorization
+  attemptTimeoutMilliseconds?: SafeInteger
+  connectTimeoutMilliseconds?: SafeInteger
+  maximumResponseBytes?: SafeInteger
+  userAgent?: string
+  trustedRootCertificates?: string
   /**
    * How many times a keyed mutation (create, patch, attachment upload or
    * delete, lifecycle action, immediate action, batch, tombstone, statistics
@@ -149,7 +160,7 @@ export interface BaseRegistryClientConfig {
    * number from 0 to 2, default 2; 0 sends it once. Any other value is a
    * `configuration` error.
    */
-  maxMutationRetries?: SafeInteger | null
+  maximumMutationRetries?: SafeInteger
 }
 
 export type RecordFormat = 'json' | 'json-ld'
@@ -227,7 +238,7 @@ export interface ListContinuation {
   accessProfile?: string | null
   registryIdentifier: string
   datasetIdentifier: string
-  entityTypeIdentifier: string
+  recordTypeIdentifier: string
 }
 export type CurrentListContinuation = ListContinuation
 export interface AsOfListContinuation extends ListContinuation { asOf: string }
@@ -255,7 +266,7 @@ export interface RegistryRecord {
 export interface RecordMetadata {
   registryIdentifier: string
   datasetIdentifier: string
-  entityTypeIdentifier: string
+  recordTypeIdentifier: string
   readonly [member: string]: JsonValue | undefined
 }
 
@@ -473,6 +484,7 @@ export interface BRegProposalActionDescriptor {
   readonly accessProfile: string
   readonly operations: ReadonlyArray<string>
   readonly readableInputs: ReadonlyArray<string>
+  readonly readableContextFields: ReadonlyArray<string>
 }
 
 export interface BRegActionAttachmentDescriptor {
@@ -536,7 +548,7 @@ export interface BRegActionReceipt {
 
 export type BRegActionAvailability =
   | { readonly available: true; readonly observedRevision: number }
-  | { readonly available: false; readonly observedRevision: number; readonly reason: 'guard-not-satisfied'; readonly recovery: 'none' }
+  | { readonly available: false; readonly observedRevision: number; readonly reason: 'guard-not-satisfied'; readonly guardReason?: string; readonly recovery: 'none' }
   | { readonly available: null; readonly observedRevision: number; readonly reason: 'input-required'; readonly recovery: 'correct-input'; readonly missingInputs: ReadonlyArray<string> }
   | { readonly available: null; readonly observedRevision: null; readonly reason: 'not-disclosed'; readonly recovery: 'none' }
 
@@ -547,8 +559,8 @@ export interface BRegBatchCreateItem {
 export interface BRegBatchPatchItem {
   readonly operation: 'patch'
   readonly recordIdentifier: string
-  readonly etag: string
-  readonly operations: ReadonlyArray<PatchOperation | RemovePatchOperation>
+  readonly ifMatch: string
+  readonly patch: ReadonlyArray<PatchOperation | RemovePatchOperation>
 }
 export type BRegBatchItem = BRegBatchCreateItem | BRegBatchPatchItem
 export type BRegChangeContext =
@@ -571,10 +583,10 @@ export interface BRegBatchReceipt {
   readonly snapshot: string
   readonly results: ReadonlyArray<{
     readonly operation: 'create' | 'patch'
-    readonly id: string
-    readonly revision: SafeInteger
+    readonly recordIdentifier: string
+    readonly revisionIdentifier: string
     readonly etag: string
-    readonly data: Readonly<Record<string, JsonValue>>
+    readonly domainData: Readonly<Record<string, JsonValue>>
   }>
 }
 
@@ -795,6 +807,8 @@ export declare class BRegMetadata {
   selectAction(actionIdentifier: string, expectedProfile: string): BRegActionBinding
   selectTombstone(recordTypeIdentifier: string, expectedProfile: string): BRegTombstoneBinding
   selectBatch(recordTypeIdentifier: string, expectedProfile: string): BRegBatchBinding
+  /** The event record descriptor declared for a record type, as JSON text. */
+  eventRecordDescriptor(recordType: string): string
 }
 
 /** Bounded declared identifiers; absent when any referenced field is unreadable. */
@@ -815,6 +829,7 @@ export interface BaseRegistryClientFailure extends Error {
   readonly code?: string
   readonly refusalCode?: string
   readonly reasonCode?: string
+  readonly guardReason?: string
   readonly fieldPath?: string
   readonly constraint?: BRegConstraintViolation
   readonly status?: number
@@ -842,6 +857,7 @@ export declare class BaseRegistryClientError extends Error implements BaseRegist
   readonly code?: string
   readonly refusalCode?: string
   readonly reasonCode?: string
+  readonly guardReason?: string
   readonly fieldPath?: string
   readonly constraint?: BRegConstraintViolation
   readonly status?: number
@@ -865,13 +881,24 @@ export declare class BaseRegistryClientError extends Error implements BaseRegist
 }
 
 export declare class BaseRegistryClient {
-  startProposal(binding: BRegActionBinding, inputsJson: string, key: string): Promise<BRegProposal>
+  startProposal(binding: BRegActionBinding, inputs: JsonObject, key: string): Promise<BRegProposal>
   getProposal(binding: BRegProposalGetBinding, id: string): Promise<BRegProposal>
   readProposal(proposal: BRegProposal): Promise<BRegProposal>
   /** Read one retained submission version under the access profile of the Proposal's self link. */
   readProposalSubmission(proposal: BRegProposal, version: number): Promise<CompleteOutcome<BRegProposalSubmission>>
-  listProposals(collection: BRegProposalCollection, queryJson: string): Promise<BRegProposalPage>
-  prepareProposal(proposal: BRegProposal, operation: BRegProposalTransition, bodyJson: string, key: string): BRegPreparedProposal
+  listProposals(collection: BRegProposalCollection, query: JsonObject): Promise<BRegProposalPage>
+  /** Exact JSON query; retains the metadata-selected collection and bounded pagination. */
+  listProposalsJson(collection: BRegProposalCollection, queryJson: string): Promise<BRegProposalPage>
+  /**
+   * Bind an available transition without I/O. Throws locally when the operation
+   * is not a legal transition from the Proposal's observed state; `cancel` is
+   * prepared only for a Draft or Submitted Proposal, so cancelling an Applied or
+   * Cancelled Proposal never reaches the server. Call the HTTP route directly to
+   * exercise the server's terminal-state refusal.
+   */
+  prepareProposal(proposal: BRegProposal, operation: BRegProposalTransition, body: JsonObject, key: string): BRegPreparedProposal
+  /** Exact JSON body; preserves integer values and the same lifecycle authority and recovery contract. */
+  prepareProposalJson(proposal: BRegProposal, operation: BRegProposalTransition, bodyJson: string, key: string): BRegPreparedProposal
   recoverProposal(proposal: BRegProposal, attempt: BRegPreparedProposal): BRegPreparedProposal
   executeProposal(attempt: BRegPreparedProposal): Promise<BRegProposal>
   constructor(config: BaseRegistryClientConfig)
@@ -879,6 +906,12 @@ export declare class BaseRegistryClient {
   ready(): Promise<CompleteOutcome<ProbeStatus>>
   openapi(accessProfile?: string | null): Promise<RawOutcome>
   registryMetadata(accessProfile?: string | null): Promise<RawOutcome>
+  /**
+   * The first revision of a record as
+   * `{recordType, recordId, revision, createdAt}` JSON text, or null when the
+   * caller may not read it (403 or 404).
+   */
+  eventRecordCreationRevision(recordRoute: string, recordIdentifier: string, accessProfile?: string | null): Promise<string | null>
   statisticsLive(dataset: string, from?: string | null, to?: string | null, accessProfile?: string | null, format?: StatisticsFormat | null): Promise<RawOutcome>
   statisticsReleases(dataset: string, top?: SafeInteger | null, skipToken?: string | null, accessProfile?: string | null): Promise<RawOutcome>
   statisticsLatestRelease(dataset: string, period: string, selection: StatisticsReleaseSelection, accessProfile?: string | null, format?: StatisticsFormat | null): Promise<RawOutcome>
@@ -887,24 +920,24 @@ export declare class BaseRegistryClient {
   statisticsPublish(dataset: string, period: string, status: StatisticsReleaseStatus, accessProfile: string, idempotencyKey: string): Promise<RawOutcome>
   statisticsWithdraw(dataset: string, period: string, version: SafeInteger, reason: StatisticsWithdrawalReason, accessProfile: string, idempotencyKey: string): Promise<RawOutcome>
   registryContract(accessProfile?: string | null): Promise<BRegMetadata>
-  entitySchema(recordTypeIdentifier: string, accessProfile?: string | null): Promise<RawOutcome>
-  recordRevisions(entityRoute: string, recordIdentifier: string, accessProfile?: string | null): Promise<RawOutcome>
-  getRecordRevision(entityRoute: string, recordIdentifier: string, revision: SafeInteger, options?: RecordProjectionOptions | null): Promise<RawOutcome>
-  getRecord(entityRoute: string, recordIdentifier: string, options?: RecordOptions | null): Promise<CompleteOutcome<RecordEnvelope>>
-  listRecords(entityRoute: string, options?: ListOptions | null): Promise<PageOutcome>
+  recordSchema(recordTypeIdentifier: string, accessProfile?: string | null): Promise<RawOutcome>
+  recordRevisions(recordRoute: string, recordIdentifier: string, accessProfile?: string | null): Promise<RawOutcome>
+  getRecordRevision(recordRoute: string, recordIdentifier: string, revision: SafeInteger, options?: RecordProjectionOptions | null): Promise<RawOutcome>
+  getRecord(recordRoute: string, recordIdentifier: string, options?: RecordOptions | null): Promise<CompleteOutcome<RecordEnvelope>>
+  listRecords(recordRoute: string, options?: ListOptions | null): Promise<PageOutcome>
   continueList(continuation: ListContinuation): Promise<PageOutcome>
-  getGeoJsonRecord(entityRoute: string, recordIdentifier: string, options?: GeoJsonOptions | null): Promise<CompleteOutcome<GeoJsonFeature>>
-  listGeoJsonRecords(entityRoute: string, options?: GeoJsonListOptions | null): Promise<PageOutcome<GeoJsonFeatureCollection, GeoJsonListContinuation>>
+  getGeoJsonRecord(recordRoute: string, recordIdentifier: string, options?: GeoJsonOptions | null): Promise<CompleteOutcome<GeoJsonFeature>>
+  listGeoJsonRecords(recordRoute: string, options?: GeoJsonListOptions | null): Promise<PageOutcome<GeoJsonFeatureCollection, GeoJsonListContinuation>>
   continueGeoJsonList(continuation: GeoJsonListContinuation): Promise<PageOutcome<GeoJsonFeatureCollection, GeoJsonListContinuation>>
-  listCurrentRecords(entityRoute: string, options?: CollectionOptions | null): Promise<PageOutcome<RecordCollection, CurrentListContinuation>>
+  listCurrentRecords(recordRoute: string, options?: CollectionOptions | null): Promise<PageOutcome<RecordCollection, CurrentListContinuation>>
   continueCurrentList(continuation: CurrentListContinuation): Promise<PageOutcome<RecordCollection, CurrentListContinuation>>
-  listRecordsAsOf(entityRoute: string, options: AsOfListOptions): Promise<PageOutcome<RecordCollection, AsOfListContinuation>>
+  listRecordsAsOf(recordRoute: string, options: AsOfListOptions): Promise<PageOutcome<RecordCollection, AsOfListContinuation>>
   continueAsOfList(continuation: AsOfListContinuation): Promise<PageOutcome<RecordCollection, AsOfListContinuation>>
-  listSnapshotRecords(entityRoute: string, options?: SnapshotListOptions | null): Promise<PageOutcome<RecordCollection, SnapshotListContinuation>>
+  listSnapshotRecords(recordRoute: string, options?: SnapshotListOptions | null): Promise<PageOutcome<RecordCollection, SnapshotListContinuation>>
   continueSnapshotList(continuation: SnapshotListContinuation): Promise<PageOutcome<RecordCollection, SnapshotListContinuation>>
-  listRelationshipRecords(entityRoute: string, recordIdentifier: string, pathRoute: string, options?: CollectionOptions | null): Promise<PageOutcome<RecordCollection, RelationshipListContinuation>>
+  listRelationshipRecords(recordRoute: string, recordIdentifier: string, pathRoute: string, options?: CollectionOptions | null): Promise<PageOutcome<RecordCollection, RelationshipListContinuation>>
   continueRelationshipList(continuation: RelationshipListContinuation): Promise<PageOutcome<RecordCollection, RelationshipListContinuation>>
-  lookupRecord(entityRoute: string, selector: string, values?: JsonObject | null, options?: RecordProjectionOptions | null): Promise<CompleteOutcome<RecordEnvelope>>
+  lookupRecord(recordRoute: string, selector: string, values?: JsonObject | null, options?: RecordProjectionOptions | null): Promise<CompleteOutcome<RecordEnvelope>>
   actionTargetConditions(binding: BRegActionBinding, inputs: JsonObject): Promise<BRegActionTargetConditions>
   actionTargetConditionsJson(binding: BRegActionBinding, inputsJson: string): Promise<BRegActionTargetConditions>
   actionAvailability(binding: BRegActionBinding, targetInput: string, inputs: JsonObject): Promise<CompleteOutcome<BRegActionAvailability>>
@@ -937,36 +970,36 @@ export declare class BaseRegistryClient {
   patchRecord(binding: BRegPatchBinding, recordIdentifier: string, etag: string, operations: ReadonlyArray<PatchOperation | RemovePatchOperation>, idempotencyKey: string, format?: RecordFormat | null): Promise<CompleteOutcome<RecordEnvelope>>
   batchRecords(binding: BRegBatchBinding, request: BRegBatchInput, idempotencyKey: string): Promise<CompleteOutcome<BRegBatchReceipt>>
   batchRecordsJson(binding: BRegBatchBinding, requestJson: string, idempotencyKey: string): Promise<JsonOutcome>
-  createIngestionRun(entityRoute: string, request: BRegIngestionRunInput): Promise<CompleteOutcome<BRegIngestionRun>>
-  listIngestionRuns(entityRoute: string, query?: BRegIngestionRunListInput | null): Promise<CompleteOutcome<BRegIngestionRunPage>>
-  readIngestionRun(entityRoute: string, runId: string, accessProfile?: string | null): Promise<CompleteOutcome<BRegIngestionRun>>
-  submitIngestionChunk(entityRoute: string, runId: string, chunk: BRegIngestionChunk, profileId: string): Promise<CompleteOutcome<BRegIngestionChunkSubmission>>
-  cancelIngestionRun(entityRoute: string, runId: string, accessProfile?: string | null): Promise<CompleteOutcome<BRegIngestionRun>>
-  ingestionChunkReceipt(entityRoute: string, runId: string, chunkIndex: SafeInteger, profileId: string): Promise<CompleteOutcome<BRegIngestionChunkReceipt>>
+  createIngestionRun(recordRoute: string, request: BRegIngestionRunInput): Promise<CompleteOutcome<BRegIngestionRun>>
+  listIngestionRuns(recordRoute: string, query?: BRegIngestionRunListInput | null): Promise<CompleteOutcome<BRegIngestionRunPage>>
+  readIngestionRun(recordRoute: string, runId: string, accessProfile?: string | null): Promise<CompleteOutcome<BRegIngestionRun>>
+  submitIngestionChunk(recordRoute: string, runId: string, chunk: BRegIngestionChunk, profileId: string): Promise<CompleteOutcome<BRegIngestionChunkSubmission>>
+  cancelIngestionRun(recordRoute: string, runId: string, accessProfile?: string | null): Promise<CompleteOutcome<BRegIngestionRun>>
+  ingestionChunkReceipt(recordRoute: string, runId: string, chunkIndex: SafeInteger, profileId: string): Promise<CompleteOutcome<BRegIngestionChunkReceipt>>
   tombstoneRecord(binding: BRegTombstoneBinding, recordIdentifier: string, etag: string, idempotencyKey: string, format?: RecordFormat | null): Promise<CompleteOutcome<RecordEnvelope>>
   tombstoneRecordJson(binding: BRegTombstoneBinding, recordIdentifier: string, etag: string, idempotencyKey: string, format?: RecordFormat | null): Promise<JsonOutcome>
-  getRecordJson(entityRoute: string, recordIdentifier: string, options?: RecordOptions | null): Promise<JsonOutcome>
-  listRecordsJson(entityRoute: string, options?: ListOptions | null): Promise<JsonOutcome>
+  getRecordJson(recordRoute: string, recordIdentifier: string, options?: RecordOptions | null): Promise<JsonOutcome>
+  listRecordsJson(recordRoute: string, options?: ListOptions | null): Promise<JsonOutcome>
   continueListJson(continuation: ListContinuation): Promise<JsonOutcome>
-  getGeoJsonRecordJson(entityRoute: string, recordIdentifier: string, options?: GeoJsonOptions | null): Promise<JsonOutcome>
-  listGeoJsonRecordsJson(entityRoute: string, options?: GeoJsonListOptions | null): Promise<JsonOutcome<GeoJsonListContinuation>>
+  getGeoJsonRecordJson(recordRoute: string, recordIdentifier: string, options?: GeoJsonOptions | null): Promise<JsonOutcome>
+  listGeoJsonRecordsJson(recordRoute: string, options?: GeoJsonListOptions | null): Promise<JsonOutcome<GeoJsonListContinuation>>
   continueGeoJsonListJson(continuation: GeoJsonListContinuation): Promise<JsonOutcome<GeoJsonListContinuation>>
-  listCurrentRecordsJson(entityRoute: string, options?: CollectionOptions | null): Promise<JsonOutcome<CurrentListContinuation>>
+  listCurrentRecordsJson(recordRoute: string, options?: CollectionOptions | null): Promise<JsonOutcome<CurrentListContinuation>>
   continueCurrentListJson(continuation: CurrentListContinuation): Promise<JsonOutcome<CurrentListContinuation>>
-  listRecordsAsOfJson(entityRoute: string, options: AsOfListOptions): Promise<JsonOutcome<AsOfListContinuation>>
+  listRecordsAsOfJson(recordRoute: string, options: AsOfListOptions): Promise<JsonOutcome<AsOfListContinuation>>
   continueAsOfListJson(continuation: AsOfListContinuation): Promise<JsonOutcome<AsOfListContinuation>>
-  listSnapshotRecordsJson(entityRoute: string, options?: SnapshotListOptions | null): Promise<JsonOutcome<SnapshotListContinuation>>
+  listSnapshotRecordsJson(recordRoute: string, options?: SnapshotListOptions | null): Promise<JsonOutcome<SnapshotListContinuation>>
   continueSnapshotListJson(continuation: SnapshotListContinuation): Promise<JsonOutcome<SnapshotListContinuation>>
-  listRelationshipRecordsJson(entityRoute: string, recordIdentifier: string, pathRoute: string, options?: CollectionOptions | null): Promise<JsonOutcome<RelationshipListContinuation>>
+  listRelationshipRecordsJson(recordRoute: string, recordIdentifier: string, pathRoute: string, options?: CollectionOptions | null): Promise<JsonOutcome<RelationshipListContinuation>>
   continueRelationshipListJson(continuation: RelationshipListContinuation): Promise<JsonOutcome<RelationshipListContinuation>>
-  lookupRecordJson(entityRoute: string, selector: string, valuesJson?: string | null, options?: RecordProjectionOptions | null): Promise<JsonOutcome>
+  lookupRecordJson(recordRoute: string, selector: string, valuesJson?: string | null, options?: RecordProjectionOptions | null): Promise<JsonOutcome>
   createRecordJson(binding: BRegCreateBinding, dataJson: string, idempotencyKey: string, format?: RecordFormat | null): Promise<JsonOutcome>
   patchRecordJson(binding: BRegPatchBinding, recordIdentifier: string, etag: string, operationsJson: string, idempotencyKey: string, format?: RecordFormat | null): Promise<JsonOutcome>
 }
 
 export type BRegProposalTransition = 'edit' | 'submit' | 'revise' | 'rebase' | 'retry' | 'cancel' | 'apply'
-export type BRegAvailabilityReason = 'pending-review' | 'review-rejected' | 'review-changes-requested' | 'review-ended' | 'stale-revision' | 'contract-changed' | 'dependency-outage' | 'invalid-input' | 'already-applied'
-export type BRegRecoveryHint = 'refresh' | 'revise' | 'retry' | 'correct-input' | 'receipt-only'
+export type BRegAvailabilityReason = 'pending-review' | 'review-rejected' | 'review-changes-requested' | 'review-ended' | 'stale-revision' | 'package-changed' | 'dependency-outage' | 'invalid-input' | 'already-applied'
+export type BRegRecoveryHint = 'refresh' | 'revise' | 'retry' | 'rebase' | 'correct-input' | 'receipt-only'
 export type BRegAvailability =
   | { readonly available: true; readonly observedRevision: number }
   | { readonly available: false; readonly observedRevision: number; readonly reason: BRegAvailabilityReason; readonly recovery: BRegRecoveryHint }
@@ -985,8 +1018,8 @@ export interface BRegProposalApplication {
 export interface BRegProposalApplicationStatus {
   readonly state: 'awaiting-review' | 'pending' | 'applying' | 'blocked' | 'applied' | 'cancelled' | 'rejected'
   readonly mode: 'automatic' | 'manual'
-  readonly reason?: 'contract-changed' | 'dependency-outage' | 'lease-expired' | 'application-refused' | 'attempts-exhausted'
-  readonly recovery?: 'retry' | 'correct-input'
+  readonly reason?: 'package-changed' | 'dependency-outage' | 'lease-expired' | 'application-refused' | 'attempts-exhausted'
+  readonly recovery?: 'retry' | 'rebase' | 'correct-input'
   readonly automaticRetry?: {readonly scheduled: boolean; readonly attempts: number; readonly maximumAttempts: number}
 }
 export interface BRegProposalReviewDocument {
@@ -995,6 +1028,8 @@ export interface BRegProposalReviewDocument {
   readonly subject: {readonly source: string; readonly subjectType: 'proposal'; readonly id: string; readonly version: string; readonly digest: string}
   readonly context: {readonly reference: string; readonly contract?: {readonly id: string; readonly revision: string; readonly schemaDigest: string}; readonly fields?: Readonly<Record<string, JsonValue>>}
   readonly requestId?: string
+  /** Status reads only: where the submission stands with the Review provider. `reason` is present exactly when `state` is `failed`. */
+  readonly handoff?: {readonly state: 'pending' | 'accepted' | 'failed' | 'withdrawn'; readonly reason?: 'remote-refused' | 'producer-identity-mismatch' | 'review-acceptance-changed' | 'review-policy-changed' | 'submission-recovery-expired' | 'operator-closed' | 'unspecified'}
   readonly authority?: string; readonly policy?: {readonly id: string; readonly version: string; readonly digest: string}
   readonly result?: {readonly state: 'pending' | 'approved' | 'rejected' | 'changes-requested' | 'answered' | 'cancelled' | 'superseded' | 'expired'; readonly resultId?: string; readonly completedAt?: string; readonly availableUntil?: string}
 }
@@ -1002,13 +1037,16 @@ export interface BRegProposalReviewDocument {
 export type BRegProposalTurn = 'party' | 'official' | 'nobody'
 /** The review decision on one submission. The public reason is the only reviewer text BReg serves. */
 export interface BRegProposalDecision { readonly status: 'approved' | 'rejected' | 'changes-requested' | 'answered'; readonly decidedAt: string; readonly publicReason?: string }
+/** Why the review authority refused to take a submission. BReg names only these codes and never the authority's own text. */
+export interface BRegProposalHandoffRefusal { readonly code: 'review.initiator-required' | 'review.initiator-excluded' | 'review.policy-mismatch' | 'review.refused' }
 export interface BRegProposalSubmission {
   readonly id: string; readonly actionId: string; readonly submissionVersion: number; readonly current: boolean; readonly effectDigest: string
   readonly review: NonNullable<BRegProposalReviewDocument['result']> | null
   readonly application: (Omit<BRegProposalApplicationStatus, 'mode'> & {readonly mode?: BRegProposalApplicationStatus['mode']; readonly applicationId?: string; readonly appliedBy?: string; readonly appliedAt?: string}) | null
   readonly decision?: BRegProposalDecision
+  readonly handoffRefusal?: BRegProposalHandoffRefusal
 }
-export interface BRegProposalDocument { readonly id: string; readonly actionId: string; readonly actionRevision: string; readonly submissionVersion: number; readonly revision: number; readonly state: 'draft' | 'submitted' | 'cancelled' | 'applied' | 'rejected'; readonly turn?: BRegProposalTurn; readonly decision?: BRegProposalDecision; readonly title?: string; readonly input?: JsonObject; readonly blockedReason?: 'package-changed'; readonly effectDigest?: string; readonly application?: BRegProposalApplication; readonly applicationStatus?: BRegProposalApplicationStatus; readonly links: Readonly<Partial<Record<BRegProposalTransition | 'self' | 'reviewContext' | 'reviewStatus', BRegProposalLink>>>; readonly attachments?: Readonly<Record<string, BRegProposalAttachment>> }
+export interface BRegProposalDocument { readonly id: string; readonly actionId: string; readonly actionRevision: string; readonly submissionVersion: number; readonly revision: number; readonly state: 'draft' | 'submitted' | 'cancelled' | 'applied' | 'rejected'; readonly createdAt?: string; readonly turn?: BRegProposalTurn; readonly decision?: BRegProposalDecision; readonly handoffRefusal?: BRegProposalHandoffRefusal; readonly title?: string; readonly input?: JsonObject; readonly blockedReason?: 'package-changed'; readonly effectDigest?: string; readonly application?: BRegProposalApplication; readonly applicationStatus?: BRegProposalApplicationStatus; readonly links: Readonly<Partial<Record<BRegProposalTransition | 'self' | 'reviewContext' | 'reviewStatus', BRegProposalLink>>>; readonly attachments?: Readonly<Record<string, BRegProposalAttachment>> }
 export declare class BRegProposal { private constructor(); private readonly __opaque: void; readonly identifier: string; readonly actionIdentifier: string; readonly documentJson: string; readonly inputJson?: string | null }
 export declare class BRegProposalGetBinding { private constructor(); private readonly __opaque: void }
 export declare class BRegProposalReviewBinding { private constructor(); private readonly __opaque: void }

package/breg/client.js

@@ -16,7 +16,7 @@ class BaseRegistryClientError extends Error {
     for (const field of ['code', 'refusalCode', 'reasonCode', 'status', 'traceId', 'transportKind', 'tokenKind']) {
       if (envelope[field] !== undefined && envelope[field] !== null) this[field] = envelope[field];
     }
-    for (const field of ['fieldPath', 'constraint']) {
+    for (const field of ['fieldPath', 'constraint', 'guardReason']) {
       if (envelope[field] !== undefined && envelope[field] !== null) {
         Object.defineProperty(this, field, {
           value: envelope[field],
@@ -82,7 +82,7 @@ function plainDataObject(value, expectedFields) {
   return result;
 }
 
-function webhookHeaders(value) {
+function hookHeaders(value) {
   if (value === null || typeof value !== 'object' || Array.isArray(value) || isProxy(value)) {
     throw inputError('invalid-request');
   }
@@ -102,7 +102,7 @@ function webhookHeaders(value) {
   return result;
 }
 
-function verifyWebhookDelivery(value) {
+function verifyHookDelivery(value) {
   try {
     const input = plainDataObject(value, ['method', 'path', 'headers', 'body', 'key']);
     if (typeof input.method !== 'string' || typeof input.path !== 'string'
@@ -110,10 +110,19 @@ function verifyWebhookDelivery(value) {
       || isSharedArrayBuffer(input.body.buffer) || isSharedArrayBuffer(input.key.buffer)) {
       throw inputError('invalid-request');
     }
-    input.headers = webhookHeaders(input.headers);
+    input.headers = hookHeaders(input.headers);
     input.body = Buffer.from(input.body);
     input.key = Buffer.from(input.key);
-    return native.verifyWebhookDelivery(input);
+    return native.verifyHookDelivery(input);
+  } catch (error) {
+    throw normalize(error, 'invalid-request');
+  }
+}
+
+function eventRecordView(argumentsJson) {
+  try {
+    if (typeof argumentsJson !== 'string') throw inputError('invalid-request');
+    return native.eventRecordView(argumentsJson);
   } catch (error) {
     throw normalize(error, 'invalid-request');
   }
@@ -207,11 +216,11 @@ function wrapAsync(name, jsonIndexes = [], requiredIndexes = []) {
 }
 
 for (const [method, jsonIndexes, requiredIndexes] of [
-  ['health'], ['ready'], ['openapi'], ['registryMetadata'], ['registryContract'], ['entitySchema'],
+  ['health'], ['ready'], ['openapi'], ['registryMetadata'], ['registryContract'], ['recordSchema'],
   ['statisticsLive'], ['statisticsReleases'], ['statisticsLatestRelease'],
   ['statisticsReleaseVersion'], ['statisticsReleaseSeries'], ['statisticsPublish'],
   ['statisticsWithdraw'],
-  ['recordRevisions'], ['getRecordRevision', [3]],
+  ['recordRevisions'], ['getRecordRevision', [3]], ['eventRecordCreationRevision'],
   ['getRecord', [2]], ['listRecords', [1]], ['continueList', [0], [0]],
   ['getGeoJsonRecord', [2]], ['listGeoJsonRecords', [1]], ['continueGeoJsonList', [0], [0]],
   ['listCurrentRecords', [1]], ['continueCurrentList', [0], [0]],
@@ -223,7 +232,7 @@ for (const [method, jsonIndexes, requiredIndexes] of [
   ['invokeAction', [1], [1]],
   ['executeRecoveredAction'], ['executeRecoveredProposalStart'], ['executeRecoveredCreate'],
   ['patchRecord', [3], [3]], ['batchRecords', [1], [1]], ['tombstoneRecord'],
-  ['startProposal'], ['readProposal'], ['readProposalSubmission'], ['getProposal'], ['listProposals'], ['executeProposal'],
+  ['startProposal', [1], [1]], ['readProposal'], ['readProposalSubmission'], ['getProposal'], ['listProposals', [1], [1]], ['executeProposal'], ['listProposalsJson'],
   ['downloadProposalAttachment'], ['uploadProposalAttachment'], ['deleteProposalAttachment'],
   ['readProposalReviewStatus'], ['readProposalReviewContext'],
   ['readProposalReviewContextBatch', [1], [1]],
@@ -247,7 +256,7 @@ for (const [method, jsonIndexes, requiredIndexes] of [
   ['prepareAction', [1], [1]], ['prepareActionJson'],
   ['recoverAction', [2], [2]], ['recoverActionJson'],
   ['prepareCreate', [1], [1]], ['prepareCreateJson'], ['recoverCreate'],
-  ['prepareProposal'], ['recoverProposal'],
+  ['prepareProposal', [2], [2]], ['prepareProposalJson'], ['recoverProposal'],
 ]) {
   const original = native.BaseRegistryClient.prototype[method];
   native.BaseRegistryClient.prototype[method] = function (...args) {
@@ -298,7 +307,7 @@ const BRegPreparedProposal = preparedClass(native.BRegPreparedProposal, 'BRegPre
 for (const name of [
   'selectCreate', 'selectPatch',
   'selectAction', 'selectTombstone', 'selectBatch', 'selectProposals', 'selectProposalGet',
-  'selectProposalReviewContext', 'selectProposalReviewStatus',
+  'selectProposalReviewContext', 'selectProposalReviewStatus', 'eventRecordDescriptor',
 ]) {
   const original = native.BRegMetadata.prototype[name];
   native.BRegMetadata.prototype[name] = function (...args) {
@@ -373,7 +382,8 @@ class PrivateKeyJwt {
 }
 
 module.exports = {
-  verifyWebhookDelivery,
+  verifyHookDelivery,
+  eventRecordView,
   PrivateKeyJwt,
   BaseRegistryClient,
   BaseRegistryClientError,