@satorio/machinery 0.2.1

package/dist/vitest/port-contracts/event-publisher.contract.js

@@ -0,0 +1,67 @@
+import { describe, expect } from '@effect/vitest';
+import { EventPublisher } from '@satorio/machinery/ports';
+import { DateTime, Effect } from 'effect';
+const HOW_MANY_TIMES_TO_ASK = 20;
+/**
+ * One message, built the way an outbox hands it over.
+ */
+export const outboxEvent = (messageId, payload) => ({
+    messageId,
+    eventType: 'SomethingHappened',
+    schemaVersion: 1,
+    occurredAt: DateTime.unsafeMake('2026-03-01T12:00:00.000Z'),
+    payload,
+});
+/**
+ * One contract, every event publisher. The same body runs against an
+ * in-memory publisher and a live SNS topic, so a difference between them
+ * shows up as a red test rather than as a surprise in production. Hand
+ * it the port's unavailable stand-in as a fourth argument and it walks
+ * the refusal too.
+ *
+ * What this contract cannot prove: that a subscriber reads the envelope
+ * the publisher wrote. The shape on the wire is each implementation's
+ * own — `stdoutLineOf` carries a channel, `snsMessageBodyOf` does not —
+ * so the live test in `src/publishing/ports.localstack.test.ts` owns
+ * that branch, reading the envelope back off a queue subscribed to the
+ * topic.
+ */
+export const eventPublisherContract = (it, implementationName, publisher, unavailable) => {
+    const run = (effect) => Effect.provide(effect, publisher.layer);
+    const deliveredUntil = (howMany) => publisher.delivered.pipe(Effect.repeat({
+        until: (ids) => ids.length >= howMany,
+        times: HOW_MANY_TIMES_TO_ASK,
+    }));
+    describe(`EventPublisher contract (${implementationName})`, () => {
+        it.effect('a published message reaches whatever stands behind it', () => run(Effect.gen(function* () {
+            const publishing = yield* EventPublisher;
+            yield* publishing.publish([outboxEvent('contract-1', { seq: 1 })]);
+            const delivered = yield* deliveredUntil(1);
+            expect(delivered).toContain('contract-1');
+        })));
+        it.effect('every message of a batch goes, not only the first', () => run(Effect.gen(function* () {
+            const publishing = yield* EventPublisher;
+            yield* publishing.publish([
+                outboxEvent('contract-2', { seq: 2 }),
+                outboxEvent('contract-3', { seq: 3 }),
+            ]);
+            const delivered = yield* deliveredUntil(3);
+            expect(delivered).toContain('contract-2');
+            expect(delivered).toContain('contract-3');
+        })));
+        it.effect('an empty batch publishes nothing and fails nothing', () => run(Effect.gen(function* () {
+            const publishing = yield* EventPublisher;
+            yield* publishing.publish([]);
+        })));
+    });
+    if (unavailable === undefined)
+        return;
+    describe(`EventPublisher contract (${implementationName}, not mounted)`, () => {
+        it.effect('publish fails, and the caller reads the refusal', () => Effect.gen(function* () {
+            const publishing = yield* EventPublisher;
+            const refusal = yield* Effect.flip(publishing.publish([outboxEvent('contract-4', {})]));
+            expect(refusal._tag).toBe('EventPublisherUnavailableError');
+            expect(refusal.operation).toBe('publish');
+        }).pipe(Effect.provide(unavailable)));
+    });
+};

package/dist/vitest/port-contracts/external-http-client.contract.d.ts

