@opendatalabs/personal-server-ts-core 1.34.2 → 1.35.1

package/dist/publication/publish.js

@@ -0,0 +1,261 @@
+import { DataFileEnvelopeSchema, decryptWithPassword, deriveScopeKey, encryptWithPassword, } from "@opendatalabs/vana-sdk/browser";
+import { keccak256, stringToHex } from "viem";
+import { isTombstoneRecord } from "../sync/tombstone.js";
+import { readStoredLineage } from "../lineage/lineage.js";
+import { StoredBlobConflictError, } from "../storage/adapters/interface.js";
+export class NeedsFencedPublicationError extends Error {
+    scope;
+    reason;
+    retryable;
+    code = "NEEDS_FENCED_PUBLICATION";
+    constructor(scope, reason, retryable = true) {
+        super(`Needs fenced publication for ${scope}: ${reason}`);
+        this.scope = scope;
+        this.reason = reason;
+        this.retryable = retryable;
+        this.name = "NeedsFencedPublicationError";
+    }
+}
+const sameHash = (a, b) => a.toLowerCase() === b.toLowerCase();
+function metadata(scope, collectedAt, sizeBytes) {
+    return keccak256(stringToHex(JSON.stringify({ scope, collectedAt, sizeBytes })));
+}
+/** Full-envelope preparation and verification for the shared publication owner. */
+export async function publishVersion(options) {
+    const { envelope, storageAdapter } = options;
+    const { scope } = envelope;
+    const password = Array.from(deriveScopeKey(options.masterKey, scope), (byte) => byte.toString(16).padStart(2, "0")).join("");
+    const plaintext = new TextEncoder().encode(JSON.stringify(envelope));
+    const lineage = readStoredLineage(envelope.data);
+    function candidate(env, bytes, hash) {
+        return {
+            dataHash: hash,
+            metadataHash: metadata(scope, env.collectedAt, bytes.byteLength),
+            sizeBytes: bytes.byteLength,
+            lineage: readStoredLineage(env.data),
+        };
+    }
+    return publishPreparedVersion({
+        ...options,
+        scope,
+        storageAdapter,
+        async prepare() {
+            const encrypted = await encryptWithPassword(plaintext, password);
+            return {
+                encrypted,
+                wanted: {
+                    ...candidate(envelope, encrypted, keccak256(plaintext)),
+                    lineage,
+                },
+                async verifyStored(bytes) {
+                    const clear = await decryptWithPassword(bytes, password);
+                    const env = DataFileEnvelopeSchema.parse(JSON.parse(new TextDecoder().decode(clear)));
+                    if (env.scope !== scope ||
+                        !Number.isFinite(Date.parse(env.collectedAt)))
+                        throw new Error("Publication envelope scope/timestamp mismatch");
+                    return candidate(env, bytes, keccak256(clear));
+                },
+            };
+        },
+    });
+}
+/** Single reserve/upload/register/recover policy for full and bounded hosts.
+ * No deletion/reclaim effect is permitted here. Retries derive evidence from
+ * storage and the registry, never from an abandoned attempt's local URL. */
+export async function publishPreparedVersion(options) {
+    const { scope, storageAdapter, fencedPublication, signer } = options;
+    const isDeleted = (row) => Boolean(row.deletedAt) || isTombstoneRecord(row);
+    let fence = await fencedPublication?.read({
+        ownerAddress: options.ownerAddress,
+        scope,
+    });
+    let head = fence ? fence.head : options.head;
+    await options.checkHead?.(head ?? null);
+    function requireFence(reason) {
+        if (!fence)
+            throw new NeedsFencedPublicationError(scope, reason);
+        return fence;
+    }
+    function checkDeletion() {
+        if (!head || !isDeleted(head))
+            return;
+        requireFence("publication crosses a deletion");
+        if (options.acknowledgedDeletionVersion !== BigInt(head.expectedVersion))
+            throw new NeedsFencedPublicationError(scope, "tombstone was not acknowledged by this publication");
+    }
+    checkDeletion();
+    const { encrypted, wanted, verifyStored } = await options.prepare();
+    const wantedHash = wanted.dataHash;
+    const keyUrl = (version) => storageAdapter.urlForKey(`${scope}/${version}`);
+    async function readCandidate(version) {
+        const bytes = await storageAdapter.download(keyUrl(version));
+        return verifyStored(bytes);
+    }
+    async function commit(version, value, mode) {
+        const request = {
+            ownerAddress: options.ownerAddress,
+            scope,
+            dataHash: value.dataHash,
+            metadataHash: value.metadataHash,
+            expectedVersion: String(version),
+            signature: await signer.signAddData({
+                ownerAddress: options.ownerAddress,
+                scope,
+                dataHash: value.dataHash,
+                metadataHash: value.metadataHash,
+                expectedVersion: version,
+            }),
+        };
+        const lineage = value.lineage;
+        let lineageFields;
+        if (lineage) {
+            if (!signer.signLineageAttestation ||
+                (!fencedPublication && !options.lineageGateway))
+                throw new Error(`Cannot register derivative ${scope}: lineage registration needs a gateway URL (lineageGateway is not configured)`);
+            lineageFields = {
+                lineage: lineage.sources,
+                lineageSignature: await signer.signLineageAttestation({
+                    ownerAddress: options.ownerAddress,
+                    scope,
+                    expectedVersion: version,
+                    dataHash: value.dataHash,
+                    sources: lineage.sources,
+                }),
+            };
+        }
+        let id;
+        if (fencedPublication) {
+            const previous = requireFence("registration/adoption");
+            const result = await fencedPublication.commit({
+                ...request,
+                ...lineageFields,
+                mode,
+                fence: previous,
+            });
+            const registered = result.fence.head;
+            if (result.fence.generation !== previous.generation ||
+                !registered ||
+                isDeleted(registered) ||
+                registered.expectedVersion !== String(version) ||
+                !sameHash(registered.dataHash, value.dataHash) ||
+                !sameHash(registered.metadataHash, value.metadataHash) ||
+                registered.id !== result.dataPointId)
+                throw new Error("Gateway returned inconsistent publication evidence");
+            fence = result.fence;
+            head = registered;
+            id = result.dataPointId;
+        }
+        else if (mode === "adopt") {
+            // No remote effect: the caller verified the live row's stored bytes.
+            id = head?.id;
+        }
+        else {
+            const result = lineageFields
+                ? await options.lineageGateway.registerDataPoint({
+                    ...request,
+                    ...lineageFields,
+                })
+                : await options.gateway.registerDataPoint(request);
+            id = result.dataPointId;
+        }
+        if (!id)
+            throw new Error(`Gateway registerDataPoint did not return a dataPointId for ${scope} version ${version}`);
+        return {
+            version,
+            url: keyUrl(version),
+            dataPointId: id,
+            sizeBytes: value.sizeBytes,
+            dataHash: value.dataHash,
+            metadataHash: value.metadataHash,
+        };
+    }
+    // An observed head decides the next version. A local version ahead of the
+    // registry would leave our bytes at a future key that later wedges it.
+    let version = head === undefined
+        ? options.preferredVersion
+        : BigInt(head?.expectedVersion ?? "0") + 1n;
+    let rebased = false;
+    for (let step = 0; step < 4; step++) {
+        checkDeletion();
+        if (head && !isDeleted(head) && sameHash(head.dataHash, wantedHash)) {
+            version = BigInt(head.expectedVersion);
+            const url = keyUrl(version);
+            if (!(await storageAdapter.exists(url))) {
+                // Recreating bytes can race a delete's cleanup; that needs the fence.
+                requireFence("healing a committed version's missing bytes");
+                if (!sameHash(wanted.metadataHash, head.metadataHash))
+                    throw new Error("Missing committed blob cannot be healed: metadata commitment mismatch");
+                try {
+                    await storageAdapter.upload(`${scope}/${version}`, encrypted);
+                }
+                catch (error) {
+                    if (!(error instanceof StoredBlobConflictError))
+                        throw error;
+                }
+            }
+            const value = await readCandidate(version);
+            if (!sameHash(value.dataHash, head.dataHash) ||
+                !sameHash(value.metadataHash, head.metadataHash))
+                throw new Error("Adopted publication commitment mismatch");
+            return commit(version, value, "adopt");
+        }
+        if (fence)
+            version = BigInt(head?.expectedVersion ?? "0") + 1n;
+        if (head && BigInt(head.expectedVersion) >= version)
+            version = BigInt(head.expectedVersion) + 1n;
+        let value = wanted;
+        try {
+            await storageAdapter.upload(`${scope}/${version}`, encrypted);
+        }
+        catch (error) {
+            if (!(error instanceof StoredBlobConflictError))
+                throw error;
+            value = await readCandidate(version);
+            // Unfenced, resume only our own content: registering it is the same
+            // registration a fresh upload would make. A foreign occupant needs
+            // adopt-then-supersede, which needs the fence.
+            if (!sameHash(value.dataHash, wantedHash))
+                requireFence("resuming an occupied unregistered version");
+        }
+        try {
+            const result = await commit(version, value, "register");
+            if (sameHash(value.dataHash, wantedHash))
+                return result;
+            // Verified foreign reservation is now committed. Supersede in this
+            // generation, using the returned fence; never re-read across a delete.
+            version++;
+        }
+        catch (error) {
+            if (fencedPublication ||
+                !(error instanceof Error) ||
+                !/Gateway error: 409\b/.test(error.message))
+                throw error;
+            if (rebased)
+                throw error;
+            rebased = true;
+            head = await options.readHead();
+            await options.checkHead?.(head);
+            checkDeletion();
+            const next = parseGatewayNextVersion(error.message);
+            if (!head && next === null)
+                throw error;
+            const observedNext = BigInt(head?.expectedVersion ?? "0") + 1n;
+            if (next !== null && BigInt(next) > observedNext)
+                requireFence("gateway version hint advances beyond the observed registry head");
+            version = observedNext;
+        }
+    }
+    throw new Error(`Publication contention for ${scope}; retry next cycle`);
+}
+/** Legacy gateway conflict hints; fenced recovery never guesses from text. */
+export function parseGatewayNextVersion(message) {
+    const nextValid = message.match(/next valid version is (\d+)/i);
+    if (nextValid)
+        return Number(nextValid[1]);
+    const effectiveMax = message.match(/effective max \((\d+)/i);
+    if (effectiveMax)
+        return Number(effectiveMax[1]) + 1;
+    const storedValue = message.match(/strictly greater than the stored value (\d+)/i);
+    return storedValue ? Number(storedValue[1]) + 1 : null;
+}
+//# sourceMappingURL=publish.js.map

package/dist/publication/publish.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish.js","sourceRoot":"","sources":["../../src/publication/publish.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,cAAc,EACd,mBAAmB,GAGpB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG1D,OAAO,EACL,uBAAuB,GAExB,MAAM,kCAAkC,CAAC;AAgC1C,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IAGzC;IACA;IACA;IAJF,IAAI,GAAG,0BAA0B,CAAC;IAC3C,YACW,KAAa,EACb,MAAc,EACd,YAAqB,IAAI;QAElC,KAAK,CAAC,gCAAgC,KAAK,KAAK,MAAM,EAAE,CAAC,CAAC;QAJjD,UAAK,GAAL,KAAK,CAAQ;QACb,WAAM,GAAN,MAAM,CAAQ;QACd,cAAS,GAAT,SAAS,CAAgB;QAGlC,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF;AA6BD,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;AAC/E,SAAS,QAAQ,CAAC,KAAa,EAAE,WAAmB,EAAE,SAAiB;IACrE,OAAO,SAAS,CACd,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC,CAAC,CAC/D,CAAC;AACJ,CAAC;AAED,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAuB;IAEvB,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC;IAC7C,MAAM,EAAE,KAAK,EAAE,GAAG,QAAQ,CAAC;IAC3B,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CACzB,cAAc,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,EACxC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAC7C,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACX,MAAM,SAAS,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IACrE,MAAM,OAAO,GAAG,iBAAiB,CAAC,QAAQ,CAAC,IAA+B,CAAC,CAAC;IAC5E,SAAS,SAAS,CAChB,GAAqB,EACrB,KAAiB,EACjB,IAAmB;QAEnB,OAAO;YACL,QAAQ,EAAE,IAAI;YACd,YAAY,EAAE,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,UAAU,CAAC;YAChE,SAAS,EAAE,KAAK,CAAC,UAAU;YAC3B,OAAO,EAAE,iBAAiB,CAAC,GAAG,CAAC,IAA+B,CAAC;SAChE,CAAC;IACJ,CAAC;IACD,OAAO,sBAAsB,CAAC;QAC5B,GAAG,OAAO;QACV,KAAK;QACL,cAAc;QACd,KAAK,CAAC,OAAO;YACX,MAAM,SAAS,GAAG,MAAM,mBAAmB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YACjE,OAAO;gBACL,SAAS;gBACT,MAAM,EAAE;oBACN,GAAG,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;oBACvD,OAAO;iBACR;gBACD,KAAK,CAAC,YAAY,CAAC,KAAK;oBACtB,MAAM,KAAK,GAAG,MAAM,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;oBACzD,MAAM,GAAG,GAAG,sBAAsB,CAAC,KAAK,CACtC,IAAI,CAAC,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAC5C,CAAC;oBACF,IACE,GAAG,CAAC,KAAK,KAAK,KAAK;wBACnB,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;wBAE7C,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;oBACnE,OAAO,SAAS,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;gBACjD,CAAC;aACF,CAAC;QACJ,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAyBD;;4EAE4E;AAC5E,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAA+B;IAE/B,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IACrE,MAAM,SAAS,GAAG,CAAC,GAAsB,EAAE,EAAE,CAC3C,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACnD,IAAI,KAAK,GAAG,MAAM,iBAAiB,EAAE,IAAI,CAAC;QACxC,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,KAAK;KACN,CAAC,CAAC;IACH,IAAI,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;IAC7C,MAAM,OAAO,CAAC,SAAS,EAAE,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;IACxC,SAAS,YAAY,CAAC,MAAc;QAClC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,2BAA2B,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACjE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,SAAS,aAAa;QACpB,IAAI,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;YAAE,OAAO;QACtC,YAAY,CAAC,gCAAgC,CAAC,CAAC;QAC/C,IAAI,OAAO,CAAC,2BAA2B,KAAK,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC;YACtE,MAAM,IAAI,2BAA2B,CACnC,KAAK,EACL,oDAAoD,CACrD,CAAC;IACN,CAAC;IACD,aAAa,EAAE,CAAC;IAChB,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;IACpE,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC;IACnC,MAAM,MAAM,GAAG,CAAC,OAAe,EAAE,EAAE,CACjC,cAAc,CAAC,SAAS,CAAC,GAAG,KAAK,IAAI,OAAO,EAAE,CAAC,CAAC;IAClD,KAAK,UAAU,aAAa,CAAC,OAAe;QAC1C,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7D,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IACD,KAAK,UAAU,MAAM,CACnB,OAAe,EACf,KAA2B,EAC3B,IAA0B;QAE1B,MAAM,OAAO,GAAG;YACd,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,KAAK;YACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,eAAe,EAAE,MAAM,CAAC,OAAO,CAAC;YAChC,SAAS,EAAE,MAAM,MAAM,CAAC,WAAW,CAAC;gBAClC,YAAY,EAAE,OAAO,CAAC,YAA6B;gBACnD,KAAK;gBACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,YAAY,EAAE,KAAK,CAAC,YAAY;gBAChC,eAAe,EAAE,OAAO;aACzB,CAAC;SACH,CAAC;QACF,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC9B,IAAI,aACkE,CAAC;QACvE,IAAI,OAAO,EAAE,CAAC;YACZ,IACE,CAAC,MAAM,CAAC,sBAAsB;gBAC9B,CAAC,CAAC,iBAAiB,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC;gBAE/C,MAAM,IAAI,KAAK,CACb,8BAA8B,KAAK,+EAA+E,CACnH,CAAC;YACJ,aAAa,GAAG;gBACd,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,gBAAgB,EAAE,MAAM,MAAM,CAAC,sBAAsB,CAAC;oBACpD,YAAY,EAAE,OAAO,CAAC,YAA6B;oBACnD,KAAK;oBACL,eAAe,EAAE,OAAO;oBACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,OAAO,EAAE,OAAO,CAAC,OAAO;iBACzB,CAAC;aACH,CAAC;QACJ,CAAC;QACD,IAAI,EAAsB,CAAC;QAC3B,IAAI,iBAAiB,EAAE,CAAC;YACtB,MAAM,QAAQ,GAAG,YAAY,CAAC,uBAAuB,CAAC,CAAC;YACvD,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,MAAM,CAAC;gBAC5C,GAAG,OAAO;gBACV,GAAG,aAAa;gBAChB,IAAI;gBACJ,KAAK,EAAE,QAAQ;aAChB,CAAC,CAAC;YACH,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;YACrC,IACE,MAAM,CAAC,KAAK,CAAC,UAAU,KAAK,QAAQ,CAAC,UAAU;gBAC/C,CAAC,UAAU;gBACX,SAAS,CAAC,UAAU,CAAC;gBACrB,UAAU,CAAC,eAAe,KAAK,MAAM,CAAC,OAAO,CAAC;gBAC9C,CAAC,QAAQ,CAAC,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC;gBAC9C,CAAC,QAAQ,CAAC,UAAU,CAAC,YAAY,EAAE,KAAK,CAAC,YAAY,CAAC;gBACtD,UAAU,CAAC,EAAE,KAAK,MAAM,CAAC,WAAW;gBAEpC,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;YACxE,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;YACrB,IAAI,GAAG,UAAU,CAAC;YAClB,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC;QAC1B,CAAC;aAAM,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;YAC5B,qEAAqE;YACrE,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC;QAChB,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,GAAG,aAAa;gBAC1B,CAAC,CAAC,MAAM,OAAO,CAAC,cAAe,CAAC,iBAAiB,CAAC;oBAC9C,GAAG,OAAO;oBACV,GAAG,aAAa;iBACjB,CAAC;gBACJ,CAAC,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;YACrD,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC;QAC1B,CAAC;QACD,IAAI,CAAC,EAAE;YACL,MAAM,IAAI,KAAK,CACb,8DAA8D,KAAK,YAAY,OAAO,EAAE,CACzF,CAAC;QACJ,OAAO;YACL,OAAO;YACP,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC;YACpB,WAAW,EAAE,EAAE;YACf,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,YAAY,EAAE,KAAK,CAAC,YAAY;SACjC,CAAC;IACJ,CAAC;IACD,0EAA0E;IAC1E,uEAAuE;IACvE,IAAI,OAAO,GACT,IAAI,KAAK,SAAS;QAChB,CAAC,CAAC,OAAO,CAAC,gBAAgB;QAC1B,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,IAAI,GAAG,CAAC,GAAG,EAAE,CAAC;IAChD,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC;QACpC,aAAa,EAAE,CAAC;QAChB,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,CAAC;YACpE,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;YACvC,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;YAC5B,IAAI,CAAC,CAAC,MAAM,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBACxC,sEAAsE;gBACtE,YAAY,CAAC,6CAA6C,CAAC,CAAC;gBAC5D,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC,YAAY,CAAC;oBACnD,MAAM,IAAI,KAAK,CACb,uEAAuE,CACxE,CAAC;gBACJ,IAAI,CAAC;oBACH,MAAM,cAAc,CAAC,MAAM,CAAC,GAAG,KAAK,IAAI,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;gBAChE,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,IAAI,CAAC,CAAC,KAAK,YAAY,uBAAuB,CAAC;wBAAE,MAAM,KAAK,CAAC;gBAC/D,CAAC;YACH,CAAC;YACD,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC;YAC3C,IACE,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC;gBACxC,CAAC,QAAQ,CAAC,KAAK,CAAC,YAAY,EAAE,IAAI,CAAC,YAAY,CAAC;gBAEhD,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;YAC7D,OAAO,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QACzC,CAAC;QACD,IAAI,KAAK;YAAE,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,eAAe,IAAI,GAAG,CAAC,GAAG,EAAE,CAAC;QAC/D,IAAI,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,OAAO;YACjD,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,EAAE,CAAC;QAC9C,IAAI,KAAK,GAAG,MAAM,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,cAAc,CAAC,MAAM,CAAC,GAAG,KAAK,IAAI,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;QAChE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,CAAC,KAAK,YAAY,uBAAuB,CAAC;gBAAE,MAAM,KAAK,CAAC;YAC7D,KAAK,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC;YACrC,oEAAoE;YACpE,mEAAmE;YACnE,+CAA+C;YAC/C,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC;gBACvC,YAAY,CAAC,2CAA2C,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;YACxD,IAAI,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC;gBAAE,OAAO,MAAM,CAAC;YACxD,mEAAmE;YACnE,uEAAuE;YACvE,OAAO,EAAE,CAAC;QACZ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IACE,iBAAiB;gBACjB,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;gBACzB,CAAC,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;gBAE3C,MAAM,KAAK,CAAC;YACd,IAAI,OAAO;gBAAE,MAAM,KAAK,CAAC;YACzB,OAAO,GAAG,IAAI,CAAC;YACf,IAAI,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;YAChC,MAAM,OAAO,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,CAAC;YAChC,aAAa,EAAE,CAAC;YAChB,MAAM,IAAI,GAAG,uBAAuB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACpD,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,IAAI;gBAAE,MAAM,KAAK,CAAC;YACxC,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,EAAE,eAAe,IAAI,GAAG,CAAC,GAAG,EAAE,CAAC;YAC/D,IAAI,IAAI,KAAK,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,YAAY;gBAC9C,YAAY,CACV,iEAAiE,CAClE,CAAC;YACJ,OAAO,GAAG,YAAY,CAAC;QACzB,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,8BAA8B,KAAK,oBAAoB,CAAC,CAAC;AAC3E,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAChE,IAAI,SAAS;QAAE,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3C,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC7D,IAAI,YAAY;QAAE,OAAO,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACrD,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,CAC/B,+CAA+C,CAChD,CAAC;IACF,OAAO,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACzD,CAAC"}

package/dist/replication/completion.d.ts

@@ -0,0 +1,20 @@
+import { type ReplicaOperation } from "./envelope.js";
+export type CompletionOperation = Extract<ReplicaOperation, {
+    kind: "stream-complete";
+}>;
+/** `sha256:<hex>` of an operation's canonical JSON, as completion dependencies pin it. */
+export declare function operationDigest(operation: ReplicaOperation): string;
+/**
+ * Dependency coverage only: every dependency has exactly one retained variant
+ * and it has the pinned digest. `variantDigests` returns the distinct digests
+ * of every retained variant of an operation id, across all connections. The
+ * rest of availability is `completionAvailability` in `visibility-engine.ts`.
+ */
+export declare function completionDependenciesCovered(completion: CompletionOperation, variantDigests: (writerId: string, operationId: string) => readonly string[]): boolean;
+/** Dependency coverage over a list of imported operations. */
+export declare function hasCompletionDependencies(completion: CompletionOperation, imported: readonly ReplicaOperation[]): Promise<boolean>;
+/** Select current receipt state for ONE validated stream/generation; this is not an availability check. */
+export declare function selectStreamCompletion(operations: readonly Extract<ReplicaOperation, {
+    kind: "stream-complete" | "stream-invalidate";
+}>[]): CompletionOperation | null;
+//# sourceMappingURL=completion.d.ts.map

package/dist/replication/completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../src/replication/completion.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AAIvB,MAAM,MAAM,mBAAmB,GAAG,OAAO,CACvC,gBAAgB,EAChB;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE,CAC5B,CAAC;AAEF,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,SAAS,EAAE,gBAAgB,GAAG,MAAM,CAEnE;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,mBAAmB,EAC/B,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,GAC3E,OAAO,CAMT;AAED,8DAA8D;AAC9D,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,mBAAmB,EAC/B,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GACpC,OAAO,CAAC,OAAO,CAAC,CAelB;AAED,2GAA2G;AAC3G,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,SAAS,OAAO,CAC1B,gBAAgB,EAChB;IAAE,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,CAAA;CAAE,CAClD,EAAE,GACF,mBAAmB,GAAG,IAAI,CA6B5B"}

package/dist/replication/completion.js

@@ -0,0 +1,73 @@
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex } from "@noble/hashes/utils";
+import { canonicalJson, declarationShape, replicaOperationSchema, } from "./envelope.js";
+import { compareRevisions } from "./revision.js";
+/** `sha256:<hex>` of an operation's canonical JSON, as completion dependencies pin it. */
+export function operationDigest(operation) {
+    return `sha256:${bytesToHex(sha256(new TextEncoder().encode(canonicalJson(operation))))}`;
+}
+/**
+ * Dependency coverage only: every dependency has exactly one retained variant
+ * and it has the pinned digest. `variantDigests` returns the distinct digests
+ * of every retained variant of an operation id, across all connections. The
+ * rest of availability is `completionAvailability` in `visibility-engine.ts`.
+ */
+export function completionDependenciesCovered(completion, variantDigests) {
+    if (completion.dependencies.length === 0)
+        return false;
+    return completion.dependencies.every((dependency) => {
+        const digests = variantDigests(dependency.writerId, dependency.operationId);
+        return digests.length === 1 && digests[0] === dependency.digest;
+    });
+}
+/** Dependency coverage over a list of imported operations. */
+export async function hasCompletionDependencies(completion, imported) {
+    replicaOperationSchema.parse(completion);
+    if (completion.dependencies.length === 0)
+        return false;
+    const byId = new Map();
+    for (const operation of imported) {
+        replicaOperationSchema.parse(operation);
+        const key = canonicalJson([
+            operation.revision.writerId,
+            operation.revision.operationId,
+        ]);
+        byId.set(key, (byId.get(key) ?? new Set()).add(operationDigest(operation)));
+    }
+    return completionDependenciesCovered(completion, (writerId, operationId) => [
+        ...(byId.get(canonicalJson([writerId, operationId])) ?? []),
+    ]);
+}
+/** Select current receipt state for ONE validated stream/generation; this is not an availability check. */
+export function selectStreamCompletion(operations) {
+    let identity;
+    let winner;
+    const byId = new Map();
+    for (const operation of operations) {
+        replicaOperationSchema.parse(operation);
+        const key = canonicalJson([
+            operation.owner,
+            operation.sourceId,
+            operation.connectionId,
+            operation.methodId,
+            operation.generation,
+            // Versions of one declared stream are one stream (a rebinding).
+            declarationShape(operation.declaration),
+        ]);
+        if (identity !== undefined && identity !== key)
+            throw new Error("mixed completion identities");
+        identity = key;
+        const id = canonicalJson([
+            operation.revision.writerId,
+            operation.revision.operationId,
+        ]);
+        const encoded = canonicalJson(operation);
+        if (byId.has(id) && byId.get(id) !== encoded)
+            return null;
+        byId.set(id, encoded);
+        if (!winner || compareRevisions(operation.revision, winner.revision) > 0)
+            winner = operation;
+    }
+    return winner?.kind === "stream-complete" ? winner : null;
+}
+//# sourceMappingURL=completion.js.map

