crypto-aio 0.0.2 → 0.1.0

package/dist/testing/contracts/operations.js

@@ -0,0 +1,718 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SAMPLE_ORDERINGS = void 0;
+exports.sampleOperation = sampleOperation;
+exports.sampleAttempt = sampleAttempt;
+exports.describeOperationStoreContract = describeOperationStoreContract;
+const strict_1 = __importDefault(require("node:assert/strict"));
+const api_1 = require("./api");
+/**
+ * Narrows a `Promise.allSettled` result to its rejected variant, so a batch of
+ * promises that are expected to include failures can be driven with a single
+ * `Promise.allSettled` (a bare `Promise.all` would short-circuit on the first
+ * rejection and discard the others) and then inspected without repeated casts.
+ */
+function isRejected(result) {
+    return result.status === 'rejected';
+}
+let counter = 0;
+function sampleOperation(overrides = {}) {
+    counter += 1;
+    return {
+        id: `op_contract_${counter}`,
+        namespace: 'ns',
+        idempotencyKey: `key-${counter}`,
+        intentHash: 'hash',
+        context: {
+            chain: 'c',
+            network: 'n',
+            library: 'lib',
+            providers: ['p'],
+            indexers: [],
+            wallet: 'w',
+            configHash: 'cfg',
+        },
+        kind: 'transfer',
+        state: 'created',
+        intent: {
+            assetId: 'c:n/native',
+            asset: 'native',
+            outputs: [{ to: 'to', amount: 10n }],
+            from: 'from',
+            fee: 'normal',
+        },
+        attempts: [],
+        ...overrides,
+    };
+}
+function sampleAttempt(id, overrides = {}) {
+    const fee = {
+        kind: 'x',
+        speed: 'normal',
+        charges: [{ asset: 'native', amount: 1n, label: 'network' }],
+        bound: 'exact',
+        details: {},
+    };
+    return {
+        id,
+        ref: { id: `ref-${id}`, idKind: 'tx-hash', canonical: true },
+        raw: { encoding: 'hex', data: '00' },
+        ordering: { kind: 'nonce', nonce: 7n },
+        fee,
+        unsigned: {
+            payload: { encoding: 'hex', data: '00' },
+            signingRequests: [
+                {
+                    id: 'r0',
+                    scheme: 'secp256k1-ecdsa',
+                    payload: new Uint8Array([1, 2]),
+                    payloadKind: 'digest',
+                    publicKey: new Uint8Array([3]),
+                },
+            ],
+            ordering: { kind: 'nonce', nonce: 7n },
+            fee,
+            summary: { asset: 'c:n/native', outputs: [] },
+        },
+        purpose: 'original',
+        createdAt: 1,
+        ...overrides,
+    };
+}
+/**
+ * An ordering of each kind the built-in families record, with each family's own
+ * properties. Proofs read these facts from the stored ordering, never from signed bytes,
+ * so a store must keep every one whole: a dropped property costs liveness, but a changed
+ * one (a `refBlockHash`, a `blockhash`, a `validFrom` moved later, a bigint narrowed to a
+ * number) can prove a transaction absent while a block holds it, and `rebuild` then pays
+ * twice. The bigints exceed 2^53. The core's `OrderingData` does not name these fields:
+ * each family exports its typed ordering, and this contract pins that a store keeps them.
+ */
+exports.SAMPLE_ORDERINGS = Object.freeze([
+    ['an EVM nonce', { kind: 'nonce', nonce: 2n ** 64n - 1n }],
+    [
+        'UTXO inputs',
+        {
+            kind: 'inputs',
+            inputs: [`${'ab'.repeat(32)}:0`, `${'cd'.repeat(32)}:4294967295`],
+        },
+    ],
+    [
+        'a Tron expiry',
+        {
+            kind: 'expiry',
+            expiresAtMs: 1_790_000_000_123,
+            lastValidHeight: 2n ** 53n + 65537n,
+            refBlockHash: '0a1b2c3d4e5f6071',
+        },
+    ],
+    [
+        'a Solana expiry',
+        {
+            kind: 'expiry',
+            lastValidHeight: 2n ** 63n + 150n,
+            blockhash: 'GHtXQBsoZHVnNFa9YevAzFr17DJjgHXk3ycTKD5xD3Zi',
+            blockhashSlot: 2n ** 53n + 1n,
+        },
+    ],
+    [
+        'a TON seqno',
+        {
+            kind: 'seqno',
+            seqno: 2n ** 32n - 1n,
+            validUntil: 1_790_000_060,
+            validFrom: 1_789_999_700,
+        },
+    ],
+]);
+/** Every property of `expected`, and no other, with the same value and type. */
+function assertWholeOrdering(actual, expected, where) {
+    strict_1.default.ok(actual !== null && typeof actual === 'object', `${where}: missing`);
+    const got = actual;
+    strict_1.default.deepEqual(Object.keys(got).sort(), Object.keys(expected).sort(), `${where}: properties`);
+    for (const [key, value] of Object.entries(expected)) {
+        strict_1.default.equal(typeof got[key], typeof value, `${where}.${key}: type`);
+        strict_1.default.deepEqual(got[key], value, `${where}.${key}: value`);
+    }
+}
+function describeOperationStoreContract(api, create) {
+    api.describe('OperationStore contract', () => {
+        api.it('creates if absent on (namespace, idempotencyKey)', async () => {
+            const { operations } = await create();
+            const first = await operations.create(sampleOperation({ idempotencyKey: 'same' }));
+            strict_1.default.equal(first.created, true);
+            strict_1.default.equal(first.record.version, 1);
+            const second = await operations.create(sampleOperation({ idempotencyKey: 'same' }));
+            strict_1.default.equal(second.created, false);
+            strict_1.default.equal(second.record.id, first.record.id);
+            const otherNs = await operations.create(sampleOperation({ idempotencyKey: 'same', namespace: 'other' }));
+            strict_1.default.equal(otherNs.created, true);
+            strict_1.default.equal((await operations.getByKey('ns', 'same'))?.id, first.record.id);
+            strict_1.default.equal(await operations.get('ns', 'missing'), null);
+            strict_1.default.equal(await operations.getByKey('ns', 'missing'), null);
+        });
+        api.it('rejects create when the runtime input carries a store-owned field, storing nothing', async () => {
+            const { operations } = await create();
+            const forbidden = {
+                claim: { workerId: 'w', token: '1', until: 1 },
+                version: 1,
+                createdAt: 1,
+                updatedAt: 1,
+            };
+            for (const key of Object.keys(forbidden)) {
+                const operation = {
+                    ...sampleOperation(),
+                    [key]: forbidden[key],
+                };
+                await (0, api_1.rejectsWithCode)(operations.create(operation), 'INVALID_TRANSITION');
+                strict_1.default.equal(await operations.get(operation.namespace, operation.id), null);
+                strict_1.default.equal(await operations.getByKey(operation.namespace, operation.idempotencyKey), null);
+            }
+        });
+        api.it('updates with compare-and-set versions and clears fields', async () => {
+            const { operations } = await create();
+            const { record } = await operations.create(sampleOperation());
+            const updated = await operations.update('ns', record.id, {
+                state: 'prepared',
+                reservation: { kind: 'nonce', nonce: 3n },
+                error: {
+                    name: 'E',
+                    code: 'TIMEOUT',
+                    category: 'timeout',
+                    message: 'm',
+                    retryable: true,
+                    ambiguous: false,
+                    context: {},
+                },
+            }, 1);
+            strict_1.default.equal(updated.version, 2);
+            strict_1.default.equal(updated.state, 'prepared');
+            await (0, api_1.rejectsWithCode)(operations.update('ns', record.id, { state: 'signed' }, 1), 'VERSION_CONFLICT');
+            await (0, api_1.rejectsWithCode)(operations.update('ns', 'missing', { state: 'signed' }, 1), 'NOT_FOUND');
+            const cleared = await operations.update('ns', record.id, { clear: ['reservation', 'error'] }, 2);
+            strict_1.default.equal(cleared.reservation, undefined);
+            strict_1.default.equal(cleared.error, undefined);
+            strict_1.default.equal(cleared.state, 'prepared');
+        });
+        api.it('bumps the version on every successful update, even one that changes nothing', async () => {
+            // The engine fences a stale writer with a no-effect compare-and-set; a store
+            // that skipped writing an unchanged record would let the stale write land.
+            const { operations } = await create();
+            const { record } = await operations.create(sampleOperation());
+            strict_1.default.equal(record.error, undefined);
+            const bumped = await operations.update('ns', record.id, { clear: ['error'] }, record.version);
+            strict_1.default.equal(bumped.version, record.version + 1);
+            await (0, api_1.rejectsWithCode)(operations.update('ns', record.id, { state: 'prepared' }, record.version), 'VERSION_CONFLICT');
+        });
+        api.it('appends attempts atomically with the state change', async () => {
+            const { operations } = await create();
+            const { record } = await operations.create(sampleOperation());
+            const next = await operations.appendAttempt('ns', record.id, sampleAttempt('a1'), { state: 'signed' }, 1);
+            strict_1.default.equal(next.version, 2);
+            strict_1.default.equal(next.state, 'signed');
+            strict_1.default.equal(next.activeAttemptId, 'a1');
+            strict_1.default.equal(next.attempts.length, 1);
+            await (0, api_1.rejectsWithCode)(operations.appendAttempt('ns', record.id, sampleAttempt('a1'), {}, 2), 'INVALID_TRANSITION');
+            const stored = await operations.get('ns', record.id);
+            const request = stored?.attempts[0]?.unsigned.signingRequests[0];
+            strict_1.default.deepEqual(request?.payload, new Uint8Array([1, 2]));
+            const ordering = stored?.attempts[0]?.ordering;
+            strict_1.default.equal(ordering?.kind === 'nonce' ? ordering.nonce : undefined, 7n);
+        });
+        api.it('keeps every ordering whole: each property, with its value and its type', async () => {
+            const { operations } = await create();
+            for (const [name, ordering] of exports.SAMPLE_ORDERINGS) {
+                const { record } = await operations.create(sampleOperation());
+                const sample = sampleAttempt('a1');
+                const appended = await operations.appendAttempt('ns', record.id, { ...sample, ordering, unsigned: { ...sample.unsigned, ordering } }, { state: 'signed', reservation: ordering }, record.version);
+                // Read back after the append, and again after a later write to the record.
+                const stored = await operations.get('ns', record.id);
+                const updated = await operations.update('ns', record.id, { state: 'submitted' }, appended.version);
+                const reread = await operations.get('ns', record.id);
+                for (const [when, read] of [
+                    ['appendAttempt', appended],
+                    ['get', stored],
+                    ['update', updated],
+                    ['get after update', reread],
+                ]) {
+                    const where = `${name} (${when})`;
+                    assertWholeOrdering(read?.attempts[0]?.ordering, ordering, `${where} ordering`);
+                    assertWholeOrdering(read?.attempts[0]?.unsigned.ordering, ordering, `${where} unsigned.ordering`);
+                    assertWholeOrdering(read?.reservation, ordering, `${where} reservation`);
+                }
+            }
+        });
+        api.it('isolates returned records from the store', async () => {
+            const { operations } = await create();
+            const { record } = await operations.create(sampleOperation());
+            record.intent.outputs.push({
+                to: 'x',
+                amount: 1n,
+            });
+            strict_1.default.equal((await operations.get('ns', record.id))?.intent.outputs.length, 1);
+        });
+        api.it('versions observations and finds operations by ref or tx hash', async () => {
+            const { operations } = await create();
+            const { record } = await operations.create(sampleOperation());
+            await operations.appendAttempt('ns', record.id, sampleAttempt('a2'), { state: 'signed' }, 1);
+            const base = {
+                attemptId: 'a2',
+                operationId: record.id,
+                state: 'included',
+                evidence: 'observed',
+                confirmations: 1,
+                txHash: 'canonical-hash',
+                blockHeight: 2n ** 40n,
+            };
+            const obs = await operations.putObservation(base, null);
+            strict_1.default.equal(obs.version, 1);
+            await (0, api_1.rejectsWithCode)(operations.putObservation(base, null), 'VERSION_CONFLICT');
+            strict_1.default.equal((await operations.putObservation({ ...base, confirmations: 2 }, 1)).version, 2);
+            strict_1.default.equal((await operations.getObservation('a2'))?.blockHeight, 2n ** 40n);
+            strict_1.default.equal((await operations.findByRef('ns', 'ref-a2'))?.id, record.id);
+            strict_1.default.equal((await operations.findByRef('ns', 'canonical-hash'))?.id, record.id);
+            strict_1.default.equal(await operations.findByRef('other', 'ref-a2'), null);
+        });
+        api.it('replaces an observation whole: a key left out or set to undefined reads back undefined (never null)', async () => {
+            // The core clears a stale reason or block by leaving it out or setting
+            // it to undefined. A store that merged records, or kept undefined as a value such as
+            // null, would return a stale or wrong field.
+            const { operations } = await create();
+            const { record } = await operations.create(sampleOperation());
+            await operations.appendAttempt('ns', record.id, sampleAttempt('a3'), { state: 'signed' }, 1);
+            const failed = await operations.putObservation({
+                attemptId: 'a3',
+                operationId: record.id,
+                state: 'failed',
+                evidence: 'observed',
+                confirmations: 1,
+                blockHeight: 7n,
+                blockHash: 'block-7',
+                reason: 'transfer bounced',
+            }, null);
+            await operations.putObservation({
+                attemptId: 'a3',
+                operationId: record.id,
+                state: 'pending',
+                evidence: 'observed',
+                confirmations: 0,
+                reason: undefined,
+            }, failed.version);
+            const reread = await operations.getObservation('a3');
+            strict_1.default.equal(reread?.state, 'pending');
+            strict_1.default.equal(reread?.blockHeight, undefined);
+            strict_1.default.equal(reread?.blockHash, undefined);
+            strict_1.default.equal(reread?.reason, undefined);
+        });
+        api.it('claims due operations exclusively and fences stale workers', async () => {
+            const { operations } = await create();
+            const a = (await operations.create(sampleOperation({ state: 'submitted', nextCheckAt: 100 }))).record;
+            const b = (await operations.create(sampleOperation({ state: 'submitted', nextCheckAt: 100 }))).record;
+            await operations.create(sampleOperation({ state: 'final', nextCheckAt: 100 }));
+            await operations.create(sampleOperation({ state: 'submitted', nextCheckAt: 10_000 }));
+            // Unscheduled operations (no nextCheckAt) are still being built or signed: never due.
+            await operations.create(sampleOperation({ state: 'prepared' }));
+            const w1 = await operations.claimDue('ns', 'w1', 1_000, 500, 1);
+            const w2 = await operations.claimDue('ns', 'w2', 1_000, 500, 10);
+            strict_1.default.equal(w1.length, 1);
+            strict_1.default.equal(w2.length, 1);
+            strict_1.default.notEqual(w1[0]?.id, w2[0]?.id);
+            strict_1.default.deepEqual(new Set([w1[0]?.id, w2[0]?.id]), new Set([a.id, b.id]));
+            strict_1.default.equal((await operations.claimDue('ns', 'w3', 1_200, 500, 10)).length, 0);
+            const staleClaim = w1[0];
+            const retaken = await operations.claimDue('ns', 'w3', 1_600, 500, 10);
+            const takeover = retaken.find((r) => r.id === staleClaim.id);
+            strict_1.default.ok(takeover);
+            strict_1.default.ok(BigInt(takeover.claim.token) > BigInt(staleClaim.claim.token));
+            await (0, api_1.rejectsWithCode)(operations.update('ns', staleClaim.id, { nextCheckAt: 5 }, takeover.version, {
+                claimToken: staleClaim.claim.token,
+            }), 'FENCING');
+            await (0, api_1.rejectsWithCode)(operations.releaseClaim('ns', staleClaim.id, {
+                claimToken: staleClaim.claim.token,
+            }), 'FENCING');
+            await operations.releaseClaim('ns', staleClaim.id, {
+                claimToken: takeover.claim.token,
+            });
+            strict_1.default.equal((await operations.get('ns', staleClaim.id))?.claim, undefined);
+        });
+        api.it('lists by filter in creation order', async () => {
+            const { operations } = await create();
+            const one = (await operations.create(sampleOperation({
+                namespace: 'list',
+                intent: { ...sampleOperation().intent, from: 'alice' },
+            }))).record;
+            await operations.create(sampleOperation({
+                namespace: 'list',
+                state: 'final',
+                intent: { ...sampleOperation().intent, from: 'alice' },
+            }));
+            await operations.create(sampleOperation({
+                namespace: 'list',
+                intent: { ...sampleOperation().intent, from: 'bob' },
+            }));
+            const alice = await operations.list({
+                namespace: 'list',
+                from: 'alice',
+                states: ['created'],
+            });
+            strict_1.default.deepEqual(alice.map((r) => r.id), [one.id]);
+            strict_1.default.equal((await operations.list({ namespace: 'list' })).length, 3);
+            strict_1.default.equal((await operations.list({ namespace: 'list', limit: 2 })).length, 2);
+        });
+        api.it('rejects patch fields outside the writable whitelist, leaving the record unchanged', async () => {
+            const { operations } = await create();
+            const created = await operations.create(sampleOperation());
+            const afterAppend = await operations.appendAttempt('ns', created.record.id, sampleAttempt('w1'), { state: 'signed' }, 1);
+            const snapshot = await operations.get('ns', created.record.id);
+            await (0, api_1.rejectsWithCode)(operations.update('ns', created.record.id, { attempts: [] }, afterAppend.version), 'INVALID_TRANSITION');
+            strict_1.default.deepEqual(await operations.get('ns', created.record.id), snapshot);
+            await (0, api_1.rejectsWithCode)(operations.update('ns', created.record.id, {
+                claim: undefined,
+                state: 'submitted',
+                ...{ id: 'x' },
+            }, afterAppend.version), 'INVALID_TRANSITION');
+            strict_1.default.deepEqual(await operations.get('ns', created.record.id), snapshot);
+            await (0, api_1.rejectsWithCode)(operations.update('ns', created.record.id, { clear: ['attempts', 'claim'] }, afterAppend.version), 'INVALID_TRANSITION');
+            strict_1.default.deepEqual(await operations.get('ns', created.record.id), snapshot);
+        });
+        api.it("rejects appendAttempt's patch fields outside the writable whitelist, leaving the record unchanged", async () => {
+            const { operations } = await create();
+            const created = await operations.create(sampleOperation());
+            const snapshot = await operations.get('ns', created.record.id);
+            await (0, api_1.rejectsWithCode)(operations.appendAttempt('ns', created.record.id, sampleAttempt('wl1'), { attempts: [] }, 1), 'INVALID_TRANSITION');
+            strict_1.default.deepEqual(await operations.get('ns', created.record.id), snapshot);
+            await (0, api_1.rejectsWithCode)(operations.appendAttempt('ns', created.record.id, sampleAttempt('wl2'), {
+                claim: undefined,
+                state: 'submitted',
+                ...{ id: 'x' },
+            }, 1), 'INVALID_TRANSITION');
+            strict_1.default.deepEqual(await operations.get('ns', created.record.id), snapshot);
+            await (0, api_1.rejectsWithCode)(operations.appendAttempt('ns', created.record.id, sampleAttempt('wl3'), { clear: ['attempts', 'claim'] }, 1), 'INVALID_TRANSITION');
+            strict_1.default.deepEqual(await operations.get('ns', created.record.id), snapshot);
+        });
+        api.it('rejects a clear that is not an array, leaving the record unchanged', async () => {
+            // A serialized store cannot read a number, an object or a Set as a list either;
+            // reading one as `[]` would let a malformed patch commit as if it cleared nothing.
+            const { operations } = await create();
+            const created = await operations.create(sampleOperation());
+            const snapshot = await operations.get('ns', created.record.id);
+            for (const clear of [5, {}, null, 'error', new Set(['error'])]) {
+                const patch = { state: 'prepared', clear };
+                await (0, api_1.rejectsWithCode)(operations.update('ns', created.record.id, patch, 1), 'INVALID_TRANSITION');
+                strict_1.default.deepEqual(await operations.get('ns', created.record.id), snapshot);
+                await (0, api_1.rejectsWithCode)(operations.appendAttempt('ns', created.record.id, sampleAttempt('n7'), patch, 1), 'INVALID_TRANSITION');
+                strict_1.default.deepEqual(await operations.get('ns', created.record.id), snapshot);
+            }
+        });
+        api.it('keeps the idempotency key and the wallet address out of its errors', async () => {
+            // Both are `sensitive` data, and error messages reach logs.
+            const { operations } = await create();
+            const from = 'TRonWa11etAddre55C0ffee000000000000';
+            const idempotencyKey = 'withdrawal-7f3a9c-customer-4417';
+            const secrets = [from, idempotencyKey];
+            const operation = sampleOperation({
+                idempotencyKey,
+                state: 'submitted',
+                nextCheckAt: 100,
+                intent: { ...sampleOperation().intent, from },
+            });
+            const { record } = await operations.create(operation);
+            await (0, api_1.rejectsWithCodeKeepingOut)(operations.create({ ...operation, idempotencyKey: 'another-key' }), 'INVALID_TRANSITION', secrets);
+            await (0, api_1.rejectsWithCodeKeepingOut)(operations.update('ns', record.id, { state: 'prepared' }, 9), 'VERSION_CONFLICT', secrets);
+            await (0, api_1.rejectsWithCodeKeepingOut)(operations.update('ns', record.id, { idempotencyKey: 'x' }, record.version), 'INVALID_TRANSITION', secrets);
+            const appended = await operations.appendAttempt('ns', record.id, sampleAttempt('k1'), {}, record.version);
+            await (0, api_1.rejectsWithCodeKeepingOut)(operations.appendAttempt('ns', record.id, sampleAttempt('k1'), {}, appended.version), 'INVALID_TRANSITION', secrets);
+            await (0, api_1.rejectsWithCodeKeepingOut)(operations.appendAttempt('ns', record.id, sampleAttempt('k2'), {}, 1), 'VERSION_CONFLICT', secrets);
+            const [stale] = await operations.claimDue('ns', 'w1', 1_000, 500, 10);
+            await operations.claimDue('ns', 'w2', 1_600, 500, 10);
+            const current = await operations.get('ns', record.id);
+            await (0, api_1.rejectsWithCodeKeepingOut)(operations.update('ns', record.id, {}, current.version, {
+                claimToken: stale.claim.token,
+            }), 'FENCING', secrets);
+        });
+        api.it('purges what the filter matches and nothing else, when it implements purge', async () => {
+            const { operations } = await create();
+            if (operations.purge === undefined)
+                return;
+            const done = (await operations.create(sampleOperation({ namespace: 'purge', state: 'final' }))).record;
+            await operations.appendAttempt('purge', done.id, sampleAttempt('p1'), {}, done.version);
+            await operations.putObservation({
+                attemptId: 'p1',
+                operationId: done.id,
+                state: 'included',
+                evidence: 'proven',
+                confirmations: 3,
+                txHash: 'purged-hash',
+            }, null);
+            const live = (await operations.create(sampleOperation({ namespace: 'purge', state: 'submitted' }))).record;
+            const elsewhere = (await operations.create(sampleOperation({ namespace: 'kept', state: 'final' }))).record;
+            const liveBefore = await operations.get('purge', live.id);
+            const elsewhereBefore = await operations.get('kept', elsewhere.id);
+            strict_1.default.equal(await operations.purge({ namespace: 'purge', states: ['final'] }), 1);
+            strict_1.default.equal(await operations.get('purge', done.id), null);
+            strict_1.default.equal(await operations.getByKey('purge', done.idempotencyKey), null);
+            strict_1.default.equal(await operations.findByRef('purge', 'ref-p1'), null);
+            strict_1.default.equal(await operations.findByRef('purge', 'purged-hash'), null);
+            strict_1.default.equal(await operations.getObservation('p1'), null);
+            strict_1.default.deepEqual(await operations.get('purge', live.id), liveBefore);
+            strict_1.default.deepEqual(await operations.get('kept', elsewhere.id), elsewhereBefore);
+            // The idempotency key is free again: a new Operation may take it.
+            const again = await operations.create(sampleOperation({
+                namespace: 'purge',
+                idempotencyKey: done.idempotencyKey,
+                id: `${done.id}-again`,
+            }));
+            strict_1.default.equal(again.created, true);
+            strict_1.default.equal(await operations.purge({ namespace: 'empty' }), 0);
+        });
+        api.it('purges at most limit records, the oldest first, when it implements purge', async () => {
+            const { operations } = await create();
+            if (operations.purge === undefined)
+                return;
+            const ids = [];
+            for (let i = 0; i < 3; i += 1) {
+                const { record } = await operations.create(sampleOperation({ namespace: 'purge-limit', state: 'failed' }));
+                ids.push(record.id);
+            }
+            strict_1.default.equal(await operations.purge({ namespace: 'purge-limit', limit: 2 }), 2);
+            strict_1.default.deepEqual((await operations.list({ namespace: 'purge-limit' })).map((r) => r.id), [ids[2]]);
+            strict_1.default.equal(await operations.purge({ namespace: 'purge-limit', limit: 0 }), 0);
+            strict_1.default.equal((await operations.list({ namespace: 'purge-limit' })).length, 1);
+        });
+        api.it('rejects appendAttempt with a duplicate id even when the content differs, leaving the record unchanged', async () => {
+            const { operations } = await create();
+            const created = await operations.create(sampleOperation());
+            const afterFirst = await operations.appendAttempt('ns', created.record.id, sampleAttempt('dup'), { state: 'signed' }, 1);
+            const snapshot = await operations.get('ns', created.record.id);
+            await (0, api_1.rejectsWithCode)(operations.appendAttempt('ns', created.record.id, sampleAttempt('dup', {
+                purpose: 'replacement',
+                raw: { encoding: 'hex', data: 'ff' },
+            }), { state: 'failed' }, afterFirst.version), 'INVALID_TRANSITION');
+            const after = await operations.get('ns', created.record.id);
+            strict_1.default.deepEqual(after, snapshot);
+            strict_1.default.equal(after?.attempts.length, 1);
+            strict_1.default.equal(after?.version, afterFirst.version);
+            strict_1.default.equal(after?.state, 'signed');
+        });
+        api.it('rejects appendAttempt with a stale expectedVersion, leaving the record unchanged', async () => {
+            const { operations } = await create();
+            const created = await operations.create(sampleOperation());
+            await operations.appendAttempt('ns', created.record.id, sampleAttempt('s1'), { state: 'signed' }, 1);
+            const snapshot = await operations.get('ns', created.record.id);
+            await (0, api_1.rejectsWithCode)(operations.appendAttempt('ns', created.record.id, sampleAttempt('s2'), { state: 'submitted' }, 1), 'VERSION_CONFLICT');
+            strict_1.default.deepEqual(await operations.get('ns', created.record.id), snapshot);
+        });
+        api.it('rejects appendAttempt from a stale fencing token after a claim takeover, leaving the record unchanged', async () => {
+            const { operations } = await create();
+            const created = await operations.create(sampleOperation({ state: 'submitted', nextCheckAt: 100 }));
+            const [stale] = await operations.claimDue('ns', 'w1', 1_000, 500, 10);
+            const [takeover] = await operations.claimDue('ns', 'w2', 1_600, 500, 10);
+            const snapshot = await operations.get('ns', created.record.id);
+            await (0, api_1.rejectsWithCode)(operations.appendAttempt('ns', created.record.id, sampleAttempt('f1'), { state: 'signed' }, takeover.version, { claimToken: stale.claim.token }), 'FENCING');
+            strict_1.default.deepEqual(await operations.get('ns', created.record.id), snapshot);
+        });
+        api.it("isolates a stored attempt from later mutation of the caller's input", async () => {
+            const { operations } = await create();
+            const created = await operations.create(sampleOperation());
+            const attempt = sampleAttempt('iso1');
+            await operations.appendAttempt('ns', created.record.id, attempt, { state: 'signed' }, 1);
+            attempt.unsigned.signingRequests[0].payload[0] = 99;
+            attempt.raw.data = 'ff';
+            const stored = await operations.get('ns', created.record.id);
+            const storedAttempt = stored?.attempts[0];
+            strict_1.default.deepEqual(storedAttempt?.unsigned.signingRequests[0]?.payload, new Uint8Array([1, 2]));
+            strict_1.default.equal(storedAttempt?.raw.data, '00');
+        });
+        api.it('appends attempts in order without rewriting earlier ones', async () => {
+            const { operations } = await create();
+            const created = await operations.create(sampleOperation());
+            const afterFirst = await operations.appendAttempt('ns', created.record.id, sampleAttempt('a1'), { state: 'signed' }, 1);
+            const firstAttemptSnapshot = afterFirst.attempts[0];
+            const afterSecond = await operations.appendAttempt('ns', created.record.id, sampleAttempt('a2'), { state: 'submitted' }, afterFirst.version);
+            strict_1.default.deepEqual(afterSecond.attempts.map((a) => a.id), ['a1', 'a2']);
+            strict_1.default.deepEqual(afterSecond.attempts[0], firstAttemptSnapshot);
+        });
+        api.it('resolves N concurrent creates under one idempotency key, with distinct ids, to exactly one winner', async () => {
+            const { operations } = await create();
+            const results = await Promise.all(Array.from({ length: 5 }, () => operations.create(sampleOperation({ idempotencyKey: 'race-create' }))));
+            const winners = results.filter((r) => r.created);
+            strict_1.default.equal(winners.length, 1);
+            const winnerId = winners[0].record.id;
+            for (const r of results)
+                strict_1.default.equal(r.record.id, winnerId);
+            const listed = (await operations.list({ namespace: 'ns' })).filter((r) => r.idempotencyKey === 'race-create');
+            strict_1.default.equal(listed.length, 1);
+            strict_1.default.equal((await operations.getByKey('ns', 'race-create'))?.id, winnerId);
+        });
+        api.it('resolves N concurrent updates with the same expectedVersion to exactly one winner', async () => {
+            const { operations } = await create();
+            const created = await operations.create(sampleOperation());
+            const results = await Promise.allSettled(Array.from({ length: 5 }, () => operations.update('ns', created.record.id, { state: 'prepared' }, 1)));
+            strict_1.default.equal(results.filter((r) => r.status === 'fulfilled').length, 1);
+            const rejected = results.filter(isRejected);
+            strict_1.default.equal(rejected.length, 4);
+            for (const r of rejected) {
+                strict_1.default.equal(r.reason.code, 'VERSION_CONFLICT');
+            }
+        });
+        api.it('resolves N concurrent appendAttempt calls with the same expectedVersion to exactly one winner', async () => {
+            const { operations } = await create();
+            const created = await operations.create(sampleOperation());
+            const results = await Promise.allSettled(Array.from({ length: 5 }, (_, i) => operations.appendAttempt('ns', created.record.id, sampleAttempt(`c${i}`), { state: 'signed' }, 1)));
+            strict_1.default.equal(results.filter((r) => r.status === 'fulfilled').length, 1);
+            const rejected = results.filter(isRejected);
+            strict_1.default.equal(rejected.length, 4);
+            for (const r of rejected) {
+                strict_1.default.equal(r.reason.code, 'VERSION_CONFLICT');
+            }
+            strict_1.default.equal((await operations.get('ns', created.record.id))?.attempts.length, 1);
+        });
+        api.it('returns disjoint id sets for two concurrent claimDue calls', async () => {
+            const { operations } = await create();
+            for (let i = 0; i < 4; i++) {
+                await operations.create(sampleOperation({ state: 'submitted', nextCheckAt: 100 }));
+            }
+            const [first, second] = await Promise.all([
+                operations.claimDue('ns', 'w1', 1_000, 500, 2),
+                operations.claimDue('ns', 'w2', 1_000, 500, 2),
+            ]);
+            strict_1.default.equal(first.length + second.length, 4);
+            const firstIds = new Set(first.map((r) => r.id));
+            for (const record of second)
+                strict_1.default.equal(firstIds.has(record.id), false);
+        });
+        api.it('returns the original record unchanged when a second create uses the same key but a different intentHash', async () => {
+            const { operations } = await create();
+            const first = await operations.create(sampleOperation({ idempotencyKey: 'conflict', intentHash: 'hash-a' }));
+            const second = await operations.create(sampleOperation({ idempotencyKey: 'conflict', intentHash: 'hash-b' }));
+            strict_1.default.equal(second.created, false);
+            strict_1.default.deepEqual(second.record, first.record);
+            strict_1.default.equal(second.record.intentHash, 'hash-a');
+            strict_1.default.deepEqual(await operations.get('ns', first.record.id), first.record);
+        });
+        api.it('treats an explicit undefined patch value as a no-op for that field', async () => {
+            const { operations } = await create();
+            const created = await operations.create(sampleOperation());
+            const withReservation = await operations.update('ns', created.record.id, { reservation: { kind: 'nonce', nonce: 5n } }, 1);
+            const untouched = await operations.update('ns', created.record.id, { reservation: undefined }, withReservation.version);
+            strict_1.default.deepEqual(untouched.reservation, { kind: 'nonce', nonce: 5n });
+            strict_1.default.deepEqual((await operations.get('ns', created.record.id))?.reservation, {
+                kind: 'nonce',
+                nonce: 5n,
+            });
+        });
+        api.it('clear removes the field entirely, not just sets it to undefined', async () => {
+            const { operations } = await create();
+            const created = await operations.create(sampleOperation());
+            const withReservation = await operations.update('ns', created.record.id, { reservation: { kind: 'nonce', nonce: 5n } }, 1);
+            const cleared = await operations.update('ns', created.record.id, { clear: ['reservation'] }, withReservation.version);
+            strict_1.default.equal('reservation' in cleared, false);
+            const reread = await operations.get('ns', created.record.id);
+            strict_1.default.equal(reread !== null && 'reservation' in reread, false);
+        });
+        api.it('never returns claims from another namespace', async () => {
+            const { operations } = await create();
+            await operations.create(sampleOperation({ namespace: 'other', state: 'submitted', nextCheckAt: 50 }));
+            await operations.create(sampleOperation({ state: 'submitted', nextCheckAt: 50 }));
+            const claimed = await operations.claimDue('ns', 'w1', 1_000, 500, 10);
+            strict_1.default.equal(claimed.length, 1);
+            strict_1.default.equal(claimed.every((r) => r.namespace === 'ns'), true);
+        });
+        api.it('orders claims by (nextCheckAt, createdAt)', async () => {
+            const { operations } = await create();
+            const c = (await operations.create(sampleOperation({ state: 'submitted', nextCheckAt: 300 }))).record;
+            const a = (await operations.create(sampleOperation({ state: 'submitted', nextCheckAt: 100 }))).record;
+            const b = (await operations.create(sampleOperation({ state: 'submitted', nextCheckAt: 200 }))).record;
+            const claimed = await operations.claimDue('ns', 'w1', 1_000, 500, 10);
+            strict_1.default.deepEqual(claimed.map((r) => r.id), [a.id, b.id, c.id]);
+        });
+        api.it('limit picks the earliest due record after sorting, not by insertion order', async () => {
+            const { operations } = await create();
+            // Created in descending nextCheckAt order, so a limit-before-sort bug (e.g.
+            // slicing then sorting, instead of sorting then slicing) would return the
+            // first-inserted (highest nextCheckAt) record instead of the earliest-due one.
+            await operations.create(sampleOperation({ state: 'submitted', nextCheckAt: 300 }));
+            await operations.create(sampleOperation({ state: 'submitted', nextCheckAt: 200 }));
+            const earliest = (await operations.create(sampleOperation({ state: 'submitted', nextCheckAt: 100 }))).record;
+            const claimed = await operations.claimDue('ns', 'w1', 1_000, 500, 1);
+            strict_1.default.deepEqual(claimed.map((r) => r.id), [earliest.id]);
+        });
+        api.it('limit 2 returns the two earliest due records in order, on fresh records', async () => {
+            const { operations } = await create();
+            await operations.create(sampleOperation({ namespace: 'limit2', state: 'submitted', nextCheckAt: 300 }));
+            const second = (await operations.create(sampleOperation({
+                namespace: 'limit2',
+                state: 'submitted',
+                nextCheckAt: 200,
+            }))).record;
+            const first = (await operations.create(sampleOperation({
+                namespace: 'limit2',
+                state: 'submitted',
+                nextCheckAt: 100,
+            }))).record;
+            const claimed = await operations.claimDue('limit2', 'w1', 1_000, 500, 2);
+            strict_1.default.deepEqual(claimed.map((r) => r.id), [first.id, second.id]);
+        });
+        api.it('breaks a nextCheckAt tie by createdAt, in creation order', async () => {
+            const { operations, advance } = await create();
+            const first = (await operations.create(sampleOperation({ state: 'submitted', nextCheckAt: 100 }))).record;
+            await advance(10);
+            const second = (await operations.create(sampleOperation({ state: 'submitted', nextCheckAt: 100 }))).record;
+            const claimed = await operations.claimDue('ns', 'w1', 1_000, 500, 10);
+            strict_1.default.deepEqual(claimed.map((r) => r.id), [first.id, second.id]);
+        });
+        api.it('limit 0 returns no claims', async () => {
+            const { operations } = await create();
+            await operations.create(sampleOperation({ state: 'submitted', nextCheckAt: 100 }));
+            strict_1.default.deepEqual(await operations.claimDue('ns', 'w1', 1_000, 500, 0), []);
+        });
+        api.it('returns matching records in creation order', async () => {
+            const { operations } = await create();
+            const a = (await operations.create(sampleOperation({ namespace: 'order' }))).record;
+            const b = (await operations.create(sampleOperation({ namespace: 'order' }))).record;
+            const c = (await operations.create(sampleOperation({ namespace: 'order' }))).record;
+            const found = await operations.list({ namespace: 'order' });
+            strict_1.default.deepEqual(found.map((r) => r.id), [a.id, b.id, c.id]);
+        });
+        api.it('putObservation never changes the Operation version, and rejects a stale expectedVersion', async () => {
+            const { operations } = await create();
+            const created = await operations.create(sampleOperation());
+            const afterAppend = await operations.appendAttempt('ns', created.record.id, sampleAttempt('obs1'), { state: 'signed' }, 1);
+            const base = {
+                attemptId: 'obs1',
+                operationId: created.record.id,
+                state: 'included',
+                evidence: 'observed',
+                confirmations: 1,
+            };
+            await operations.putObservation(base, null);
+            strict_1.default.equal((await operations.get('ns', created.record.id))?.version, afterAppend.version);
+            await operations.putObservation({ ...base, confirmations: 2 }, 1);
+            strict_1.default.equal((await operations.get('ns', created.record.id))?.version, afterAppend.version);
+            await (0, api_1.rejectsWithCode)(operations.putObservation({ ...base, confirmations: 3 }, 1), 'VERSION_CONFLICT');
+        });
+        api.it('does not resolve a tx hash to an operation with the same id in a different namespace', async () => {
+            const { operations } = await create();
+            const sharedId = 'op_shared_1';
+            await operations.create(sampleOperation({ id: sharedId, namespace: 'ns-a', idempotencyKey: 'key-a' }));
+            await operations.create(sampleOperation({ id: sharedId, namespace: 'ns-b', idempotencyKey: 'key-b' }));
+            await operations.appendAttempt('ns-a', sharedId, sampleAttempt('shared-attempt'), { state: 'signed' }, 1);
+            await operations.putObservation({
+                attemptId: 'shared-attempt',
+                operationId: sharedId,
+                state: 'included',
+                evidence: 'observed',
+                confirmations: 1,
+                txHash: 'shared-hash',
+            }, null);
+            const found = await operations.findByRef('ns-a', 'shared-hash');
+            strict_1.default.equal(found?.id, sharedId);
+            strict_1.default.equal(found?.namespace, 'ns-a');
+            strict_1.default.equal(await operations.findByRef('ns-b', 'shared-hash'), null);
+        });
+    });
+}
+//# sourceMappingURL=operations.js.map