@@ -0,0 +1,35 @@
+import { ExternalHttpClient } from '@satorio/machinery/ports';
+import { type Layer } from 'effect';
+import type { PortContractTester } from '../port-contract-tester.js';
+/**
+ * One external service, described the way a contract can hold it: the
+ * layer that mounts the port, and the three paths whatever stands behind
+ * it answers — one that returns a body with the title given here, one it
+ * does not serve at all, and one whose body does not fit the schema.
+ *
+ * @internal
+ */
+export interface ExternalServiceUnderTest {
+    readonly layer: Layer.Layer<ExternalHttpClient>;
+    readonly answered: string;
+    readonly answeredTitle: string;
+    readonly notServed: string;
+    readonly malformed: string;
+}
+/**
+ * One contract, every external HTTP client. The same body runs against
+ * the in-memory stand-in and against a real socket, so the three
+ * failures stay three: the service did not answer, the service said a
+ * specific no, and the body did not fit the schema. Hand it the port's
+ * unavailable stand-in as a fourth argument and it walks the refusal
+ * too.
+ *
+ * What this contract cannot prove: that a transient failure is retried
+ * and a refusal is not. Retrying takes a transport that answers
+ * differently on the second call, and no stand-in reaches that from the
+ * port alone — `src/integration/external-http-client.test.ts` owns that
+ * branch, driving a scripted transport past the retry schedule on a
+ * `TestClock`. Nor does it prove the timeout: that branch belongs to the
+ * same test, because a stand-in that answers at once can never be late.
+ */
+export declare const externalHttpClientContract: (it: PortContractTester, implementationName: string, service: ExternalServiceUnderTest, unavailable?: Layer.Layer<ExternalHttpClient>) => void;

package/dist/vitest/port-contracts/external-http-client.contract.js

@@ -0,0 +1,52 @@
+import { describe, expect } from '@effect/vitest';
+import { ExternalHttpClient } from '@satorio/machinery/ports';
+import { Effect, Schema } from 'effect';
+const AnsweredBody = Schema.Struct({ title: Schema.String });
+/**
+ * One contract, every external HTTP client. The same body runs against
+ * the in-memory stand-in and against a real socket, so the three
+ * failures stay three: the service did not answer, the service said a
+ * specific no, and the body did not fit the schema. Hand it the port's
+ * unavailable stand-in as a fourth argument and it walks the refusal
+ * too.
+ *
+ * What this contract cannot prove: that a transient failure is retried
+ * and a refusal is not. Retrying takes a transport that answers
+ * differently on the second call, and no stand-in reaches that from the
+ * port alone — `src/integration/external-http-client.test.ts` owns that
+ * branch, driving a scripted transport past the retry schedule on a
+ * `TestClock`. Nor does it prove the timeout: that branch belongs to the
+ * same test, because a stand-in that answers at once can never be late.
+ */
+export const externalHttpClientContract = (it, implementationName, service, unavailable) => {
+    const run = (effect) => Effect.provide(effect, service.layer);
+    describe(`ExternalHttpClient contract (${implementationName})`, () => {
+        it.effect('a served path answers with the decoded body', () => run(Effect.gen(function* () {
+            const client = yield* ExternalHttpClient;
+            const answered = yield* client.getJson(service.answered, AnsweredBody);
+            expect(answered.title).toBe(service.answeredTitle);
+        })));
+        it.effect('a path the service does not serve is a refusal, not silence', () => run(Effect.gen(function* () {
+            const client = yield* ExternalHttpClient;
+            const refusal = yield* Effect.flip(client.getJson(service.notServed, AnsweredBody));
+            expect(refusal._tag).toBe('ExternalServiceRefusedError');
+        })));
+        it.effect('a body that does not fit the schema is its own failure', () => run(Effect.gen(function* () {
+            const client = yield* ExternalHttpClient;
+            const failure = yield* Effect.flip(client.getJson(service.malformed, AnsweredBody));
+            expect(failure._tag).toBe('ExternalServiceResponseMalformedError');
+        })));
+    });
+    if (unavailable === undefined)
+        return;
+    describe(`ExternalHttpClient contract (${implementationName}, not mounted)`, () => {
+        it.effect('every call fails, and the caller reads the refusal', () => Effect.gen(function* () {
+            const client = yield* ExternalHttpClient;
+            const refusal = yield* Effect.flip(client.getJson(service.answered, AnsweredBody));
+            expect(refusal._tag).toBe('ExternalServiceUnavailableError');
+            if (refusal._tag === 'ExternalServiceUnavailableError') {
+                expect(refusal.operation).toBe('getJson');
+            }
+        }).pipe(Effect.provide(unavailable)));
+    });
+};