package/dist/replication/completion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.js","sourceRoot":"","sources":["../../src/replication/completion.ts"],"names":[],"mappings":"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"}

package/dist/replication/coordinator-state.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The durable coordinator rotation over SQL, shared by every host. Node runs
+ * these effects synchronously inside the receiver's write transaction;
+ * PS-Lite runs them inside its native transaction. Both adapters pass
+ * `replicaCoordinatorStateContract`.
+ *
+ * Ownership is the token in `pdpp_transport_lock`. The adapter does NOT
+ * acquire or replace it: Node's PID lock and Lite's boot owner write it.
+ */
+import { type ReplicaEffect, type ReplicaEffectContext } from "./effects.js";
+import { type ReplicaCoordinatorState, type ReplicaRotation } from "./coordinator.js";
+/** Additive, idempotent forward open; no existing row/table is rewritten. */
+export declare const REPLICA_COORDINATOR_SCHEMA = "\nCREATE TABLE IF NOT EXISTS pdpp_transport_coordinator (\n  id INTEGER PRIMARY KEY CHECK(id=1),\n  version INTEGER NOT NULL DEFAULT 0 CHECK(version>=0),\n  rotation_json TEXT NOT NULL\n);\nINSERT OR IGNORE INTO pdpp_transport_coordinator(id,version,rotation_json)\n  VALUES(1,0,'{\"writers\":{}}');\n";
+/** The exclusive-owner table both hosts write. Node adds a PID; Lite writes 0. */
+export declare const REPLICA_LOCK_SCHEMA = "CREATE TABLE IF NOT EXISTS pdpp_transport_lock (id INTEGER PRIMARY KEY CHECK(id=1), pid INTEGER NOT NULL, token TEXT NOT NULL);";
+/** Who this adapter acts for; read at every check, never cached. */
+export type ReplicaCoordinatorOwner = () => string | undefined;
+/** The current rotation, only for the owner that holds the lock. */
+export declare function loadReplicaCoordinatorState(owner: ReplicaCoordinatorOwner): ReplicaEffect<ReplicaCoordinatorState>;
+/**
+ * Check owner and revision, run `checkpoint`, check the owner again, then
+ * write the rotation at the next revision. The caller runs this whole effect
+ * in ONE write transaction, so any throw rolls back checkpoint and rotation.
+ */
+export declare function commitReplicaCoordinatorState<T, C extends ReplicaEffectContext = ReplicaEffectContext>(owner: ReplicaCoordinatorOwner, expected: ReplicaCoordinatorState, next: ReplicaRotation, checkpoint: (context: C) => T | Promise<T>): ReplicaEffect<{
+    state: ReplicaCoordinatorState;
+    result: T;
+}, C>;
+//# sourceMappingURL=coordinator-state.d.ts.map

