@interop/was-client 0.48.1 → 0.50.0

package/README.md

@@ -840,7 +840,17 @@ plugs into:
   itself never touches keys. A rejected precondition throws
   `WasSyncConflictError` (412); a delete of an already-gone resource throws
   `WasSyncNotFoundError` (404) -- both catchable subtypes of the core
-  `PreconditionFailedError` / `NotFoundError`.
+  `PreconditionFailedError` / `NotFoundError`. Every other failure arrives as
+  the typed `WasError` subclass for its status, carrying the server's
+  `problem+json` fields.
+- **`isSyncConflictError` / `isSyncNotFoundError` / `isSyncAuthError` /
+  `isUnknownEpochError`** classify those signals by `err.name`. Use them rather
+  than `instanceof`: the port and the `DocCipher` are seams your app injects,
+  and a tree that resolves two copies of this package makes an `instanceof`
+  check quietly false. Read what you need off the matched value, such as
+  `err.status` on an auth error to tell a 401 from the masked 404.
+- **`SyncStatus`** (`'idle' | 'syncing' | 'synced' | 'error'`) is the closed
+  vocabulary a replication driver reports one feed's state through.
 - **`DocCipher`** is the per-collection encrypt/decrypt seam sitting above the
   port: it turns a JSON document into its stored body (minting the resource id)
   and back. `createPlaintextDocCipher(...)` is the crypto-free identity
@@ -869,7 +879,7 @@ import {
   createPlaintextDocCipher,
   deriveSpaceId,
   ensureSpaceAndCollection,
-  WasSyncConflictError
+  isSyncConflictError
 } from '@interop/was-client/sync'
 
 const spaceId = deriveSpaceId(controllerDid) // same Space on every device