package/dist/vitest/port-contracts/integration-event-outbox.contract.d.ts

@@ -0,0 +1,23 @@
+import { IntegrationEventOutbox, type OutboxMessage } from '@satorio/machinery/ports';
+import { type Layer } from 'effect';
+import type { PortContractTester } from '../port-contract-tester.js';
+/**
+ * One outbox message a contract enqueues and reads back, so every
+ * implementation is asked the same question.
+ */
+export declare const outboxMessage: (messageId: string) => OutboxMessage;
+/**
+ * One contract, every integration event outbox. The same body runs against an
+ * in-memory outbox and a live Postgres outbox, so a difference between
+ * them shows up as a red test, not a surprise in production. Hand it the
+ * port's unavailable stand-in as a fourth argument and it walks the
+ * refusal too: the write fails, and the failure reaches the caller.
+ *
+ * What this contract cannot prove: that a message enqueued inside a
+ * transaction disappears with it when the transaction rolls back. The
+ * in-memory outbox writes to a `Ref` that only an in-memory transaction
+ * boundary can restore; only the live run in
+ * `src/postgres/ports.postgres.test.ts` puts one real transaction around
+ * the state change and the message together.
+ */
+export declare const integrationEventOutboxContract: (it: PortContractTester, implementationName: string, layer: Layer.Layer<IntegrationEventOutbox>, unavailable?: Layer.Layer<IntegrationEventOutbox>) => void;

package/dist/vitest/port-contracts/integration-event-outbox.contract.js

@@ -0,0 +1,75 @@
+import { describe, expect } from '@effect/vitest';
+import { IntegrationEventOutbox, } from '@satorio/machinery/ports';
+import { DateTime, Effect } from 'effect';
+const OCCURRED_AT = DateTime.unsafeMake('2026-03-01T12:00:00.000Z');
+/**
+ * One outbox message a contract enqueues and reads back, so every
+ * implementation is asked the same question.
+ */
+export const outboxMessage = (messageId) => ({
+    messageId,
+    eventType: 'SomethingHappened',
+    schemaVersion: 1,
+    occurredAt: OCCURRED_AT,
+    payload: { subject: messageId },
+});
+const idsOf = (messages) => messages.map((message) => message.messageId);
+/**
+ * One contract, every integration event outbox. The same body runs against an
+ * in-memory outbox and a live Postgres outbox, so a difference between
+ * them shows up as a red test, not a surprise in production. Hand it the
+ * port's unavailable stand-in as a fourth argument and it walks the
+ * refusal too: the write fails, and the failure reaches the caller.
+ *
+ * What this contract cannot prove: that a message enqueued inside a
+ * transaction disappears with it when the transaction rolls back. The
+ * in-memory outbox writes to a `Ref` that only an in-memory transaction
+ * boundary can restore; only the live run in
+ * `src/postgres/ports.postgres.test.ts` puts one real transaction around
+ * the state change and the message together.
+ */
+export const integrationEventOutboxContract = (it, implementationName, layer, unavailable) => {
+    const run = (effect) => Effect.provide(effect, layer);
+    describe(`IntegrationEventOutbox contract (${implementationName})`, () => {
+        it.effect('a message that was put waits among the undispatched', () => run(Effect.gen(function* () {
+            const outbox = yield* IntegrationEventOutbox;
+            yield* outbox.enqueue([outboxMessage('outbox-1')]);
+            const pending = yield* outbox.pending(10);
+            expect(idsOf(pending)).toContain('outbox-1');
+        })));
+        it.effect('a message marked dispatched no longer shows as undispatched', () => run(Effect.gen(function* () {
+            const outbox = yield* IntegrationEventOutbox;
+            yield* outbox.enqueue([outboxMessage('outbox-2')]);
+            yield* outbox.markDispatched(['outbox-2']);
+            const pending = yield* outbox.pending(10);
+            expect(idsOf(pending)).not.toContain('outbox-2');
+        })));
+        it.effect('enqueuing the same messageId again does not duplicate it', () => run(Effect.gen(function* () {
+            const outbox = yield* IntegrationEventOutbox;
+            yield* outbox.enqueue([outboxMessage('outbox-3')]);
+            yield* outbox.enqueue([outboxMessage('outbox-3')]);
+            const pending = yield* outbox.pending(100);
+            expect(idsOf(pending).filter((id) => id === 'outbox-3')).toHaveLength(1);
+        })));
+        it.effect('the limit caps the batch size', () => run(Effect.gen(function* () {
+            const outbox = yield* IntegrationEventOutbox;
+            yield* outbox.enqueue([
+                outboxMessage('outbox-4'),
+                outboxMessage('outbox-5'),
+                outboxMessage('outbox-6'),
+            ]);
+            const pending = yield* outbox.pending(2);
+            expect(pending).toHaveLength(2);
+        })));
+    });
+    if (unavailable === undefined)
+        return;
+    describe(`IntegrationEventOutbox contract (${implementationName}, not mounted)`, () => {
+        it.effect('the write fails, and the caller reads the refusal', () => Effect.gen(function* () {
+            const outbox = yield* IntegrationEventOutbox;
+            const refusal = yield* Effect.flip(outbox.enqueue([outboxMessage('outbox-7')]));
+            expect(refusal._tag).toBe('IntegrationEventOutboxUnavailableError');
+            expect(refusal.operation).toBe('enqueue');
+        }).pipe(Effect.provide(unavailable)));
+    });
+};