package/dist/replication/coordinator-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator-state.d.ts","sourceRoot":"","sources":["../../src/replication/coordinator-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACrB,MAAM,kBAAkB,CAAC;AAE1B,6EAA6E;AAC7E,eAAO,MAAM,0BAA0B,kTAQtC,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,oIACmG,CAAC;AA4BpI,oEAAoE;AACpE,MAAM,MAAM,uBAAuB,GAAG,MAAM,MAAM,GAAG,SAAS,CAAC;AAY/D,oEAAoE;AACpE,wBAAiB,2BAA2B,CAC1C,KAAK,EAAE,uBAAuB,GAC7B,aAAa,CAAC,uBAAuB,CAAC,CAUxC;AAED;;;;GAIG;AACH,wBAAiB,6BAA6B,CAC5C,CAAC,EACD,CAAC,SAAS,oBAAoB,GAAG,oBAAoB,EAErD,KAAK,EAAE,uBAAuB,EAC9B,QAAQ,EAAE,uBAAuB,EACjC,IAAI,EAAE,eAAe,EACrB,UAAU,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACzC,aAAa,CAAC;IAAE,KAAK,EAAE,uBAAuB,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,EAAE,CAAC,CAAC,CA0BjE"}

package/dist/replication/coordinator-state.js