@@ -889,7 +899,7 @@ const { id, envelope } = await cipher.encrypt({ data: { note: 'hello' } })
 try {
   await port.putContent({ id, data: envelope, ifNoneMatch: true })
 } catch (err) {
-  if (!(err instanceof WasSyncConflictError)) {
+  if (!isSyncConflictError(err)) {
     throw err
   }
   // 412 on a content-addressed insert: another replica already wrote this

package/dist/sync/index.d.ts

@@ -16,25 +16,36 @@
  * - `ensureSpaceAndCollection` / `ensureSpace` -- idempotent Space +
  *   Collection provisioning, and its Space half alone (ensure the Space once,
  *   then thread the returned description through every collection).
+ * - `isSyncConflictError` / `isSyncNotFoundError` / `isSyncAuthError` /
+ *   `isUnknownEpochError` -- the classification contract for the signals
+ *   below. A consumer matches by `err.name` and never with `instanceof`,
+ *   because every one of these errors is raised inside a seam the app injects
+ *   (the port, the caller's `DocCipher`) and that seam can resolve to a second
+ *   copy of this package. Reading a property off the matched value, such as
+ *   `status` on an auth error, is the intended shape.
  *
  * The 412 conflict / 404 not-found port signals (`WasSyncConflictError` /
  * `WasSyncNotFoundError`), and the opt-in revoked-access signal
  * (`WasSyncAuthError`, raised only under `mapAuthErrors`), live in the client's
  * typed error hierarchy and are re-exported here for convenience -- as are the
- * two decrypt-routing signals, so a crypto-free sync consumer can
- * `instanceof`-match them without importing the `/edv` entry that throws them:
- * the stale-descriptor signal (`UnknownEpochError`: the envelope's epoch is not
- * on the descriptor at all, so re-read it and rebuild the cipher) and the
- * membership signal (`KeyUnwrapError`: the epoch is on the descriptor but this
- * reader holds no key for it, so a refresh cannot help). `EncryptionError`, the
- * fail-closed umbrella `KeyUnwrapError` falls under, rides along.
+ * two decrypt-routing signals, so a crypto-free sync consumer can classify them
+ * without importing the `/edv` entry that throws them: the stale-descriptor
+ * signal (`UnknownEpochError`: the envelope's epoch is not on the descriptor at
+ * all, so re-read it and rebuild the cipher) and the membership signal
+ * (`KeyUnwrapError`: the epoch is on the descriptor but this reader holds no
+ * key for it, so a refresh cannot help). `EncryptionError`, the fail-closed
+ * umbrella `KeyUnwrapError` falls under, rides along. The classes are exported
+ * for construction and for a caller inside one resolved copy; across a package
+ * boundary the predicates are the contract
+ * (`decisions/0001-cross-package-errors-match-by-name.md`).
  */
-export { createWasSyncPort, KEY_EPOCH_HEADER, formatEtag, parseEtag } from './port.js';
+export { createWasSyncPort, KEY_EPOCH_HEADER, parseEtag } from './port.js';
 export { httpStatus as errorStatus, errorMessage } from '../errors.js';
 export { contentCid, cidFrom, deriveSpaceId } from './cid.js';
 export { isEncryptedEnvelope } from './envelope.js';
 export { createPlaintextDocCipher } from './plaintextCipher.js';
 export { ensureSpace, ensureSpaceAndCollection } from './provisioning.js';
+export { isSyncAuthError, isSyncConflictError, isSyncNotFoundError, isUnknownEpochError } from './predicates.js';
 export { EncryptionError, KeyUnwrapError, UnknownEpochError, WasSyncAuthError, WasSyncConflictError, WasSyncNotFoundError } from '../errors.js';
-export type { Json, SyncCheckpoint, WireDoc, SyncPage, MasterState, WasSyncPort, DocCipher } from './types.js';
+export type { Json, SyncCheckpoint, WireDoc, SyncPage, MasterState, WriteAck, SyncStatus, WasSyncPort, DocCipher } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/sync/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,SAAS,EACV,MAAM,WAAW,CAAA;AAIlB,OAAO,EAAE,UAAU,IAAI,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AACtE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAA;AACzE,OAAO,EACL,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACrB,MAAM,cAAc,CAAA;AAErB,YAAY,EACV,IAAI,EACJ,cAAc,EACd,OAAO,EACP,QAAQ,EACR,WAAW,EACX,WAAW,EACX,SAAS,EACV,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAI1E,OAAO,EAAE,UAAU,IAAI,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AACtE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAA;AACzE,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACrB,MAAM,cAAc,CAAA;AAErB,YAAY,EACV,IAAI,EACJ,cAAc,EACd,OAAO,EACP,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,UAAU,EACV,WAAW,EACX,SAAS,EACV,MAAM,YAAY,CAAA"}

package/dist/sync/index.js

@@ -16,20 +16,30 @@
  * - `ensureSpaceAndCollection` / `ensureSpace` -- idempotent Space +
  *   Collection provisioning, and its Space half alone (ensure the Space once,
  *   then thread the returned description through every collection).
+ * - `isSyncConflictError` / `isSyncNotFoundError` / `isSyncAuthError` /
+ *   `isUnknownEpochError` -- the classification contract for the signals
+ *   below. A consumer matches by `err.name` and never with `instanceof`,
+ *   because every one of these errors is raised inside a seam the app injects
+ *   (the port, the caller's `DocCipher`) and that seam can resolve to a second
+ *   copy of this package. Reading a property off the matched value, such as
+ *   `status` on an auth error, is the intended shape.
  *
  * The 412 conflict / 404 not-found port signals (`WasSyncConflictError` /
  * `WasSyncNotFoundError`), and the opt-in revoked-access signal
  * (`WasSyncAuthError`, raised only under `mapAuthErrors`), live in the client's
  * typed error hierarchy and are re-exported here for convenience -- as are the
- * two decrypt-routing signals, so a crypto-free sync consumer can
- * `instanceof`-match them without importing the `/edv` entry that throws them:
- * the stale-descriptor signal (`UnknownEpochError`: the envelope's epoch is not
- * on the descriptor at all, so re-read it and rebuild the cipher) and the
- * membership signal (`KeyUnwrapError`: the epoch is on the descriptor but this
- * reader holds no key for it, so a refresh cannot help). `EncryptionError`, the
- * fail-closed umbrella `KeyUnwrapError` falls under, rides along.
+ * two decrypt-routing signals, so a crypto-free sync consumer can classify them
+ * without importing the `/edv` entry that throws them: the stale-descriptor
+ * signal (`UnknownEpochError`: the envelope's epoch is not on the descriptor at
+ * all, so re-read it and rebuild the cipher) and the membership signal
+ * (`KeyUnwrapError`: the epoch is on the descriptor but this reader holds no
+ * key for it, so a refresh cannot help). `EncryptionError`, the fail-closed
+ * umbrella `KeyUnwrapError` falls under, rides along. The classes are exported
+ * for construction and for a caller inside one resolved copy; across a package
+ * boundary the predicates are the contract
+ * (`decisions/0001-cross-package-errors-match-by-name.md`).
  */
-export { createWasSyncPort, KEY_EPOCH_HEADER, formatEtag, parseEtag } from './port.js';
+export { createWasSyncPort, KEY_EPOCH_HEADER, parseEtag } from './port.js';
 // The sync subpath's names for the client's own error accessors, so a
 // sync-only consumer reads a raw ky/ezcap failure without importing the core
 // entry.
@@ -38,5 +48,6 @@ export { contentCid, cidFrom, deriveSpaceId } from './cid.js';
 export { isEncryptedEnvelope } from './envelope.js';
 export { createPlaintextDocCipher } from './plaintextCipher.js';
 export { ensureSpace, ensureSpaceAndCollection } from './provisioning.js';
+export { isSyncAuthError, isSyncConflictError, isSyncNotFoundError, isUnknownEpochError } from './predicates.js';
 export { EncryptionError, KeyUnwrapError, UnknownEpochError, WasSyncAuthError, WasSyncConflictError, WasSyncNotFoundError } from '../errors.js';
 //# sourceMappingURL=index.js.map

package/dist/sync/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,SAAS,EACV,MAAM,WAAW,CAAA;AAClB,sEAAsE;AACtE,6EAA6E;AAC7E,SAAS;AACT,OAAO,EAAE,UAAU,IAAI,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AACtE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAA;AACzE,OAAO,EACL,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACrB,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1E,sEAAsE;AACtE,6EAA6E;AAC7E,SAAS;AACT,OAAO,EAAE,UAAU,IAAI,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AACtE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAA;AACzE,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACrB,MAAM,cAAc,CAAA"}

package/dist/sync/port.d.ts

@@ -19,11 +19,21 @@
  * `POST /space/:s/:c/query` (profile `changes`) as a root invocation and, like
  * the raw writes, ships the stored bodies verbatim without decrypting.
  *
- * Conditional writes ride the server's monotonic content `version` (`ETag`),
- * enforced uniformly for plaintext and encrypted resources, so there is no
- * plaintext-vs-encrypted fork. `putContent`/`deleteContent` return the server-
- * acked `version` (parsed from the write's `ETag`, re-read only if the backend
- * sent none), so a caller can record acked revisions immediately.
+ * Conditional writes ride the server's `ETag`: an opaque quoted string
+ * (`"<generation>.<version>"`, a per-record generation marker ahead of the
+ * monotonic content `version` so a hard-deleted-and-recreated id can never
+ * collide with its predecessor's validators), enforced uniformly for
+ * plaintext and encrypted resources, so there is no plaintext-vs-encrypted
+ * fork. `putContent`/`deleteContent` return the server-acked {@link
+ * WriteAck} -- the write's raw `etag` (re-read only if the backend sent
+ * none) plus its `version` parsed out of it -- so a caller can record acked
+ * revisions immediately and echo `etag` back verbatim as a later write's
+ * `ifMatch`.
+ *
+ * Bypassing the codec is not bypassing the error mapper. Every failure caught
+ * here goes through the client's own `mapError` first, so the port's signals
+ * carry the server's `problem+json` fields and a `cause`, and a status the
+ * port has no signal for still leaves this subpath as a typed `WasError`.
  */
 import type { WasClient } from '../WasClient.js';
 import { KEY_EPOCH_HEADER } from '../internal/conditional.js';
@@ -37,17 +47,17 @@ import type { WasSyncPort } from './types.js';
  */
 export { KEY_EPOCH_HEADER };
 /**
- * Formats a numeric content `version` as the quoted strong `ETag` an
- * update-if-unchanged write passes as its `ifMatch` precondition (e.g. `3` to
- * `"3"`). Inverse of {@link parseEtag}.
+ * Parses a quoted strong `ETag` into its numeric revision: the decimal
+ * integer after the LAST `.` inside the quotes (`"3mJr7AoUXx2.3"` to `3`).
+ * Returns `undefined` when the header is absent, has no `.`, or the trailing
+ * segment is anything other than a run of digits.
  *
- * @param version {number}
- * @returns {string}
- */
-export declare function formatEtag(version: number): string;
-/**
- * Parses a quoted strong `ETag` (`"3"`) into its numeric revision, or
- * `undefined` when the header is absent or non-numeric (no such revision yet).
+ * The quoted string as a whole is opaque -- it also carries a per-record
+ * generation marker ahead of the version, minted once and kept for the
+ * record's life, so this is one-way: there is no `formatEtag` to build a
+ * validator back out of a bare revision number. Always echo the `etag` a read
+ * or write returned back verbatim for `ifMatch`/`ifNoneMatch`; this helper
+ * only reads the revision out of it for comparison or display.
  *
  * @param etag {string | null | undefined}
  * @returns {number | undefined}

package/dist/sync/port.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../src/sync/port.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,EACL,gBAAgB,EAGjB,MAAM,4BAA4B,CAAA;AAQnC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,KAAK,EAAqB,WAAW,EAAE,MAAM,YAAY,CAAA;AAEhE;;;;;GAKG;AACH,OAAO,EAAE,gBAAgB,EAAE,CAAA;AA4D3B;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAM7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,GAAG,EACH,OAAO,EACP,YAAY,EACZ,UAAU,EACV,aAAqB,EACtB,EAAE;IACD,GAAG,EAAE,SAAS,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,KAAK,CAAA;IAClB,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB,GAAG,WAAW,CAsMd"}
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../src/sync/port.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,EACL,gBAAgB,EAGjB,MAAM,4BAA4B,CAAA;AAWnC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,KAAK,EAAqB,WAAW,EAAY,MAAM,YAAY,CAAA;AAE1E;;;;;GAKG;AACH,OAAO,EAAE,gBAAgB,EAAE,CAAA;AAwG3B;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAW7E;AAwBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,GAAG,EACH,OAAO,EACP,YAAY,EACZ,UAAU,EACV,aAAqB,EACtB,EAAE;IACD,GAAG,EAAE,SAAS,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,KAAK,CAAA;IAClB,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB,GAAG,WAAW,CAiNd"}

package/dist/sync/port.js

@@ -1,6 +1,6 @@
 import { KEY_EPOCH_HEADER, readEtag, writeHeaders } from '../internal/conditional.js';
 import { resourceMeta, resourcePath } from '../internal/paths.js';
-import { httpStatus, WasSyncAuthError, WasSyncConflictError, WasSyncNotFoundError } from '../errors.js';
+import { mapError, NotFoundError, PreconditionFailedError, WasSyncAuthError, WasSyncConflictError, WasSyncNotFoundError } from '../errors.js';
 /**
  * The request header the server reads a content write's key-epoch id from,
  * stamping it onto the Resource's metadata. Defined next to the header
@@ -28,49 +28,87 @@ function isAuthStatus(status) {
     return status === 401 || status === 403 || status === 404;
 }
 /**
- * Maps a raw write error onto the port's typed signals, rethrowing anything
- * else unchanged: `412` becomes a {@link WasSyncConflictError} for every write.
- * `notFound` opts in to the `404` mapping, which only `deleteContent` performs
- * (an already-gone target is a settled outcome for a delete, but a hard error
- * for a content or metadata write). `authErrors` is the port's `mapAuthErrors`
- * option: it maps `401` / `403` / the masked `404` to a
- * {@link WasSyncAuthError}. `notFound` is checked first, so a port that asked
- * for both still gets the delete-specific signal.
+ * Carries a mapped error's `problem+json` fields onto the port signal built
+ * from it. The `cause` is the raw transport error `mapError` recorded, or the
+ * mapped error itself when there was none. A port signal is a narrowing of the
+ * classification `mapError` already made, so it must not lose what the server
+ * said.
+ *
+ * @param mapped {WasError}   the classified error
+ * @returns {WasErrorOptions}
+ */
+function signalOptions(mapped) {
+    return {
+        status: mapped.status,
+        type: mapped.type,
+        title: mapped.title,
+        details: mapped.details,
+        requestUrl: mapped.requestUrl,
+        cause: mapped.cause ?? mapped
+    };
+}
+/**
+ * Whether a mapped error is already one of the port's own signals, which a
+ * nested port call (the write-ack re-read inside a write) can raise through a
+ * write's catch block. Re-wrapping one would drop its cause for no gain.
+ *
+ * @param mapped {WasError}
+ * @returns {boolean}
+ */
+function isPortSignal(mapped) {
+    return (mapped instanceof WasSyncConflictError ||
+        mapped instanceof WasSyncNotFoundError ||
+        mapped instanceof WasSyncAuthError);
+}
+/**
+ * Maps a caught write error onto the port's typed signals, rethrowing anything
+ * else as the classified {@link WasError} the client's own `mapError` builds
+ * (so a status outside this list -- a `500`, a `507` quota-exceeded -- still
+ * leaves the sync subpath typed and carrying the server's problem details).
+ * A rejected precondition becomes a {@link WasSyncConflictError} for every
+ * write. `notFound` opts in to the not-found mapping, which only
+ * `deleteContent` performs (an already-gone target is a settled outcome for a
+ * delete, but a hard error for a content or metadata write). `authErrors` is
+ * the port's `mapAuthErrors` option: it maps `401` / `403` / the masked `404`
+ * to a {@link WasSyncAuthError}. `notFound` is checked first, so a port that
+ * asked for both still gets the delete-specific signal.
  *
  * @param err {unknown}   the caught error
  * @param [options] {object}
- * @param [options.notFound] {boolean}   map `404` to {@link WasSyncNotFoundError}
+ * @param [options.notFound] {boolean}   map a not-found to
+ *   {@link WasSyncNotFoundError}
  * @param [options.authErrors] {boolean}   map `401`/`403`/`404` to
  *   {@link WasSyncAuthError}
  * @returns {never}   always throws
  */
 function mapWriteError(err, { notFound = false, authErrors = false } = {}) {
-    const status = httpStatus(err);
-    if (notFound && status === 404) {
-        throw new WasSyncNotFoundError();
+    const mapped = mapError(err);
+    if (isPortSignal(mapped)) {
+        throw mapped;
+    }
+    if (notFound && mapped instanceof NotFoundError) {
+        throw new WasSyncNotFoundError(mapped.message, signalOptions(mapped));
     }
-    if (status === 412) {
-        throw new WasSyncConflictError();
+    if (mapped instanceof PreconditionFailedError) {
+        throw new WasSyncConflictError(mapped.message, signalOptions(mapped));
     }
-    if (authErrors && isAuthStatus(status)) {
-        throw new WasSyncAuthError(status);
+    if (authErrors && isAuthStatus(mapped.status)) {
+        throw new WasSyncAuthError(mapped.status, signalOptions(mapped));
     }
-    throw err;
+    throw mapped;
 }
 /**
- * Formats a numeric content `version` as the quoted strong `ETag` an
- * update-if-unchanged write passes as its `ifMatch` precondition (e.g. `3` to
- * `"3"`). Inverse of {@link parseEtag}.
+ * Parses a quoted strong `ETag` into its numeric revision: the decimal
+ * integer after the LAST `.` inside the quotes (`"3mJr7AoUXx2.3"` to `3`).
+ * Returns `undefined` when the header is absent, has no `.`, or the trailing
+ * segment is anything other than a run of digits.
  *
- * @param version {number}
- * @returns {string}
- */
-export function formatEtag(version) {
-    return `"${version}"`;
-}
-/**
- * Parses a quoted strong `ETag` (`"3"`) into its numeric revision, or
- * `undefined` when the header is absent or non-numeric (no such revision yet).
+ * The quoted string as a whole is opaque -- it also carries a per-record
+ * generation marker ahead of the version, minted once and kept for the
+ * record's life, so this is one-way: there is no `formatEtag` to build a
+ * validator back out of a bare revision number. Always echo the `etag` a read
+ * or write returned back verbatim for `ifMatch`/`ifNoneMatch`; this helper
+ * only reads the revision out of it for comparison or display.
  *
  * @param etag {string | null | undefined}
  * @returns {number | undefined}
@@ -79,8 +117,31 @@ export function parseEtag(etag) {
     if (!etag) {
         return undefined;
     }
-    const revision = Number(etag.replace(/"/g, ''));
-    return Number.isFinite(revision) ? revision : undefined;
+    const unquoted = etag.replace(/"/g, '');
+    const lastDot = unquoted.lastIndexOf('.');
+    if (lastDot === -1) {
+        return undefined;
+    }
+    const versionPart = unquoted.slice(lastDot + 1);
+    return /^\d+$/.test(versionPart) ? Number(versionPart) : undefined;
+}
+/**
+ * Reads a response's `ETag` together with the revision parsed out of it, the
+ * one place the two are paired. `etag` is absent when the response carried no
+ * validator (a backend that does not version the resource); `version` is
+ * absent whenever `etag` is, and also when the validator does not end in a
+ * revision number. Callers decide what an absent value means for them.
+ *
+ * @param response {HttpResponse}
+ * @returns {{ etag?: string, version?: number }}
+ */
+function versionedEtag(response) {
+    const etag = readEtag(response);
+    const version = parseEtag(etag);
+    return {
+        ...(etag !== undefined && { etag }),
+        ...(version !== undefined && { version })
+    };
 }
 /**
  * Builds a {@link WasSyncPort} bound to one Space + Collection, backed by the
@@ -136,31 +197,36 @@ export function createWasSyncPort({ was, spaceId, collectionId, capability, mapA
             });
         }
         catch (err) {
-            const status = httpStatus(err);
+            const mapped = mapError(err);
             // A read's `404` stays "absent or tombstoned" even under
             // `mapAuthErrors`: it is a modeled outcome here, and the callers read it
             // as deletion-wins.
-            if (status === 404) {
+            if (mapped instanceof NotFoundError) {
                 return null;
             }
-            if (mapAuthErrors && isAuthStatus(status)) {
-                throw new WasSyncAuthError(status);
+            if (mapAuthErrors && isAuthStatus(mapped.status)) {
+                throw new WasSyncAuthError(mapped.status, signalOptions(mapped));
             }
-            throw err;
+            throw mapped;
         }
+        const { etag, version } = versionedEtag(response);
         return {
-            version: parseEtag(readEtag(response)) ?? 0,
+            version: version ?? 0,
+            etag,
             updatedAt: UNKNOWN_UPDATED_AT,
             data: response.data
         };
     };
-    /** Resolves the acked version from a write response, or via a content re-read. */
-    const ackedVersion = async (response, id) => {
-        const version = parseEtag(readEtag(response));
-        if (version !== undefined) {
-            return version;
-        }
-        return (await readContent(id))?.version ?? 0;
+    /**
+     * The acked {@link WriteAck} of a write response. Taken from the response's
+     * own `ETag` only: a re-read after the fact could return a concurrent
+     * writer's validator as this write's ack. A response with no `ETag` acks
+     * `version: 0` and no `etag`, the shape of a backend that does not version
+     * resources.
+     */
+    const writeAck = (response) => {
+        const { etag, version } = versionedEtag(response);
+        return { version: version ?? 0, etag };
     };
     return {
         async query({ checkpoint, limit }) {
@@ -171,11 +237,11 @@ export function createWasSyncPort({ was, spaceId, collectionId, capability, mapA
                 // The pull path is where revoked access surfaces reliably: unlike a
                 // read or a delete, a `404` on the collection's own query endpoint has
                 // no benign reading once the collection is known to exist.
-                const status = httpStatus(err);
-                if (mapAuthErrors && isAuthStatus(status)) {
-                    throw new WasSyncAuthError(status);
+                const mapped = mapError(err);
+                if (mapAuthErrors && isAuthStatus(mapped.status)) {
+                    throw new WasSyncAuthError(mapped.status, signalOptions(mapped));
                 }
-                throw err;
+                throw mapped;
             }
         },
         async putContent({ id, data, ifMatch, ifNoneMatch, epoch }) {
@@ -190,7 +256,7 @@ export function createWasSyncPort({ was, spaceId, collectionId, capability, mapA
                         epoch
                     })
                 });
-                return await ackedVersion(response, id);
+                return writeAck(response);
             }
             catch (err) {
                 mapWriteError(err, { authErrors: mapAuthErrors });
@@ -204,7 +270,7 @@ export function createWasSyncPort({ was, spaceId, collectionId, capability, mapA
                     method: 'DELETE',
                     headers: writeHeaders({ precondition: { ifMatch } })
                 });
-                return await ackedVersion(response, id);
+                return writeAck(response);
             }
             catch (err) {
                 // Under `mapAuthErrors` a delete's `404` is an idempotent success: the
@@ -213,10 +279,11 @@ export function createWasSyncPort({ was, spaceId, collectionId, capability, mapA
                 // holds and the batch must not be retried forever. A masked
                 // authorization `404` is swallowed with it -- indistinguishable by
                 // design -- but revoked access still surfaces on the next `query`.
-                if (mapAuthErrors && httpStatus(err) === 404) {
+                const mapped = mapError(err);
+                if (mapAuthErrors && mapped instanceof NotFoundError) {
                     return undefined;
                 }
-                mapWriteError(err, {
+                mapWriteError(mapped, {
                     notFound: !mapAuthErrors,
                     authErrors: mapAuthErrors
                 });
@@ -236,7 +303,8 @@ export function createWasSyncPort({ was, spaceId, collectionId, capability, mapA
                     json: custom === undefined ? {} : { custom },
                     headers: writeHeaders({ precondition: { ifMatch, ifNoneMatch } })
                 });
-                return parseEtag(readEtag(response));
+                const { etag, version } = versionedEtag(response);
+                return etag !== undefined ? { version: version ?? 0, etag } : undefined;
             }
             catch (err) {
                 mapWriteError(err, { authErrors: mapAuthErrors });
@@ -256,21 +324,21 @@ export function createWasSyncPort({ was, spaceId, collectionId, capability, mapA
             }
             // Metadata (best-effort): the `/meta` body carries the server-managed
             // `updatedAt`, the creator DID, the key-epoch id, and the user-writable
-            // `custom`, plus its own `metaVersion` ETag. A resource with no metadata
-            // yet 404s here; only a hard error propagates.
+            // `custom`, plus its own `metaVersion`/`metaEtag` ETag. A resource with
+            // no metadata yet 404s here; only a hard error propagates.
             const meta = await metaRead;
             if (!meta.ok) {
-                const status = httpStatus(meta.err);
+                const mapped = mapError(meta.err);
                 // A `/meta` `404` is routine (the resource has no metadata document
                 // yet), so it stays benign under `mapAuthErrors` -- only `401`/`403`
                 // map there.
-                if (status === 404) {
+                if (mapped instanceof NotFoundError) {
                     return master;
                 }
-                if (mapAuthErrors && isAuthStatus(status)) {
-                    throw new WasSyncAuthError(status);
+                if (mapAuthErrors && isAuthStatus(mapped.status)) {
+                    throw new WasSyncAuthError(mapped.status, signalOptions(mapped));
                 }
-                throw meta.err;
+                throw mapped;
             }
             const metaBody = meta.response.data;
             if (metaBody?.updatedAt) {
@@ -285,7 +353,12 @@ export function createWasSyncPort({ was, spaceId, collectionId, capability, mapA
             if (metaBody?.custom !== undefined) {
                 master.custom = metaBody.custom;
             }
-            const metaVersion = parseEtag(readEtag(meta.response));
+            // The validator is kept whenever the server sent one, so a later
+            // `putMeta` can pin on it even when no revision number parses out of it.
+            const { etag: metaEtag, version: metaVersion } = versionedEtag(meta.response);
+            if (metaEtag !== undefined) {
+                master.metaEtag = metaEtag;
+            }
             if (metaVersion !== undefined) {
                 master.metaVersion = metaVersion;
             }

package/dist/sync/port.js.map

@@ -1 +1 @@
-{"version":3,"file":"port.js","sourceRoot":"","sources":["../../src/sync/port.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"port.js","sourceRoot":"","sources":["../../src/sync/port.ts"],"names":[],"mappings":"AAuCA,OAAO,EACL,gBAAgB,EAChB,QAAQ,EACR,YAAY,EACb,MAAM,4BAA4B,CAAA;AACnC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACjE,OAAO,EACL,QAAQ,EACR,aAAa,EACb,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACrB,MAAM,cAAc,CAAA;AAKrB;;;;;GAKG;AACH,OAAO,EAAE,gBAAgB,EAAE,CAAA;AAE3B;;;;;;GAMG;AACH,MAAM,kBAAkB,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAA;AAEpD;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,MAA0B;IAC9C,OAAO,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,CAAA;AAC3D,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,aAAa,CAAC,MAAgB;IACrC,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,MAAM;KAC9B,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,MAAgB;IACpC,OAAO,CACL,MAAM,YAAY,oBAAoB;QACtC,MAAM,YAAY,oBAAoB;QACtC,MAAM,YAAY,gBAAgB,CACnC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAS,aAAa,CACpB,GAAY,EACZ,EACE,QAAQ,GAAG,KAAK,EAChB,UAAU,GAAG,KAAK,KAC8B,EAAE;IAEpD,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;IAC5B,IAAI,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;QACzB,MAAM,MAAM,CAAA;IACd,CAAC;IACD,IAAI,QAAQ,IAAI,MAAM,YAAY,aAAa,EAAE,CAAC;QAChD,MAAM,IAAI,oBAAoB,CAAC,MAAM,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IACvE,CAAC;IACD,IAAI,MAAM,YAAY,uBAAuB,EAAE,CAAC;QAC9C,MAAM,IAAI,oBAAoB,CAAC,MAAM,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IACvE,CAAC;IACD,IAAI,UAAU,IAAI,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IAClE,CAAC;IACD,MAAM,MAAM,CAAA;AACd,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,SAAS,CAAC,IAA+B;IACvD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;IACvC,MAAM,OAAO,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;IACzC,IAAI,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC;QACnB,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAA;IAC/C,OAAO,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;AACpE,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,aAAa,CAAC,QAAsB;IAI3C,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAA;IAC/B,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;IAC/B,OAAO;QACL,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC;QACnC,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,CAAC;KAC1C,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAChC,GAAG,EACH,OAAO,EACP,YAAY,EACZ,UAAU,EACV,aAAa,GAAG,KAAK,EAOtB;IACC,wEAAwE;IACxE,sEAAsE;IACtE,MAAM,WAAW,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,CAAC,CAAA;IAC3E,MAAM,QAAQ,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,CAAC,CAAA;IAExE,0EAA0E;IAC1E,sEAAsE;IACtE,uDAAuD;IACvD,MAAM,iBAAiB,GAAG,GAAG;SAC1B,KAAK,CAAC,OAAO,CAAC;SACd,UAAU,CAAC,YAAY,EAAE,EAAE,UAAU,EAAE,CAAC,CAAA;IAE3C,iFAAiF;IACjF,MAAM,WAAW,GAAG,KAAK,EAAE,EAAU,EAA+B,EAAE;QACpE,IAAI,QAAsB,CAAA;QAC1B,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC;gBAC3B,UAAU;gBACV,IAAI,EAAE,WAAW,CAAC,EAAE,CAAC;gBACrB,MAAM,EAAE,KAAK;aACd,CAAC,CAAA;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;YAC5B,yDAAyD;YACzD,yEAAyE;YACzE,oBAAoB;YACpB,IAAI,MAAM,YAAY,aAAa,EAAE,CAAC;gBACpC,OAAO,IAAI,CAAA;YACb,CAAC;YACD,IAAI,aAAa,IAAI,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;gBACjD,MAAM,IAAI,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;YAClE,CAAC;YACD,MAAM,MAAM,CAAA;QACd,CAAC;QACD,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAA;QACjD,OAAO;YACL,OAAO,EAAE,OAAO,IAAI,CAAC;YACrB,IAAI;YACJ,SAAS,EAAE,kBAAkB;YAC7B,IAAI,EAAE,QAAQ,CAAC,IAAY;SAC5B,CAAA;IACH,CAAC,CAAA;IAED;;;;;;OAMG;IACH,MAAM,QAAQ,GAAG,CAAC,QAAsB,EAAY,EAAE;QACpD,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAA;QACjD,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,CAAC,EAAE,IAAI,EAAE,CAAA;IACxC,CAAC,CAAA;IAED,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE;YAC/B,IAAI,CAAC;gBACH,OAAO,MAAM,iBAAiB,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAA;YAC/D,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,oEAAoE;gBACpE,uEAAuE;gBACvE,2DAA2D;gBAC3D,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;gBAC5B,IAAI,aAAa,IAAI,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;oBACjD,MAAM,IAAI,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;gBAClE,CAAC;gBACD,MAAM,MAAM,CAAA;YACd,CAAC;QACH,CAAC;QAED,KAAK,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE;YACxD,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC;oBACjC,UAAU;oBACV,IAAI,EAAE,WAAW,CAAC,EAAE,CAAC;oBACrB,MAAM,EAAE,KAAK;oBACb,IAAI,EAAE,IAAc;oBACpB,OAAO,EAAE,YAAY,CAAC;wBACpB,YAAY,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE;wBACtC,KAAK;qBACN,CAAC;iBACH,CAAC,CAAA;gBACF,OAAO,QAAQ,CAAC,QAAQ,CAAC,CAAA;YAC3B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,aAAa,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,aAAa,EAAE,CAAC,CAAA;YACnD,CAAC;QACH,CAAC;QAED,KAAK,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE;YACjC,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC;oBACjC,UAAU;oBACV,IAAI,EAAE,WAAW,CAAC,EAAE,CAAC;oBACrB,MAAM,EAAE,QAAQ;oBAChB,OAAO,EAAE,YAAY,CAAC,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC;iBACrD,CAAC,CAAA;gBACF,OAAO,QAAQ,CAAC,QAAQ,CAAC,CAAA;YAC3B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,uEAAuE;gBACvE,uEAAuE;gBACvE,sEAAsE;gBACtE,4DAA4D;gBAC5D,mEAAmE;gBACnE,mEAAmE;gBACnE,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;gBAC5B,IAAI,aAAa,IAAI,MAAM,YAAY,aAAa,EAAE,CAAC;oBACrD,OAAO,SAAS,CAAA;gBAClB,CAAC;gBACD,aAAa,CAAC,MAAM,EAAE;oBACpB,QAAQ,EAAE,CAAC,aAAa;oBACxB,UAAU,EAAE,aAAa;iBAC1B,CAAC,CAAA;YACJ,CAAC;QACH,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE;YAChD,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC;oBACjC,UAAU;oBACV,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;oBAClB,MAAM,EAAE,KAAK;oBACb,qEAAqE;oBACrE,+DAA+D;oBAC/D,+DAA+D;oBAC/D,oEAAoE;oBACpE,4DAA4D;oBAC5D,IAAI,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE;oBAC5C,OAAO,EAAE,YAAY,CAAC,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE,CAAC;iBAClE,CAAC,CAAA;gBACF,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAA;gBACjD,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;YACzE,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,aAAa,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,aAAa,EAAE,CAAC,CAAA;YACnD,CAAC;QACH,CAAC;QAED,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE;YACd,wEAAwE;YACxE,0EAA0E;YAC1E,0EAA0E;YAC1E,4CAA4C;YAC5C,MAAM,QAAQ,GAAG,GAAG;iBACjB,OAAO,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;iBAC1D,IAAI,CACH,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAa,EAAE,QAAQ,EAAE,CAAC,EAC7C,CAAC,GAAY,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAc,EAAE,GAAG,EAAE,CAAC,CAChD,CAAA;YAEH,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,EAAE,CAAC,CAAA;YACpC,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBACpB,OAAO,IAAI,CAAA,CAAC,uDAAuD;YACrE,CAAC;YAED,sEAAsE;YACtE,wEAAwE;YACxE,wEAAwE;YACxE,2DAA2D;YAC3D,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAA;YAC3B,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;gBACb,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;gBACjC,oEAAoE;gBACpE,qEAAqE;gBACrE,aAAa;gBACb,IAAI,MAAM,YAAY,aAAa,EAAE,CAAC;oBACpC,OAAO,MAAM,CAAA;gBACf,CAAC;gBACD,IAAI,aAAa,IAAI,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;oBACjD,MAAM,IAAI,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;gBAClE,CAAC;gBACD,MAAM,MAAM,CAAA;YACd,CAAC;YAED,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAOlB,CAAA;YACb,IAAI,QAAQ,EAAE,SAAS,EAAE,CAAC;gBACxB,MAAM,CAAC,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAA;YACvC,CAAC;YACD,IAAI,QAAQ,EAAE,SAAS,KAAK,SAAS,EAAE,CAAC;gBACtC,MAAM,CAAC,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAA;YACvC,CAAC;YACD,IAAI,QAAQ,EAAE,KAAK,KAAK,SAAS,EAAE,CAAC;gBAClC,MAAM,CAAC,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAA;YAC/B,CAAC;YACD,IAAI,QAAQ,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;gBACnC,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAA;YACjC,CAAC;YACD,iEAAiE;YACjE,yEAAyE;YACzE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,aAAa,CAC5D,IAAI,CAAC,QAAQ,CACd,CAAA;YACD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,MAAM,CAAC,QAAQ,GAAG,QAAQ,CAAA;YAC5B,CAAC;YACD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;gBAC9B,MAAM,CAAC,WAAW,GAAG,WAAW,CAAA;YAClC,CAAC;YAED,OAAO,MAAM,CAAA;QACf,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/sync/predicates.d.ts

@@ -0,0 +1,67 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `err.name` predicates that classify the errors a replication path can
+ * meet: the port's two wire signals (`WasSyncConflictError` /
+ * `WasSyncNotFoundError`), its opt-in revoked-access signal
+ * (`WasSyncAuthError`), and the cipher's stale-descriptor signal
+ * (`UnknownEpochError`).
+ *
+ * They live beside the classes that assign the names they match (`errors.ts`)
+ * because every one of those errors is raised inside a seam the consuming app
+ * injects -- the port for the wire signals, the caller's `DocCipher` for the
+ * unknown epoch -- and that seam can resolve to a SECOND copy of this package
+ * (a `link:` dev setup, a dedupe miss through a dependency tree). So the match
+ * is on the `name` string alone and never `instanceof`, which cannot see across
+ * that boundary. The cost of a miss is silent and expensive: every push 412
+ * becomes a fatal cycle error, and a create-loss re-mint rethrows instead of
+ * re-minting. Each class assigns its `name` explicitly, which is what makes the
+ * string a contract (`decisions/0001-cross-package-errors-match-by-name.md`).
+ *
+ * Each returns a plain boolean rather than a type guard: the guard would narrow
+ * to this copy's class, the very identity the rule declines to depend on. A
+ * caller reading a property after the match (`err.status` on an auth error)
+ * reads it off the value itself.
+ */
+/**
+ * Whether an error is the replication port's rejected-conditional-write signal
+ * (`WasSyncConflictError`, HTTP 412): a lost-update `If-Match` mismatch, or a
+ * create-if-absent whose target already exists. The push loop's one settle-and-
+ * reconcile branch; everything else propagates to the engine's backoff.
+ *
+ * @param err {unknown}
+ * @returns {boolean}
+ */
+export declare function isSyncConflictError(err: unknown): boolean;
+/**
+ * Whether an error is the replication port's absent-target signal
+ * (`WasSyncNotFoundError`, HTTP 404). On a delete that is a settled outcome
+ * -- already gone, or the write never reached the server -- not a conflict.
+ *
+ * @param err {unknown}
+ * @returns {boolean}
+ */
+export declare function isSyncNotFoundError(err: unknown): boolean;
+/**
+ * Whether an error is the replication port's refused-authorization signal
+ * (`WasSyncAuthError`), raised only by a port built with `mapAuthErrors`. It
+ * covers `401`, `403`, and the `404` a WAS server returns when it masks an
+ * authorization failure as "not found", so a caller that needs the three apart
+ * reads `status` off the matched value as a plain property.
+ *
+ * @param err {unknown}
+ * @returns {boolean}
+ */
+export declare function isSyncAuthError(err: unknown): boolean;
+/**
+ * Whether an error is the cipher's unknown-epoch signal (`UnknownEpochError`):
+ * an envelope naming recipient key ids whose epoch the descriptor this reader
+ * holds does not list at all. Distinct from a key the reader simply does not
+ * have (`KeyUnwrapError`), which re-reading the descriptor cannot fix.
+ *
+ * @param err {unknown}
+ * @returns {boolean}
+ */
+export declare function isUnknownEpochError(err: unknown): boolean;
+//# sourceMappingURL=predicates.d.ts.map

package/dist/sync/predicates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicates.d.ts","sourceRoot":"","sources":["../../src/sync/predicates.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAaH;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAErD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEzD"}

package/dist/sync/predicates.js

@@ -0,0 +1,85 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `err.name` predicates that classify the errors a replication path can
+ * meet: the port's two wire signals (`WasSyncConflictError` /
+ * `WasSyncNotFoundError`), its opt-in revoked-access signal
+ * (`WasSyncAuthError`), and the cipher's stale-descriptor signal
+ * (`UnknownEpochError`).
+ *
+ * They live beside the classes that assign the names they match (`errors.ts`)
+ * because every one of those errors is raised inside a seam the consuming app
+ * injects -- the port for the wire signals, the caller's `DocCipher` for the
+ * unknown epoch -- and that seam can resolve to a SECOND copy of this package
+ * (a `link:` dev setup, a dedupe miss through a dependency tree). So the match
+ * is on the `name` string alone and never `instanceof`, which cannot see across
+ * that boundary. The cost of a miss is silent and expensive: every push 412
+ * becomes a fatal cycle error, and a create-loss re-mint rethrows instead of
+ * re-minting. Each class assigns its `name` explicitly, which is what makes the
+ * string a contract (`decisions/0001-cross-package-errors-match-by-name.md`).
+ *
+ * Each returns a plain boolean rather than a type guard: the guard would narrow
+ * to this copy's class, the very identity the rule declines to depend on. A
+ * caller reading a property after the match (`err.status` on an auth error)
+ * reads it off the value itself.
+ */
+/**
+ * Reads the `name` off an unknown caught value, without raising on a nullish
+ * or non-object rejection.
+ *
+ * @param err {unknown}   the caught error
+ * @returns {unknown}
+ */
+function nameOf(err) {
+    return err?.name;
+}
+/**
+ * Whether an error is the replication port's rejected-conditional-write signal
+ * (`WasSyncConflictError`, HTTP 412): a lost-update `If-Match` mismatch, or a
+ * create-if-absent whose target already exists. The push loop's one settle-and-
+ * reconcile branch; everything else propagates to the engine's backoff.
+ *
+ * @param err {unknown}
+ * @returns {boolean}
+ */
+export function isSyncConflictError(err) {
+    return nameOf(err) === 'WasSyncConflictError';
+}
+/**
+ * Whether an error is the replication port's absent-target signal
+ * (`WasSyncNotFoundError`, HTTP 404). On a delete that is a settled outcome
+ * -- already gone, or the write never reached the server -- not a conflict.
+ *
+ * @param err {unknown}
+ * @returns {boolean}
+ */
+export function isSyncNotFoundError(err) {
+    return nameOf(err) === 'WasSyncNotFoundError';
+}
+/**
+ * Whether an error is the replication port's refused-authorization signal
+ * (`WasSyncAuthError`), raised only by a port built with `mapAuthErrors`. It
+ * covers `401`, `403`, and the `404` a WAS server returns when it masks an
+ * authorization failure as "not found", so a caller that needs the three apart
+ * reads `status` off the matched value as a plain property.
+ *
+ * @param err {unknown}
+ * @returns {boolean}
+ */
+export function isSyncAuthError(err) {
+    return nameOf(err) === 'WasSyncAuthError';
+}
+/**
+ * Whether an error is the cipher's unknown-epoch signal (`UnknownEpochError`):
+ * an envelope naming recipient key ids whose epoch the descriptor this reader
+ * holds does not list at all. Distinct from a key the reader simply does not
+ * have (`KeyUnwrapError`), which re-reading the descriptor cannot fix.
+ *
+ * @param err {unknown}
+ * @returns {boolean}
+ */
+export function isUnknownEpochError(err) {
+    return nameOf(err) === 'UnknownEpochError';
+}
+//# sourceMappingURL=predicates.js.map

package/dist/sync/predicates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicates.js","sourceRoot":"","sources":["../../src/sync/predicates.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;GAMG;AACH,SAAS,MAAM,CAAC,GAAY;IAC1B,OAAQ,GAAiC,EAAE,IAAI,CAAA;AACjD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,sBAAsB,CAAA;AAC/C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,sBAAsB,CAAA;AAC/C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,kBAAkB,CAAA;AAC3C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,mBAAmB,CAAA;AAC5C,CAAC"}

package/dist/sync/types.d.ts

@@ -9,7 +9,8 @@
  * here under replication-facing names so a sync consumer imports one module.
  * `WasSyncPort` and `MasterState` are the injectable access seam the change
  * engine depends on, and `DocCipher` is the encrypt/decrypt seam a per-
- * collection cipher implements.
+ * collection cipher implements. `SyncStatus` is the closed status vocabulary
+ * every replication driver reports one feed's state through.
  */
 import type { ChangeDocument, ChangesCheckpoint, ChangesPage } from '@interop/storage-core';
 import type { Json } from '../types.js';
@@ -24,12 +25,17 @@ export type { Json };
 export type SyncCheckpoint = ChangesCheckpoint;
 /**
  * One document as it travels on the `changes` feed wire: `id` is the WAS
- * resource id, `version` the content revision (the push `If-Match` ETag), and
- * the stored body is under `data`. A tombstone carries `_deleted: true` with no
- * `data`. This is the shared `ChangeDocument` from `@interop/storage-core`; on
- * an encrypted collection `data`/`custom` are the opaque stored envelope, moved
- * verbatim (decrypt is a projection-time concern the engine's `DocCipher`
- * handles, never the port).
+ * resource id, `version` its monotonic content revision number, and the
+ * stored body is under `data`. `version` is for comparison/ordering only and
+ * is not an `ifMatch` value on its own; the server's `ETag` is an opaque
+ * string that embeds more than the version. The feed carries the validators
+ * themselves: `etag` (content) and `metaEtag` (the `/meta` object), quoted
+ * exactly as the server emits them, so a puller passes one back verbatim as a
+ * conditional write's `ifMatch` without a {@link WasSyncPort.get} first. A
+ * tombstone carries `_deleted: true` with no `data`. This is the shared
+ * `ChangeDocument` from `@interop/storage-core`; on an encrypted collection
+ * `data`/`custom` are the opaque stored envelope, moved verbatim (decrypt is a
+ * projection-time concern the engine's `DocCipher` handles, never the port).
  */
 export type WireDoc = ChangeDocument;
 /**
@@ -42,20 +48,41 @@ export type SyncPage = ChangesPage;
  * The current master state of a single resource, read back for the 412-conflict
  * path ({@link WasSyncPort.get}). An absent or tombstoned resource surfaces as
  * `get` resolving `null`, never as a `MasterState`. `updatedAt`, `metaVersion`,
- * `custom`, `createdBy`, and `epoch` are populated from the resource's `/meta`
- * document when it exists; a resource with no metadata yet reports an
- * epoch-zero `updatedAt` placeholder (a valid, sortable timestamp -- the
- * change feed remains the authority on ordering).
+ * `metaEtag`, `custom`, `createdBy`, and `epoch` are populated from the
+ * resource's `/meta` document when it exists; a resource with no metadata yet
+ * reports an epoch-zero `updatedAt` placeholder (a valid, sortable timestamp --
+ * the change feed remains the authority on ordering).
+ *
+ * `etag` and `metaEtag` are the raw, opaque `ETag` validators the content and
+ * `/meta` reads returned (absent against a backend that does not version
+ * resources) -- pass one back verbatim as a later write's `ifMatch`. `version`
+ * and `metaVersion` are the revision numbers parsed out of them, for
+ * comparison or display only.
  */
 export interface MasterState {
     version: number;
+    etag?: string;
     updatedAt: string;
     metaVersion?: number;
+    metaEtag?: string;
     data?: Json;
     custom?: Json;
     createdBy?: string;
     epoch?: string;
 }
+/**
+ * The acknowledgment a conditional write returns: the new `version` plus the
+ * opaque `etag` validator it lives behind, exactly as the server sent it.
+ * Pass `etag` back verbatim as a later write's `ifMatch` -- it can no longer
+ * be synthesized from `version` alone, since the server's `ETag` also embeds a
+ * per-record generation marker ahead of the version. `etag` is absent against
+ * a backend that does not version resources; read `version` only to compare
+ * or display a revision number.
+ */
+export interface WriteAck {
+    version: number;
+    etag?: string;
+}
 /**
  * The injected WAS-access seam. `createWasSyncPort` implements this over
  * `@interop/was-client`'s `was.request()` and the `Collection.changes()` feed;
@@ -77,10 +104,10 @@ export interface WasSyncPort {
     }): Promise<SyncPage>;
     /**
      * Conditionally writes the content body verbatim (`PUT /:id`). Pass
-     * `ifNoneMatch: true` for create-if-absent, or `ifMatch` (a quoted ETag over
-     * the content `version`) for update-if-unchanged. `epoch` stamps the opaque
-     * key-epoch id the body was encrypted under (absent clears any prior stamp).
-     * Returns the new server `version` (parsed from the write's `ETag`). Throws
+     * `ifNoneMatch: true` for create-if-absent, or `ifMatch` (the opaque `ETag`
+     * from a prior read/write, echoed back verbatim) for update-if-unchanged.
+     * `epoch` stamps the opaque key-epoch id the body was encrypted under
+     * (absent clears any prior stamp). Returns the new {@link WriteAck}. Throws
      * {@link WasSyncConflictError} on `412`.
      */
     putContent(options: {
@@ -89,13 +116,14 @@ export interface WasSyncPort {
         ifMatch?: string;
         ifNoneMatch?: boolean;
         epoch?: string;
-    }): Promise<number>;
+    }): Promise<WriteAck>;
     /**
      * Conditionally deletes a resource (writes a tombstone; `DELETE /:id`). Pass
-     * `ifMatch` (a quoted ETag over the content `version`) to delete only if
-     * unchanged. Returns the tombstone's new server `version`. Throws
-     * {@link WasSyncConflictError} on `412`, {@link WasSyncNotFoundError} on `404`
-     * (already gone -- a settled outcome for a delete).
+     * `ifMatch` (the opaque `ETag` from a prior read/write, echoed back
+     * verbatim) to delete only if unchanged. Returns the tombstone's new
+     * {@link WriteAck}. Throws {@link WasSyncConflictError} on `412`,
+     * {@link WasSyncNotFoundError} on `404` (already gone -- a settled outcome
+     * for a delete).
      *
      * Resolves `undefined` instead when the port was built with
      * `mapAuthErrors: true` and the target was already absent: there the delete
@@ -104,22 +132,22 @@ export interface WasSyncPort {
     deleteContent(options: {
         id: string;
         ifMatch?: string;
-    }): Promise<number | undefined>;
+    }): Promise<WriteAck | undefined>;
     /**
      * Conditionally writes the user-writable metadata `custom` (`PUT /:id/meta`).
      * Optional -- present only on a port that syncs metadata. The write fully
      * replaces `custom`, so omitting it writes the CLEARED state (the server
      * clears every property the body leaves out) -- that is how a metadata clear
-     * replicates. Returns the new `metaVersion` (parsed from the write's `ETag`),
-     * or `undefined` when the response carried none. Throws
-     * {@link WasSyncConflictError} on `412`.
+     * replicates. Returns the new metadata {@link WriteAck}, or `undefined` when
+     * the response carried no `ETag`. Throws {@link WasSyncConflictError} on
+     * `412`.
      */
     putMeta?(options: {
         id: string;
         custom?: Json;
         ifMatch?: string;
         ifNoneMatch?: boolean;
-    }): Promise<number | undefined>;
+    }): Promise<WriteAck | undefined>;
     /**
      * Re-reads a single resource's current master state for the 412-conflict
      * assembler. Returns `null` when the resource is genuinely absent OR a
@@ -169,4 +197,11 @@ export interface DocCipher {
         envelope: Json;
     }): Promise<Json>;
 }
+/**
+ * Per-feed replication status, surfaced to the app's state layer. The
+ * vocabulary is closed: a consumer may render a status through a lookup keyed
+ * on the string, so a widened value would fail at runtime rather than at
+ * compile time.
+ */
+export type SyncStatus = 'idle' | 'syncing' | 'synced' | 'error';
 //# sourceMappingURL=types.d.ts.map

package/dist/sync/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sync/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;GASG;AACH,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,WAAW,EACZ,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAEvC,YAAY,EAAE,IAAI,EAAE,CAAA;AAEpB;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,iBAAiB,CAAA;AAE9C;;;;;;;;GAQG;AACH,MAAM,MAAM,OAAO,GAAG,cAAc,CAAA;AAEpC;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAA;AAElC;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,MAAM,CAAC,EAAE,IAAI,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE;QACb,UAAU,CAAC,EAAE,cAAc,CAAA;QAC3B,KAAK,EAAE,MAAM,CAAA;KACd,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAErB;;;;;;;OAOG;IACH,UAAU,CAAC,OAAO,EAAE;QAClB,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,EAAE,IAAI,CAAA;QACV,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,WAAW,CAAC,EAAE,OAAO,CAAA;QACrB,KAAK,CAAC,EAAE,MAAM,CAAA;KACf,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAEnB;;;;;;;;;;OAUG;IACH,aAAa,CAAC,OAAO,EAAE;QACrB,EAAE,EAAE,MAAM,CAAA;QACV,OAAO,CAAC,EAAE,MAAM,CAAA;KACjB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IAE/B;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,OAAO,EAAE;QAChB,EAAE,EAAE,MAAM,CAAA;QACV,MAAM,CAAC,EAAE,IAAI,CAAA;QACb,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,WAAW,CAAC,EAAE,OAAO,CAAA;KACtB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IAE/B;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;CAC1D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,OAAO,EAAE;QACf,IAAI,EAAE,IAAI,CAAA;KACX,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC3D,aAAa,CAAC,CAAC,OAAO,EAAE;QACtB,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,EAAE,IAAI,CAAA;QACV,OAAO,EAAE,IAAI,CAAA;KACd,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC3D,OAAO,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sync/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@interop/was-client",
   "description": "A developer-friendly client for Wallet Attached Storage (WAS) servers.",
-  "version": "0.48.1",
+  "version": "0.50.0",
   "type": "module",
   "scripts": {
     "build": "pnpm run clear && tsc",
@@ -67,7 +67,7 @@
     "@interop/ezcap": "^7.4.6",
     "@interop/http-client": "^1.0.5",
     "@interop/minimal-cipher": "^7.10.0",
-    "@interop/storage-core": "^0.10.0",
+    "@interop/storage-core": "^0.11.0",
     "@interop/vh-resource-log": "^0.4.1",
     "@interop/x25519-key-agreement-key": "^5.3.0",
     "@noble/hashes": "^2.3.0",