package/dist/vitest/port-contracts/processed-event-registry.contract.d.ts

@@ -0,0 +1,18 @@
+import { ProcessedEventRegistry } from '@satorio/machinery/ports';
+import { type Layer } from 'effect';
+import type { PortContractTester } from '../port-contract-tester.js';
+/**
+ * One contract, every processed event registry. The same body runs against an
+ * in-memory registry and a live Postgres registry, so a difference between
+ * them shows up as a red test, not a surprise in production. Hand it the
+ * port's unavailable stand-in as a fourth argument and it walks the
+ * refusal too: the claim fails, and the failure reaches the caller.
+ *
+ * What this contract cannot prove: that two callers claiming the same id
+ * at the same instant get one acceptance and one AlreadyProcessed. The
+ * in-memory registry runs one fiber at a time over a `Ref`, so it cannot
+ * lose that race; only the live run in
+ * `src/postgres/ports.postgres.test.ts` puts a real unique constraint
+ * behind the claim.
+ */
+export declare const processedEventRegistryContract: (it: PortContractTester, implementationName: string, layer: Layer.Layer<ProcessedEventRegistry>, unavailable?: Layer.Layer<ProcessedEventRegistry>) => void;

package/dist/vitest/port-contracts/processed-event-registry.contract.js

@@ -0,0 +1,84 @@
+import { describe, expect } from '@effect/vitest';
+import { ProcessedEventRegistry } from '@satorio/machinery/ports';
+import { DateTime, Effect } from 'effect';
+const FIRST_CLAIM_AT = DateTime.unsafeMake('2026-02-10T09:30:00.000Z');
+const SECOND_CLAIM_AT = DateTime.unsafeMake('2026-02-11T18:00:00.000Z');
+/**
+ * One contract, every processed event registry. The same body runs against an
+ * in-memory registry and a live Postgres registry, so a difference between
+ * them shows up as a red test, not a surprise in production. Hand it the
+ * port's unavailable stand-in as a fourth argument and it walks the
+ * refusal too: the claim fails, and the failure reaches the caller.
+ *
+ * What this contract cannot prove: that two callers claiming the same id
+ * at the same instant get one acceptance and one AlreadyProcessed. The
+ * in-memory registry runs one fiber at a time over a `Ref`, so it cannot
+ * lose that race; only the live run in
+ * `src/postgres/ports.postgres.test.ts` puts a real unique constraint
+ * behind the claim.
+ */
+export const processedEventRegistryContract = (it, implementationName, layer, unavailable) => {
+    const run = (effect) => Effect.provide(effect, layer);
+    describe(`ProcessedEventRegistry contract (${implementationName})`, () => {
+        it.effect('the first claim on an eventId gives ClaimAccepted', () => run(Effect.gen(function* () {
+            const registry = yield* ProcessedEventRegistry;
+            const claim = yield* registry.claim({
+                eventId: 'event-1',
+                processedAt: FIRST_CLAIM_AT,
+            });
+            expect(claim._tag).toBe('ClaimAccepted');
+        })));
+        it.effect('a second claim on the same eventId gives AlreadyProcessed', () => run(Effect.gen(function* () {
+            const registry = yield* ProcessedEventRegistry;
+            yield* registry.claim({
+                eventId: 'event-2',
+                processedAt: FIRST_CLAIM_AT,
+            });
+            const claim = yield* registry.claim({
+                eventId: 'event-2',
+                processedAt: SECOND_CLAIM_AT,
+            });
+            expect(claim._tag).toBe('AlreadyProcessed');
+        })));
+        it.effect('AlreadyProcessed carries the first claim time, not the repeat', () => run(Effect.gen(function* () {
+            const registry = yield* ProcessedEventRegistry;
+            yield* registry.claim({
+                eventId: 'event-3',
+                processedAt: FIRST_CLAIM_AT,
+            });
+            const claim = yield* registry.claim({
+                eventId: 'event-3',
+                processedAt: SECOND_CLAIM_AT,
+            });
+            expect(claim._tag).toBe('AlreadyProcessed');
+            if (claim._tag === 'AlreadyProcessed') {
+                expect(DateTime.toEpochMillis(claim.processedAt)).toBe(DateTime.toEpochMillis(FIRST_CLAIM_AT));
+            }
+        })));
+        it.effect('a claim on a different eventId gives ClaimAccepted', () => run(Effect.gen(function* () {
+            const registry = yield* ProcessedEventRegistry;
+            yield* registry.claim({
+                eventId: 'event-4',
+                processedAt: FIRST_CLAIM_AT,
+            });
+            const claim = yield* registry.claim({
+                eventId: 'event-5',
+                processedAt: SECOND_CLAIM_AT,
+            });
+            expect(claim._tag).toBe('ClaimAccepted');
+        })));
+    });
+    if (unavailable === undefined)
+        return;
+    describe(`ProcessedEventRegistry contract (${implementationName}, not mounted)`, () => {
+        it.effect('the claim fails, and the caller reads the refusal', () => Effect.gen(function* () {
+            const registry = yield* ProcessedEventRegistry;
+            const refusal = yield* Effect.flip(registry.claim({
+                eventId: 'event-6',
+                processedAt: FIRST_CLAIM_AT,
+            }));
+            expect(refusal._tag).toBe('ProcessedEventRegistryUnavailableError');
+            expect(refusal.operation).toBe('claim');
+        }).pipe(Effect.provide(unavailable)));
+    });
+};

