@satorio/machinery 0.2.1

package/dist/vitest/effect-single-instance.js

@@ -0,0 +1,125 @@
+import { existsSync, readdirSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { repoRoot } from './repo-source-files.js';
+const isSkippedEntry = (name) => name.startsWith('.');
+/**
+ * @internal
+ */
+export const walkForEffectCopies = (nodeModulesDirectory, visited, found) => {
+    let entries;
+    try {
+        entries = readdirSync(nodeModulesDirectory);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        if (isSkippedEntry(name))
+            continue;
+        const entryPath = join(nodeModulesDirectory, name);
+        let realEntryPath;
+        try {
+            realEntryPath = realpathSync(entryPath);
+        }
+        catch {
+            continue;
+        }
+        if (visited.has(realEntryPath))
+            continue;
+        visited.add(realEntryPath);
+        if (name.startsWith('@')) {
+            walkForEffectCopies(entryPath, visited, found);
+            continue;
+        }
+        if (name === 'effect' && existsSync(join(entryPath, 'package.json'))) {
+            found.push({ packageDirectory: realEntryPath });
+        }
+        const nested = join(entryPath, 'node_modules');
+        if (existsSync(nested))
+            walkForEffectCopies(nested, visited, found);
+    }
+};
+const resolveEffectEntryFrom = (directory) => {
+    const anchor = join(directory, 'package.json');
+    try {
+        return realpathSync(createRequire(anchor).resolve('effect'));
+    }
+    catch {
+        return undefined;
+    }
+};
+const WHY_ONE_COPY_MATTERS = "why one copy matters: effect's Context.Tag identity and TestClock " +
+    'depend on true module-singleton state. Two physical copies break both ' +
+    'silently — a service registered against one copy is invisible to code ' +
+    'running against the other, and a TestClock the test believes it is ' +
+    'driving never touches the runtime under test.';
+const WHAT_TO_DO = 'what to do: dedupe node_modules (reinstall, or run your package ' +
+    "manager's dedupe command) so only one effect copy remains, or align " +
+    "the offending path's effect version with this package's peer range " +
+    '(^3.22.1) so the package manager collapses it back to one copy.';
+const tooManyCopiesMessage = (directories) => [
+    `what happened: found ${directories.length} physical copies of the ` +
+        `effect package under node_modules:\n${directories.map((d) => `  - ${d}`).join('\n')}`,
+    WHY_ONE_COPY_MATTERS,
+    WHAT_TO_DO,
+].join('\n');
+const noCopyAtAllMessage = (root) => [
+    'what happened: the walk over ' +
+        `${root}/node_modules found no copy of the effect package at all.`,
+    'why that is a finding, not a pass: this suite proves there is exactly ' +
+        'one copy. Zero copies means it walked the wrong tree — an unbuilt ' +
+        'install, a moved root, a workspace whose packages live elsewhere — ' +
+        'and a comparison over nothing passes every time.',
+    'what to do: install dependencies at that root, or pass the root that ' +
+        "really holds node_modules through the guard's `root` option.",
+].join('\n');
+const resolveMismatchMessage = (fromConsumerRoot, fromPackageDirectory) => [
+    "what happened: require.resolve('effect') resolves to a different " +
+        `file depending on where it is called from — from the consumer ` +
+        `root: ${fromConsumerRoot ?? '(could not resolve)'}; from the ` +
+        `package's own directory: ${fromPackageDirectory ?? '(could not resolve)'}.`,
+    WHY_ONE_COPY_MATTERS,
+    WHAT_TO_DO,
+].join('\n');
+/**
+ * Registers a vitest suite that fails when a tree holds more than one copy of
+ * Effect.
+ *
+ * Registers a vitest suite that fails if more than one physical copy of the
+ * `effect` package is reachable from a consumer's `node_modules` tree, or if
+ * `require.resolve('effect')` disagrees between the consumer root and this
+ * package's own installed directory. Call it from a consumer's `*.test.ts`
+ * file — effect is a peer dependency precisely so the consumer keeps a single
+ * instance, and this is the guard that makes that invariant loud instead of
+ * silent (see `dec-20260902-8898ccfd`). It walks `node_modules` rather than
+ * the repository, so it takes no floor option; instead it refuses on zero
+ * copies found and on a resolution that answers nothing, because a comparison
+ * over an empty walk passes every time.
+ */
+export const oneEffectInstanceGuard = (options = {}) => {
+    const root = options.root ?? repoRoot();
+    const packageOwnDirectory = fileURLToPath(new URL('.', import.meta.url));
+    describe('machinery: effect lives in a single instance', () => {
+        it('node_modules holds exactly one physical copy of effect', () => {
+            const found = [];
+            walkForEffectCopies(join(root, 'node_modules'), new Set(), found);
+            const distinctDirectories = [
+                ...new Set(found.map((copy) => copy.packageDirectory)),
+            ].sort();
+            const violation = distinctDirectories.length > 1 ? distinctDirectories : [];
+            console.log(`effect single instance: found ${distinctDirectories.length} copy ` +
+                `or copies under ${root}/node_modules`);
+            expect(distinctDirectories.length, noCopyAtAllMessage(root)).toBeGreaterThanOrEqual(1);
+            expect(violation, tooManyCopiesMessage(distinctDirectories)).toEqual([]);
+        });
+        it("require.resolve('effect') agrees from the consumer root and the package's own directory", () => {
+            const fromConsumerRoot = resolveEffectEntryFrom(root);
+            const fromPackageDirectory = resolveEffectEntryFrom(packageOwnDirectory);
+            expect(fromConsumerRoot, resolveMismatchMessage(fromConsumerRoot, fromPackageDirectory)).toBeDefined();
+            expect(fromConsumerRoot, resolveMismatchMessage(fromConsumerRoot, fromPackageDirectory)).toBe(fromPackageDirectory);
+        });
+    });
+};

package/dist/vitest/fast-check-single-instance.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Registers a vitest suite that fails when the property library resolves to
+ * two module instances.
+ *
+ * Registers a vitest suite that fails if the direct `fast-check` import and
+ * `effect/FastCheck` resolve to two separate module instances — a split that
+ * silently breaks arbitraries built from one being usable in a property built
+ * from the other. Call it from a consumer's `*.test.ts` file that depends on
+ * both `effect` and `fast-check`.
+ */
+export declare const oneFastCheckInstanceGuard: () => void;

package/dist/vitest/fast-check-single-instance.js

@@ -0,0 +1,26 @@
+import * as viaEffect from 'effect/FastCheck';
+import * as direct from 'fast-check';
+import { describe, expect, it } from 'vitest';
+/**
+ * Registers a vitest suite that fails when the property library resolves to
+ * two module instances.
+ *
+ * Registers a vitest suite that fails if the direct `fast-check` import and
+ * `effect/FastCheck` resolve to two separate module instances — a split that
+ * silently breaks arbitraries built from one being usable in a property built
+ * from the other. Call it from a consumer's `*.test.ts` file that depends on
+ * both `effect` and `fast-check`.
+ */
+export const oneFastCheckInstanceGuard = () => {
+    describe('machinery: fast-check lives in a single instance', () => {
+        it('the direct import and effect/FastCheck are the same module', () => {
+            expect(direct.integer).toBe(viaEffect.integer);
+            expect(direct.bigInt).toBe(viaEffect.bigInt);
+            expect(direct.property).toBe(viaEffect.property);
+        });
+        it('an arbitrary from the direct import works in an effect property', () => {
+            const outcome = viaEffect.check(viaEffect.property(direct.bigInt({ min: -8n, max: 8n }), (value) => typeof value === 'bigint'), { numRuns: 25 });
+            expect(outcome.failed).toBe(false);
+        });
+    });
+};

package/dist/vitest/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Public entry to the vitest mechanism: live stands, port contracts, and
+ * the guards that read the test runtime. It gives you fixtures tied to the
+ * test runner — suites on live stands (Postgres and the localstack AWS
+ * stand, both in containers), port contracts, the settings contract, a stub
+ * HTTP server, and the three guards that hold the runtime this package
+ * loads. The guards that hold a tree to its written canon ship separately,
+ * as `@satorio/canon`.
+ */
+export { oneEffectInstanceGuard } from './effect-single-instance.js';
+export { oneFastCheckInstanceGuard } from './fast-check-single-instance.js';
+export { type AwsStand, LOCALSTACK_REGION, onLocalstack, } from './localstack-container.js';
+export type { PortContractTester } from './port-contract-tester.js';
+export { blobStoreContract, storedBlob, } from './port-contracts/blob-store.contract.js';
+export { documentNumberCounterContract } from './port-contracts/document-number-counter.contract.js';
+export { eventPublisherContract, outboxEvent, } from './port-contracts/event-publisher.contract.js';
+export { externalHttpClientContract } from './port-contracts/external-http-client.contract.js';
+export { integrationEventOutboxContract, outboxMessage, } from './port-contracts/integration-event-outbox.contract.js';
+export { processedEventRegistryContract } from './port-contracts/processed-event-registry.contract.js';
+export { queueMessageProducerContract } from './port-contracts/queue-message-producer.contract.js';
+export { queueMessageSourceContract } from './port-contracts/queue-message-source.contract.js';
+export { readinessProbeContract } from './port-contracts/readiness-probe.contract.js';
+export { transactionBoundaryContract } from './port-contracts/transaction-boundary.contract.js';
+export { onPostgres, onPostgresContainer, POSTGRES_IMAGE, PostgresPortsUnderTestLive, postgresInContainerLive, postgresUnderTestLive, } from './postgres-container.js';
+export { type ReaderPortUnderTest, readerPortContract, } from './reader-port-contract.js';
+export { repoCommittableFiles, repoFilesUnder, repoRoot, } from './repo-source-files.js';
+export { truncateTables } from './reset-tables.js';
+export { settingsContract } from './settings-contract.js';
+export { type RecordedStubRequest, type StubResponse, type StubRoute, scopedStubServer, } from './stub-server.js';
+export { FILES_THAT_FORK_A_FIBER_AND_ADJUST_TEST_CLOCK } from './testclock-fork-isolated-files.js';
+export { testclockForkIsolationGuard } from './testclock-fork-isolation.js';

package/dist/vitest/index.js

@@ -0,0 +1,30 @@
+/**
+ * Public entry to the vitest mechanism: live stands, port contracts, and
+ * the guards that read the test runtime. It gives you fixtures tied to the
+ * test runner — suites on live stands (Postgres and the localstack AWS
+ * stand, both in containers), port contracts, the settings contract, a stub
+ * HTTP server, and the three guards that hold the runtime this package
+ * loads. The guards that hold a tree to its written canon ship separately,
+ * as `@satorio/canon`.
+ */
+export { oneEffectInstanceGuard } from './effect-single-instance.js';
+export { oneFastCheckInstanceGuard } from './fast-check-single-instance.js';
+export { LOCALSTACK_REGION, onLocalstack, } from './localstack-container.js';
+export { blobStoreContract, storedBlob, } from './port-contracts/blob-store.contract.js';
+export { documentNumberCounterContract } from './port-contracts/document-number-counter.contract.js';
+export { eventPublisherContract, outboxEvent, } from './port-contracts/event-publisher.contract.js';
+export { externalHttpClientContract } from './port-contracts/external-http-client.contract.js';
+export { integrationEventOutboxContract, outboxMessage, } from './port-contracts/integration-event-outbox.contract.js';
+export { processedEventRegistryContract } from './port-contracts/processed-event-registry.contract.js';
+export { queueMessageProducerContract } from './port-contracts/queue-message-producer.contract.js';
+export { queueMessageSourceContract } from './port-contracts/queue-message-source.contract.js';
+export { readinessProbeContract } from './port-contracts/readiness-probe.contract.js';
+export { transactionBoundaryContract } from './port-contracts/transaction-boundary.contract.js';
+export { onPostgres, onPostgresContainer, POSTGRES_IMAGE, PostgresPortsUnderTestLive, postgresInContainerLive, postgresUnderTestLive, } from './postgres-container.js';
+export { readerPortContract, } from './reader-port-contract.js';
+export { repoCommittableFiles, repoFilesUnder, repoRoot, } from './repo-source-files.js';
+export { truncateTables } from './reset-tables.js';
+export { settingsContract } from './settings-contract.js';
+export { scopedStubServer, } from './stub-server.js';
+export { FILES_THAT_FORK_A_FIBER_AND_ADJUST_TEST_CLOCK } from './testclock-fork-isolated-files.js';
+export { testclockForkIsolationGuard } from './testclock-fork-isolation.js';

package/dist/vitest/localstack-container.d.ts

@@ -0,0 +1,32 @@
+import { type Vitest } from '@effect/vitest';
+/**
+ * The one region every client and resource in a suite agrees on. The
+ * value itself is arbitrary; what matters is that nothing in the suite
+ * reaches for a second one.
+ */
+export declare const LOCALSTACK_REGION = "eu-central-1";
+type SuiteChecks = (it: Vitest.MethodsNonLive<never, true>) => void;
+/**
+ * The address and the region of the live AWS stand a suite talks to.
+ */
+export interface AwsStand {
+    readonly endpoint: string;
+    readonly region: string;
+}
+/**
+ * `prepare` sets up the suite's own AWS resources (bucket, topic, queue) and
+ * returns the environment variables the machinery needs to find them. If
+ * setup fails, the suite fails too.
+ *
+ * @internal
+ */
+export interface LocalstackSuiteOptions {
+    readonly prepare: (stand: AwsStand) => Promise<ReadonlyMap<string, string>>;
+}
+/**
+ * Runs a suite against a real AWS stand (localstack) for `subject`. Pass
+ * `checks` to declare the tests, and `options.prepare` to seed AWS resources
+ * before they run.
+ */
+export declare const onLocalstack: (options: LocalstackSuiteOptions, subject: string, checks: SuiteChecks) => void;
+export {};

package/dist/vitest/localstack-container.js

@@ -0,0 +1,55 @@
+import { layer } from '@effect/vitest';
+import { LocalstackContainer } from '@testcontainers/localstack';
+import { Config, ConfigProvider, Duration, Effect, Layer, Option, } from 'effect';
+import { standsMayBeReused } from './container-reuse.js';
+const LOCALSTACK_IMAGE = 'localstack/localstack:4.9';
+/**
+ * The one region every client and resource in a suite agrees on. The
+ * value itself is arbitrary; what matters is that nothing in the suite
+ * reaches for a second one.
+ */
+export const LOCALSTACK_REGION = 'eu-central-1';
+const SUITE_STARTUP_BUDGET = Duration.minutes(5);
+// @effect-diagnostics effect/processEnvInEffect:off
+const ensureSdkCredentials = Effect.sync(() => {
+    delete process.env.AWS_PROFILE;
+    process.env.AWS_ACCESS_KEY_ID ??= 'test';
+    process.env.AWS_SECRET_ACCESS_KEY ??= 'test';
+});
+// @effect-diagnostics effect/processEnvInEffect:error
+const REUSING_STANDS = standsMayBeReused();
+const startedContainer = Effect.acquireRelease(Effect.promise(() => {
+    const container = new LocalstackContainer(LOCALSTACK_IMAGE);
+    return (REUSING_STANDS ? container.withReuse() : container).start();
+}), (container) => REUSING_STANDS ? Effect.void : Effect.promise(() => container.stop()));
+const containerStand = Effect.map(startedContainer, (container) => ({
+    endpoint: container.getConnectionUri(),
+    region: LOCALSTACK_REGION,
+}));
+const externallyConfiguredStand = Config.all({
+    endpoint: Config.string('AWS_ENDPOINT_URL'),
+    region: Config.string('AWS_REGION').pipe(Config.withDefault(LOCALSTACK_REGION)),
+});
+const standUnderTest = Effect.flatMap(Config.option(externallyConfiguredStand), Option.match({
+    onSome: (Effect.succeed),
+    onNone: () => containerStand,
+}));
+const configuredStand = (options) => Layer.unwrapScoped(Effect.gen(function* () {
+    yield* ensureSdkCredentials;
+    const stand = yield* standUnderTest;
+    const prepared = yield* Effect.promise(() => options.prepare(stand));
+    return Layer.setConfigProvider(ConfigProvider.fromMap(new Map([
+        ['AWS_ENDPOINT_URL', stand.endpoint],
+        ['AWS_REGION', stand.region],
+        ...prepared,
+    ])));
+})).pipe(Layer.orDie);
+/**
+ * Runs a suite against a real AWS stand (localstack) for `subject`. Pass
+ * `checks` to declare the tests, and `options.prepare` to seed AWS resources
+ * before they run.
+ */
+export const onLocalstack = (options, subject, checks) => layer(configuredStand(options), {
+    excludeTestServices: true,
+    timeout: SUITE_STARTUP_BUDGET,
+})(subject, checks);

package/dist/vitest/port-contract-tester.d.ts

@@ -0,0 +1,8 @@
+import type { Vitest } from '@effect/vitest';
+/**
+ * The subset of vitest test methods a port contract needs from its tester.
+ * Pass the tester that matches the runtime under test — plain `it` for
+ * in-memory implementations, or an `it.layer` suite's `it` for a live
+ * Postgres.
+ */
+export type PortContractTester = Pick<Vitest.MethodsNonLive<never, true>, 'effect'>;

package/dist/vitest/port-contract-tester.js

@@ -0,0 +1 @@
+export {};

package/dist/vitest/port-contracts/blob-store.contract.d.ts

@@ -0,0 +1,22 @@
+import { BlobStore, type StoredBlob } from '@satorio/machinery/ports';
+import { type Layer } from 'effect';
+import type { PortContractTester } from '../port-contract-tester.js';
+/**
+ * One blob a contract stores and reads back, so every implementation is asked
+ * the same question.
+ */
+export declare const storedBlob: (text: string) => StoredBlob;
+/**
+ * One contract, every blob store. The same body runs against an
+ * in-memory store and a live S3 store, 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:
+ * every operation fails, and the failure reaches the caller.
+ *
+ * What this contract cannot prove: that a real S3 answers an absent key
+ * the way the in-memory store does. Both sides of that promise are held
+ * here, and only the live run in
+ * `src/storage/ports.localstack.test.ts` proves the S3 half of
+ * it — the fake decides its own answer, the bucket does not.
+ */
+export declare const blobStoreContract: (it: PortContractTester, implementationName: string, layer: Layer.Layer<BlobStore>, unavailable?: Layer.Layer<BlobStore>) => void;

package/dist/vitest/port-contracts/blob-store.contract.js

@@ -0,0 +1,108 @@
+import { describe, expect } from '@effect/vitest';
+import { BlobStore } from '@satorio/machinery/ports';
+import { Effect, Option } from 'effect';
+const encoder = new TextEncoder();
+/**
+ * One blob a contract stores and reads back, so every implementation is asked
+ * the same question.
+ */
+export const storedBlob = (text) => ({
+    body: encoder.encode(text),
+    contentType: 'text/plain',
+    metadata: { origin: 'contract' },
+});
+/**
+ * One contract, every blob store. The same body runs against an
+ * in-memory store and a live S3 store, 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:
+ * every operation fails, and the failure reaches the caller.
+ *
+ * What this contract cannot prove: that a real S3 answers an absent key
+ * the way the in-memory store does. Both sides of that promise are held
+ * here, and only the live run in
+ * `src/storage/ports.localstack.test.ts` proves the S3 half of
+ * it — the fake decides its own answer, the bucket does not.
+ */
+export const blobStoreContract = (it, implementationName, layer, unavailable) => {
+    const run = (effect) => Effect.provide(effect, layer);
+    describe(`BlobStore contract (${implementationName})`, () => {
+        it.effect('what is put is read back the same: bytes, content type, metadata', () => run(Effect.gen(function* () {
+            const store = yield* BlobStore;
+            const blob = {
+                body: encoder.encode('hello, store'),
+                contentType: 'text/plain',
+                metadata: { origin: 'contract', kind: 'greeting' },
+            };
+            yield* store.put('blob-1', blob);
+            const fetched = yield* store.get('blob-1');
+            expect(Option.isSome(fetched)).toBe(true);
+            if (Option.isSome(fetched)) {
+                expect(fetched.value.body).toEqual(blob.body);
+                expect(fetched.value.contentType).toBe('text/plain');
+                expect(fetched.value.metadata).toEqual(blob.metadata);
+            }
+        })));
+        it.effect('an unknown key is Option.none, not a failure', () => run(Effect.gen(function* () {
+            const store = yield* BlobStore;
+            const fetched = yield* store.get('blob-never-put');
+            expect(Option.isNone(fetched)).toBe(true);
+        })));
+        it.effect('exists reports false before put and true after', () => run(Effect.gen(function* () {
+            const store = yield* BlobStore;
+            const before = yield* store.exists('blob-2');
+            yield* store.put('blob-2', storedBlob('appeared'));
+            const after = yield* store.exists('blob-2');
+            expect(before).toBe(false);
+            expect(after).toBe(true);
+        })));
+        it.effect('putting the same key again replaces the object', () => run(Effect.gen(function* () {
+            const store = yield* BlobStore;
+            yield* store.put('blob-3', storedBlob('first version'));
+            yield* store.put('blob-3', storedBlob('second version'));
+            const fetched = yield* store.get('blob-3');
+            expect(Option.isSome(fetched)).toBe(true);
+            if (Option.isSome(fetched)) {
+                expect(new TextDecoder().decode(fetched.value.body)).toBe('second version');
+            }
+        })));
+        it.effect('after delete, the key is gone', () => run(Effect.gen(function* () {
+            const store = yield* BlobStore;
+            yield* store.put('blob-4', storedBlob('temporary'));
+            yield* store.delete('blob-4');
+            const fetched = yield* store.get('blob-4');
+            const present = yield* store.exists('blob-4');
+            expect(Option.isNone(fetched)).toBe(true);
+            expect(present).toBe(false);
+        })));
+        it.effect('deleting an absent key does not fail', () => run(Effect.gen(function* () {
+            const store = yield* BlobStore;
+            yield* store.delete('blob-never-put');
+        })));
+    });
+    if (unavailable === undefined)
+        return;
+    describe(`BlobStore contract (${implementationName}, not mounted)`, () => {
+        it.effect('every operation fails, and the caller reads the refusal', () => Effect.gen(function* () {
+            const store = yield* BlobStore;
+            const refusals = yield* Effect.all([
+                Effect.flip(store.put('blob-5', storedBlob('never stored'))),
+                Effect.flip(store.get('blob-5')),
+                Effect.flip(store.exists('blob-5')),
+                Effect.flip(store.delete('blob-5')),
+            ]);
+            expect(refusals.map((refusal) => refusal._tag)).toEqual([
+                'BlobStoreUnavailableError',
+                'BlobStoreUnavailableError',
+                'BlobStoreUnavailableError',
+                'BlobStoreUnavailableError',
+            ]);
+            expect(refusals.map((refusal) => refusal.operation)).toEqual([
+                'put',
+                'get',
+                'exists',
+                'delete',
+            ]);
+        }).pipe(Effect.provide(unavailable)));
+    });
+};

package/dist/vitest/port-contracts/document-number-counter.contract.d.ts

@@ -0,0 +1,18 @@
+import { DocumentNumberCounter } from '@satorio/machinery/ports';
+import { type Layer } from 'effect';
+import type { PortContractTester } from '../port-contract-tester.js';
+/**
+ * One contract, every counter implementation. The same body runs against
+ * an in-memory counter and a live Postgres counter, so a difference
+ * between them shows up as a red test rather than as two documents
+ * carrying one number. Hand it the port's unavailable stand-in as a
+ * fourth argument and it walks the refusal too.
+ *
+ * What this contract cannot prove: that two callers asking for the same
+ * client and month at the same instant get two different counts. The
+ * in-memory counter 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 row lock behind the
+ * count.
+ */
+export declare const documentNumberCounterContract: (it: PortContractTester, implementationName: string, layer: Layer.Layer<DocumentNumberCounter>, unavailable?: Layer.Layer<DocumentNumberCounter>) => void;

package/dist/vitest/port-contracts/document-number-counter.contract.js

@@ -0,0 +1,90 @@
+import { describe, expect } from '@effect/vitest';
+import { DocumentNumberCounter } from '@satorio/machinery/ports';
+import { Effect } from 'effect';
+const A_CLIENT = '41738297';
+const ANOTHER_CLIENT = '55511122';
+const SEPTEMBER = '2609';
+const OCTOBER = '2610';
+/**
+ * One contract, every counter implementation. The same body runs against
+ * an in-memory counter and a live Postgres counter, so a difference
+ * between them shows up as a red test rather than as two documents
+ * carrying one number. Hand it the port's unavailable stand-in as a
+ * fourth argument and it walks the refusal too.
+ *
+ * What this contract cannot prove: that two callers asking for the same
+ * client and month at the same instant get two different counts. The
+ * in-memory counter 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 row lock behind the
+ * count.
+ */
+export const documentNumberCounterContract = (it, implementationName, layer, unavailable) => {
+    const run = (effect) => Effect.provide(effect, layer);
+    describe(`DocumentNumberCounter contract (${implementationName})`, () => {
+        it.effect('the first document of a month is the first one', () => run(Effect.gen(function* () {
+            const counter = yield* DocumentNumberCounter;
+            const count = yield* counter.nextCount({
+                clientCode: A_CLIENT,
+                reportingMonth: SEPTEMBER,
+            });
+            expect(count).toBe(1);
+        })));
+        it.effect('the next document of that month steps past it', () => run(Effect.gen(function* () {
+            const counter = yield* DocumentNumberCounter;
+            const input = {
+                clientCode: ANOTHER_CLIENT,
+                reportingMonth: SEPTEMBER,
+            };
+            const first = yield* counter.nextCount(input);
+            const second = yield* counter.nextCount(input);
+            const third = yield* counter.nextCount(input);
+            expect([first, second, third]).toEqual([1, 2, 3]);
+        })));
+        it.effect('a new month starts its own count', () => run(Effect.gen(function* () {
+            const counter = yield* DocumentNumberCounter;
+            yield* counter.nextCount({
+                clientCode: A_CLIENT,
+                reportingMonth: OCTOBER,
+            });
+            yield* counter.nextCount({
+                clientCode: A_CLIENT,
+                reportingMonth: OCTOBER,
+            });
+            const november = yield* counter.nextCount({
+                clientCode: A_CLIENT,
+                reportingMonth: '2611',
+            });
+            expect(november).toBe(1);
+        })));
+        it.effect('one client never moves another client count', () => run(Effect.gen(function* () {
+            const counter = yield* DocumentNumberCounter;
+            yield* counter.nextCount({
+                clientCode: A_CLIENT,
+                reportingMonth: '2612',
+            });
+            yield* counter.nextCount({
+                clientCode: A_CLIENT,
+                reportingMonth: '2612',
+            });
+            const other = yield* counter.nextCount({
+                clientCode: ANOTHER_CLIENT,
+                reportingMonth: '2612',
+            });
+            expect(other).toBe(1);
+        })));
+    });
+    if (unavailable === undefined)
+        return;
+    describe(`DocumentNumberCounter contract (${implementationName}, not mounted)`, () => {
+        it.effect('the count fails, and the caller reads the refusal', () => Effect.gen(function* () {
+            const counter = yield* DocumentNumberCounter;
+            const refusal = yield* Effect.flip(counter.nextCount({
+                clientCode: A_CLIENT,
+                reportingMonth: SEPTEMBER,
+            }));
+            expect(refusal._tag).toBe('DocumentNumberCounterUnavailableError');
+            expect(refusal.operation).toBe('nextCount');
+        }).pipe(Effect.provide(unavailable)));
+    });
+};

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

@@ -0,0 +1,35 @@
+import { EventPublisher, type OutboxMessage } from '@satorio/machinery/ports';
+import { Effect, type Layer } from 'effect';
+import type { PortContractTester } from '../port-contract-tester.js';
+/**
+ * One message, built the way an outbox hands it over.
+ */
+export declare const outboxEvent: (messageId: string, payload: {
+    readonly [key: string]: unknown;
+}) => OutboxMessage;
+/**
+ * One publisher, described the way a contract can hold it: the layer
+ * that mounts the port, and the one call that reads back the message ids
+ * that reached whatever stands behind it.
+ *
+ * @internal
+ */
+export interface PublisherUnderTest {
+    readonly layer: Layer.Layer<EventPublisher>;
+    readonly delivered: Effect.Effect<readonly string[]>;
+}
+/**
+ * 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 declare const eventPublisherContract: (it: PortContractTester, implementationName: string, publisher: PublisherUnderTest, unavailable?: Layer.Layer<EventPublisher>) => void;