@@ -0,0 +1,88 @@
+/**
+ * The durable coordinator rotation over SQL, shared by every host. Node runs
+ * these effects synchronously inside the receiver's write transaction;
+ * PS-Lite runs them inside its native transaction. Both adapters pass
+ * `replicaCoordinatorStateContract`.
+ *
+ * Ownership is the token in `pdpp_transport_lock`. The adapter does NOT
+ * acquire or replace it: Node's PID lock and Lite's boot owner write it.
+ */
+import { perform, sql, } from "./effects.js";
+import { ReplicaCoordinatorConflict, } from "./coordinator.js";
+/** Additive, idempotent forward open; no existing row/table is rewritten. */
+export const REPLICA_COORDINATOR_SCHEMA = `
+CREATE TABLE IF NOT EXISTS pdpp_transport_coordinator (
+  id INTEGER PRIMARY KEY CHECK(id=1),
+  version INTEGER NOT NULL DEFAULT 0 CHECK(version>=0),
+  rotation_json TEXT NOT NULL
+);
+INSERT OR IGNORE INTO pdpp_transport_coordinator(id,version,rotation_json)
+  VALUES(1,0,'{"writers":{}}');
+`;
+/** The exclusive-owner table both hosts write. Node adds a PID; Lite writes 0. */
+export const REPLICA_LOCK_SCHEMA = "CREATE TABLE IF NOT EXISTS pdpp_transport_lock (id INTEGER PRIMARY KEY CHECK(id=1), pid INTEGER NOT NULL, token TEXT NOT NULL);";
+const PHASES = new Set([
+    "retain",
+    "prepare",
+    "publish",
+    "discover",
+    "download",
+    "fetch",
+    "revalidate",
+    "import",
+    "reconcile",
+]);
+function validate(rotation) {
+    if (!rotation ||
+        !rotation.writers ||
+        typeof rotation.writers !== "object" ||
+        Array.isArray(rotation.writers) ||
+        (rotation.nextPhase !== undefined && !PHASES.has(rotation.nextPhase)) ||
+        Object.entries(rotation.writers).some(([phase, writer]) => !PHASES.has(phase) || typeof writer !== "string"))
+        throw new Error("invalid replica coordinator rotation");
+}
+function* currentOwner(owner) {
+    const current = owner();
+    const held = yield* sql.get("SELECT token FROM pdpp_transport_lock WHERE id=1");
+    if (!current || held?.token !== current)
+        throw new ReplicaCoordinatorConflict();
+    return current;
+}
+/** The current rotation, only for the owner that holds the lock. */
+export function* loadReplicaCoordinatorState(owner) {
+    const held = yield* currentOwner(owner);
+    const row = yield* sql.get("SELECT version,rotation_json FROM pdpp_transport_coordinator WHERE id=1");
+    if (!row || !Number.isSafeInteger(row.version) || row.version < 0)
+        throw new Error("invalid replica coordinator revision");
+    const rotation = JSON.parse(row.rotation_json);
+    validate(rotation);
+    return { ...rotation, owner: held, version: row.version };
+}
+/**
+ * Check owner and revision, run `checkpoint`, check the owner again, then
+ * write the rotation at the next revision. The caller runs this whole effect
+ * in ONE write transaction, so any throw rolls back checkpoint and rotation.
+ */
+export function* commitReplicaCoordinatorState(owner, expected, next, checkpoint) {
+    const current = yield* loadReplicaCoordinatorState(owner);
+    if (current.owner !== expected.owner || current.version !== expected.version)
+        throw new ReplicaCoordinatorConflict();
+    if (expected.version === Number.MAX_SAFE_INTEGER)
+        throw new RangeError("replica coordinator revision exhausted");
+    validate(next);
+    const result = yield* perform(checkpoint);
+    // Even a nested callback cannot replace the owner and leave a receipt.
+    if ((yield* currentOwner(owner)) !== expected.owner)
+        throw new ReplicaCoordinatorConflict();
+    const { changes } = yield* sql.run(`UPDATE pdpp_transport_coordinator
+          SET version=version+1,rotation_json=? WHERE id=1 AND version=?`, JSON.stringify(next), expected.version);
+    if (changes !== 1)
+        throw new ReplicaCoordinatorConflict();
+    const state = yield* loadReplicaCoordinatorState(owner);
+    if (state.version !== expected.version + 1 ||
+        state.nextPhase !== next.nextPhase ||
+        JSON.stringify(state.writers) !== JSON.stringify(next.writers))
+        throw new ReplicaCoordinatorConflict();
+    return { state, result };
+}
+//# sourceMappingURL=coordinator-state.js.map