package/dist/vitest/port-contracts/queue-message-producer.contract.d.ts

@@ -0,0 +1,26 @@
+import { QueueMessageProducer } from '@satorio/machinery/ports';
+import { Effect, type Layer } from 'effect';
+import type { PortContractTester } from '../port-contract-tester.js';
+/**
+ * One producer, described the way a contract can hold it: the layer that
+ * mounts it, and the one call that reads back the bodies that landed on
+ * the queue behind it.
+ *
+ * @internal
+ */
+export interface ProducerUnderTest {
+    readonly layer: Layer.Layer<QueueMessageProducer>;
+    readonly taken: Effect.Effect<readonly string[]>;
+}
+/**
+ * One contract, every message producer. It holds the only promise a
+ * producer makes: a body handed to `send` lands on the queue, whole and
+ * unchanged. Hand it the port's unavailable stand-in as a fourth
+ * argument and it walks the refusal too.
+ *
+ * What this contract cannot prove: the order two sends arrive in. An SQS
+ * standard queue makes no such promise, so the contract asserts what did
+ * land rather than the order it landed in, and no implementation is held
+ * to a promise the technology does not keep.
+ */
+export declare const queueMessageProducerContract: (it: PortContractTester, implementationName: string, producer: ProducerUnderTest, unavailable?: Layer.Layer<QueueMessageProducer>) => void;

package/dist/vitest/port-contracts/queue-message-producer.contract.js

@@ -0,0 +1,48 @@
+import { describe, expect } from '@effect/vitest';
+import { QueueMessageProducer } from '@satorio/machinery/ports';
+import { Effect } from 'effect';
+const HOW_MANY_TIMES_TO_ASK = 20;
+/**
+ * One contract, every message producer. It holds the only promise a
+ * producer makes: a body handed to `send` lands on the queue, whole and
+ * unchanged. Hand it the port's unavailable stand-in as a fourth
+ * argument and it walks the refusal too.
+ *
+ * What this contract cannot prove: the order two sends arrive in. An SQS
+ * standard queue makes no such promise, so the contract asserts what did
+ * land rather than the order it landed in, and no implementation is held
+ * to a promise the technology does not keep.
+ */
+export const queueMessageProducerContract = (it, implementationName, producer, unavailable) => {
+    const run = (effect) => Effect.provide(effect, producer.layer);
+    const takenUntil = (howMany) => producer.taken.pipe(Effect.repeat({
+        until: (bodies) => bodies.length >= howMany,
+        times: HOW_MANY_TIMES_TO_ASK,
+    }));
+    describe(`QueueMessageProducer contract (${implementationName})`, () => {
+        it.effect('a sent body lands on the queue unchanged', () => run(Effect.gen(function* () {
+            const sending = yield* QueueMessageProducer;
+            yield* sending.send('a body the queue keeps whole');
+            const bodies = yield* takenUntil(1);
+            expect(bodies).toContain('a body the queue keeps whole');
+        })));
+        it.effect('two sends put two messages on the queue', () => run(Effect.gen(function* () {
+            const sending = yield* QueueMessageProducer;
+            yield* sending.send('first of two');
+            yield* sending.send('second of two');
+            const bodies = yield* takenUntil(2);
+            expect(bodies).toContain('first of two');
+            expect(bodies).toContain('second of two');
+        })));
+    });
+    if (unavailable === undefined)
+        return;
+    describe(`QueueMessageProducer contract (${implementationName}, not mounted)`, () => {
+        it.effect('send fails, and the caller reads the refusal', () => Effect.gen(function* () {
+            const sending = yield* QueueMessageProducer;
+            const refusal = yield* Effect.flip(sending.send('never sent'));
+            expect(refusal._tag).toBe('QueueMessageProducerUnavailableError');
+            expect(refusal.operation).toBe('send');
+        }).pipe(Effect.provide(unavailable)));
+    });
+};

package/dist/vitest/port-contracts/queue-message-source.contract.d.ts

@@ -0,0 +1,29 @@
+import { QueueMessageSource } from '@satorio/machinery/ports';
+import { Effect, type Layer } from 'effect';
+import type { PortContractTester } from '../port-contract-tester.js';
+/**
+ * One queue, described the way a contract can hold it: the layer that
+ * mounts the source, and the one call that puts a message on the queue
+ * behind it. An in-memory queue writes to its own `Ref`; a live SQS
+ * queue sends with the producer.
+ *
+ * @internal
+ */
+export interface QueueUnderTest {
+    readonly layer: Layer.Layer<QueueMessageSource>;
+    readonly put: (body: string) => Effect.Effect<void>;
+}
+/**
+ * One contract, every message source. The same body runs against an
+ * in-memory queue and a live SQS queue, so a difference between them
+ * shows up as a red test rather than as a surprise in production. Hand
+ * it the port's unavailable stand-in as a fourth argument and it walks
+ * the refusal too: receive and acknowledge both fail, and the failure
+ * reaches the caller.
+ *
+ * What this contract cannot prove: that a message nobody acknowledges
+ * comes back. Redelivery after the visibility timeout is SQS's promise
+ * and no in-memory stand-in keeps a clock, so the live test in
+ * `src/queue/ports.localstack.test.ts` owns that branch.
+ */
+export declare const queueMessageSourceContract: (it: PortContractTester, implementationName: string, queue: QueueUnderTest, unavailable?: Layer.Layer<QueueMessageSource>) => void;

package/dist/vitest/port-contracts/queue-message-source.contract.js