package/dist/replication/coordinator-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator-state.js","sourceRoot":"","sources":["../../src/replication/coordinator-state.ts"],"names":[],"mappings":"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"}

package/dist/replication/coordinator-state.test-utils.d.ts

@@ -0,0 +1,32 @@
+import { type AsyncReplicaCoordinatorStatePort, type ReplicaCoordinatorStatePort } from "./coordinator.js";
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * One harness per adapter: Node's synchronous SQLite port and PS-Lite's
+ * asynchronous native-transaction port run this same contract. `context` is
+ * the port's open transaction, passed to calls made inside a checkpoint; a
+ * synchronous port passes `undefined`.
+ */
+export interface ReplicaCoordinatorContractHarness<C = unknown> {
+    port(owner: string): ReplicaCoordinatorStatePort | AsyncReplicaCoordinatorStatePort<C>;
+    acquire(owner: string): MaybePromise<void>;
+    /** Simulate confirmed loss of the old exclusive owner, not lease expiry. */
+    recover(owner: string, context?: C): MaybePromise<void>;
+    checkpoint(value: string, context?: C): MaybePromise<void>;
+    receipts(): MaybePromise<string[]>;
+    failCursorWrites(fail: boolean): MaybePromise<void>;
+    close(): MaybePromise<void>;
+}
+/**
+ * The caller injects its test runner's `test` and `expect` so this module stays
+ * free of Node built-ins and test-runner imports (core must stay browser-safe).
+ */
+export interface ReplicaCoordinatorContractRunner {
+    test(name: string, run: () => Promise<void>): void;
+    expect(actual: unknown): {
+        toBe(expected: unknown): void;
+        toEqual(expected: unknown): void;
+    };
+}
+export declare function replicaCoordinatorStateContract<C>({ test, expect }: ReplicaCoordinatorContractRunner, open: () => MaybePromise<ReplicaCoordinatorContractHarness<C>>): void;
+export {};
+//# sourceMappingURL=coordinator-state.test-utils.d.ts.map

package/dist/replication/coordinator-state.test-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator-state.test-utils.d.ts","sourceRoot":"","sources":["../../src/replication/coordinator-state.test-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gCAAgC,EAErC,KAAK,2BAA2B,EAEjC,MAAM,kBAAkB,CAAC;AAE1B,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAMtC;;;;;GAKG;AACH,MAAM,WAAW,iCAAiC,CAAC,CAAC,GAAG,OAAO;IAC5D,IAAI,CACF,KAAK,EAAE,MAAM,GACZ,2BAA2B,GAAG,gCAAgC,CAAC,CAAC,CAAC,CAAC;IACrE,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC3C,4EAA4E;IAC5E,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACxD,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC3D,QAAQ,IAAI,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC;IACnC,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACpD,KAAK,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,gCAAgC;IAC/C,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACnD,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG;QACvB,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;QAC9B,OAAO,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;KAClC,CAAC;CACH;AAED,wBAAgB,+BAA+B,CAAC,CAAC,EAC/C,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,gCAAgC,EAClD,IAAI,EAAE,MAAM,YAAY,CAAC,iCAAiC,CAAC,CAAC,CAAC,CAAC,GAC7D,IAAI,CAoKN"}