@@ -0,0 +1,71 @@
+import { describe, expect } from '@effect/vitest';
+import { QueueMessageSource } from '@satorio/machinery/ports';
+import { Effect } from 'effect';
+const HOW_MANY_TIMES_TO_ASK = 20;
+/**
+ * One contract, every message source. The same body runs against an
+ * in-memory queue and a live SQS queue, so a difference between them
+ * shows up as a red test rather than as a surprise in production. Hand
+ * it the port's unavailable stand-in as a fourth argument and it walks
+ * the refusal too: receive and acknowledge both fail, and the failure
+ * reaches the caller.
+ *
+ * What this contract cannot prove: that a message nobody acknowledges
+ * comes back. Redelivery after the visibility timeout is SQS's promise
+ * and no in-memory stand-in keeps a clock, so the live test in
+ * `src/queue/ports.localstack.test.ts` owns that branch.
+ */
+export const queueMessageSourceContract = (it, implementationName, queue, unavailable) => {
+    const run = (effect) => Effect.provide(effect, queue.layer);
+    const receiveSomething = Effect.flatMap(QueueMessageSource, (source) => source.receive.pipe(Effect.repeat({
+        until: (batch) => batch.length > 0,
+        times: HOW_MANY_TIMES_TO_ASK,
+    })));
+    describe(`QueueMessageSource contract (${implementationName})`, () => {
+        it.effect('what was put on the queue comes back whole', () => run(Effect.gen(function* () {
+            yield* queue.put('body-of-the-first-message');
+            const received = yield* receiveSomething;
+            const first = received[0];
+            expect(first?.body).toBe('body-of-the-first-message');
+            expect(first?.messageId).not.toBe('');
+            expect(first?.receiptHandle).not.toBe('');
+        })));
+        it.effect('an acknowledged message does not come back', () => run(Effect.gen(function* () {
+            const source = yield* QueueMessageSource;
+            yield* queue.put('body-of-the-second-message');
+            const received = yield* receiveSomething;
+            for (const message of received) {
+                yield* source.acknowledge(message.receiptHandle);
+            }
+            const afterwards = yield* source.receive;
+            expect(afterwards.map((message) => message.body)).not.toContain('body-of-the-second-message');
+        })));
+        it.effect('acknowledging a receipt twice is not a failure', () => run(Effect.gen(function* () {
+            const source = yield* QueueMessageSource;
+            yield* queue.put('body-of-the-third-message');
+            const received = yield* receiveSomething;
+            const receiptHandle = received[0]?.receiptHandle ?? '';
+            yield* source.acknowledge(receiptHandle);
+            yield* source.acknowledge(receiptHandle);
+        })));
+    });
+    if (unavailable === undefined)
+        return;
+    describe(`QueueMessageSource contract (${implementationName}, not mounted)`, () => {
+        it.effect('every operation fails, and the caller reads the refusal', () => Effect.gen(function* () {
+            const source = yield* QueueMessageSource;
+            const refusals = yield* Effect.all([
+                Effect.flip(source.receive),
+                Effect.flip(source.acknowledge('receipt-1')),
+            ]);
+            expect(refusals.map((refusal) => refusal._tag)).toEqual([
+                'QueueMessageSourceUnavailableError',
+                'QueueMessageSourceUnavailableError',
+            ]);
+            expect(refusals.map((refusal) => refusal.operation)).toEqual([
+                'receive',
+                'acknowledge',
+            ]);
+        }).pipe(Effect.provide(unavailable)));
+    });
+};

package/dist/vitest/port-contracts/readiness-probe.contract.d.ts

@@ -0,0 +1,18 @@
+import { ReadinessProbe } from '@satorio/machinery/ports';
+import { type Layer } from 'effect';
+import type { PortContractTester } from '../port-contract-tester.js';
+/**
+ * One contract, every readiness probe. The same body runs against an
+ * in-memory probe and a live Postgres probe, so a difference between them
+ * shows up as a red test, not a surprise in production. Hand it the
+ * port's unavailable stand-in as a fourth argument and it walks the "not
+ * ready" branch too.
+ *
+ * What this contract cannot prove: that a real database falling silent
+ * is what makes the probe say no. A fake can only ever answer the way it
+ * was built to, and the two reasons a Postgres probe tells apart — a
+ * query that failed and a query that never came back —
+ * `src/postgres/readiness-probe.test.ts` owns, against a query it
+ * controls.
+ */
+export declare const readinessProbeContract: (it: PortContractTester, implementationName: string, layer: Layer.Layer<ReadinessProbe>, unavailable?: Layer.Layer<ReadinessProbe>) => void;

package/dist/vitest/port-contracts/readiness-probe.contract.js

@@ -0,0 +1,41 @@
+import { describe, expect } from '@effect/vitest';
+import { ReadinessProbe } from '@satorio/machinery/ports';
+import { Effect } from 'effect';
+/**
+ * One contract, every readiness probe. The same body runs against an
+ * in-memory probe and a live Postgres probe, so a difference between them
+ * shows up as a red test, not a surprise in production. Hand it the
+ * port's unavailable stand-in as a fourth argument and it walks the "not
+ * ready" branch too.
+ *
+ * What this contract cannot prove: that a real database falling silent
+ * is what makes the probe say no. A fake can only ever answer the way it
+ * was built to, and the two reasons a Postgres probe tells apart — a
+ * query that failed and a query that never came back —
+ * `src/postgres/readiness-probe.test.ts` owns, against a query it
+ * controls.
+ */
+export const readinessProbeContract = (it, implementationName, layer, unavailable) => {
+    const run = (effect) => Effect.provide(effect, layer);
+    describe(`ReadinessProbe contract (${implementationName})`, () => {
+        it.effect('a database that answers makes the probe succeed', () => run(Effect.gen(function* () {
+            const probe = yield* ReadinessProbe;
+            yield* probe.verifyDatabaseAnswers;
+        })));
+        it.effect('asking twice answers twice, and holds nothing back', () => run(Effect.gen(function* () {
+            const probe = yield* ReadinessProbe;
+            yield* probe.verifyDatabaseAnswers;
+            yield* probe.verifyDatabaseAnswers;
+        })));
+    });
+    if (unavailable === undefined)
+        return;
+    describe(`ReadinessProbe contract (${implementationName}, not mounted)`, () => {
+        it.effect('a database that stays silent says so, with a reason', () => Effect.gen(function* () {
+            const probe = yield* ReadinessProbe;
+            const failure = yield* Effect.flip(probe.verifyDatabaseAnswers);
+            expect(failure._tag).toBe('DatabaseDidNotAnswerError');
+            expect(failure.reason.length).toBeGreaterThan(0);
+        }).pipe(Effect.provide(unavailable)));
+    });
+};

package/dist/vitest/port-contracts/transaction-boundary.contract.d.ts

@@ -0,0 +1,21 @@
+import { TransactionBoundary } from '@satorio/machinery/ports';
+import { type Layer } from 'effect';
+import type { PortContractTester } from '../port-contract-tester.js';
+/**
+ * One contract, every transaction boundary. The same body runs against an
+ * in-memory boundary and a live Postgres transaction, so a difference
+ * between them shows up as a red test, not a surprise in production.
+ * Hand it the port's unavailable stand-in as a fourth argument and it
+ * walks the refusal too: the work never runs, and the failure reaches
+ * the caller.
+ *
+ * What this contract cannot prove: that what the work wrote is what gets
+ * rolled back. An in-memory boundary restores the `Ref`s it was handed as
+ * participants; a Postgres one rolls back a real transaction and knows
+ * nothing about `Ref`s. Both promises are held here through a `Ref` the
+ * work updates and the boundary never sees, so the assertions read the
+ * same on both sides — and the Postgres half, where a row written inside
+ * a failed transaction is gone afterwards, is owned by
+ * `src/postgres/ports.postgres.test.ts`.
+ */
+export declare const transactionBoundaryContract: (it: PortContractTester, implementationName: string, layer: Layer.Layer<TransactionBoundary>, unavailable?: Layer.Layer<TransactionBoundary>) => void;