@satorio/machinery 0.2.1

package/dist/testing/event-publisher.d.ts

@@ -0,0 +1,28 @@
+import { EventPublisher, type EventPublisherShape, type OutboxMessage } from '@satorio/machinery/ports';
+import { Effect, Layer, Ref } from 'effect';
+/**
+ * What an in-memory publisher holds: every message it was handed, in the
+ * order the batches arrived. A scenario keeps the `Ref` and reads this
+ * list to see what a procedure published.
+ */
+export type PublishedMessages = readonly OutboxMessage[];
+/**
+ * An in-memory publisher over a `Ref` you keep, so a test reads what was
+ * published after the run.
+ */
+export declare const makeInMemoryEventPublisherWith: (published: Ref.Ref<PublishedMessages>) => EventPublisherShape;
+/**
+ * An in-memory publisher over a `Ref` of its own, empty at the start.
+ */
+export declare const makeInMemoryEventPublisher: Effect.Effect<EventPublisherShape, never, never>;
+/**
+ * The in-memory publisher, mounted.
+ */
+export declare const InMemoryEventPublisherLive: Layer.Layer<EventPublisher, never, never>;
+/**
+ * A publisher that takes nothing: every publish fails with
+ * `EventPublisherUnavailableError`. Mount it to walk the branch a
+ * working stand-in never reaches — the outbox relay that has to leave
+ * its messages where they are.
+ */
+export declare const EventPublisherUnavailableLive: Layer.Layer<EventPublisher>;

package/dist/testing/event-publisher.js

@@ -0,0 +1,33 @@
+import { EventPublisher, EventPublisherUnavailableError, } from '@satorio/machinery/ports';
+import { Effect, Layer, Ref } from 'effect';
+const NOT_MOUNTED = 'event publisher unavailable (test)';
+/**
+ * An in-memory publisher over a `Ref` you keep, so a test reads what was
+ * published after the run.
+ */
+export const makeInMemoryEventPublisherWith = (published) => ({
+    publish: (messages) => Ref.update(published, (current) => [...current, ...messages]),
+});
+/**
+ * An in-memory publisher over a `Ref` of its own, empty at the start.
+ */
+export const makeInMemoryEventPublisher = Effect.gen(function* () {
+    const published = yield* Ref.make([]);
+    return makeInMemoryEventPublisherWith(published);
+});
+/**
+ * The in-memory publisher, mounted.
+ */
+export const InMemoryEventPublisherLive = Layer.effect(EventPublisher, makeInMemoryEventPublisher);
+/**
+ * A publisher that takes nothing: every publish fails with
+ * `EventPublisherUnavailableError`. Mount it to walk the branch a
+ * working stand-in never reaches — the outbox relay that has to leave
+ * its messages where they are.
+ */
+export const EventPublisherUnavailableLive = Layer.succeed(EventPublisher, {
+    publish: () => Effect.fail(new EventPublisherUnavailableError({
+        operation: 'publish',
+        cause: NOT_MOUNTED,
+    })),
+});

package/dist/testing/external-http-client.d.ts

@@ -0,0 +1,29 @@
+import { ExternalHttpClient, type ExternalHttpClientShape } from '@satorio/machinery/ports';
+import { Effect, Layer, Ref } from 'effect';
+/**
+ * What an in-memory client answers with: one already-decoded body per
+ * path. A path nobody wrote an answer for is a 404, the way a real
+ * service refuses a URL it does not serve.
+ */
+export type AnswersByPath = Readonly<Record<string, unknown>>;
+/**
+ * An in-memory client over a `Ref` you keep, so a test rewrites what the
+ * service answers between two calls of the same scenario.
+ */
+export declare const makeInMemoryExternalHttpClientWith: (answers: Ref.Ref<AnswersByPath>) => ExternalHttpClientShape;
+/**
+ * An in-memory client over a `Ref` of its own, seeded with the answers
+ * you hand it.
+ */
+export declare const makeInMemoryExternalHttpClient: (answers: AnswersByPath) => Effect.Effect<ExternalHttpClientShape>;
+/**
+ * The in-memory client, mounted, answering the paths you seeded it with.
+ */
+export declare const inMemoryExternalHttpClientLive: (answers: AnswersByPath) => Layer.Layer<ExternalHttpClient>;
+/**
+ * A client that reaches nothing: every call fails with
+ * `ExternalServiceUnavailableError`. Mount it to walk the branch a
+ * working stand-in never reaches — the use case that has to carry on
+ * without the reference service it wanted.
+ */
+export declare const ExternalHttpClientUnavailableLive: Layer.Layer<ExternalHttpClient>;

package/dist/testing/external-http-client.js

@@ -0,0 +1,49 @@
+import { ExternalHttpClient, ExternalServiceRefusedError, ExternalServiceResponseMalformedError, ExternalServiceUnavailableError, } from '@satorio/machinery/ports';
+import { Effect, Layer, Ref, Schema } from 'effect';
+const NOT_MOUNTED = 'external http client unavailable (test)';
+const IN_MEMORY_SERVICE = 'in-memory';
+const GET_JSON = 'getJson';
+const NOT_ANSWERED_STATUS = 404;
+/**
+ * An in-memory client over a `Ref` you keep, so a test rewrites what the
+ * service answers between two calls of the same scenario.
+ */
+export const makeInMemoryExternalHttpClientWith = (answers) => ({
+    getJson: (path, schema) => Effect.gen(function* () {
+        const answered = yield* Ref.get(answers);
+        if (!Object.hasOwn(answered, path)) {
+            return yield* Effect.fail(new ExternalServiceRefusedError({
+                service: IN_MEMORY_SERVICE,
+                operation: GET_JSON,
+                status: NOT_ANSWERED_STATUS,
+            }));
+        }
+        return yield* Schema.decodeUnknown(schema)(answered[path]).pipe(Effect.mapError((cause) => new ExternalServiceResponseMalformedError({
+            service: IN_MEMORY_SERVICE,
+            operation: GET_JSON,
+            cause,
+        })));
+    }),
+});
+/**
+ * An in-memory client over a `Ref` of its own, seeded with the answers
+ * you hand it.
+ */
+export const makeInMemoryExternalHttpClient = (answers) => Effect.map(Ref.make(answers), makeInMemoryExternalHttpClientWith);
+/**
+ * The in-memory client, mounted, answering the paths you seeded it with.
+ */
+export const inMemoryExternalHttpClientLive = (answers) => Layer.effect(ExternalHttpClient, makeInMemoryExternalHttpClient(answers));
+/**
+ * A client that reaches nothing: every call fails with
+ * `ExternalServiceUnavailableError`. Mount it to walk the branch a
+ * working stand-in never reaches — the use case that has to carry on
+ * without the reference service it wanted.
+ */
+export const ExternalHttpClientUnavailableLive = Layer.succeed(ExternalHttpClient, {
+    getJson: () => Effect.fail(new ExternalServiceUnavailableError({
+        service: IN_MEMORY_SERVICE,
+        operation: GET_JSON,
+        cause: NOT_MOUNTED,
+    })),
+});

package/dist/testing/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Public entry to the testing mechanism: a stand-in for every port, a clock a
+ * test drives, and the scenario player. It gives you an in-memory stand-in and
+ * a deliberately unavailable one for every port, a clock a test drives, the
+ * scenario player, the small readers a test uses to look inside what it just
+ * ran, and the settings a test runner and a mutation runner read before either
+ * runtime exists. No production file imports any of it.
+ */
+export { BlobStoreUnavailableLive, type BlobsByKey, InMemoryBlobStoreLive, makeInMemoryBlobStore, makeInMemoryBlobStoreWith, } from './blob-store.js';
+export { advanceBy, atTheMoment, clockPinnedAt, nowAsDateTime, nowAsIsoString, setNowTo, } from './clock.js';
+export { type DocumentCountsByClientAndMonth, DocumentNumberCounterUnavailableLive, InMemoryDocumentNumberCounterLive, makeInMemoryDocumentNumberCounter, makeInMemoryDocumentNumberCounterWith, } from './document-number-counter.js';
+export { EventPublisherUnavailableLive, InMemoryEventPublisherLive, makeInMemoryEventPublisher, makeInMemoryEventPublisherWith, type PublishedMessages, } from './event-publisher.js';
+export { type AnswersByPath, ExternalHttpClientUnavailableLive, inMemoryExternalHttpClientLive, makeInMemoryExternalHttpClient, makeInMemoryExternalHttpClientWith, } from './external-http-client.js';
+export { type DispatchedMessageIds, InMemoryIntegrationEventOutboxLive, IntegrationEventOutboxUnavailableLive, IntegrationEventOutboxUnreadableLive, makeInMemoryIntegrationEventOutbox, makeInMemoryIntegrationEventOutboxWith, type QueuedOutboxMessages, } from './integration-event-outbox.js';
+export { mutationSettings, SUITES_THAT_START_A_STAND, } from './mutation-settings.js';
+export { distinctMomentsIn, emptiedTables, } from './postgres-rows.js';
+export { InMemoryProcessedEventRegistryLive, makeInMemoryProcessedEventRegistry, makeInMemoryProcessedEventRegistryWith, ProcessedEventRegistryUnavailableLive, type ProcessedEventsById, } from './processed-event-registry.js';
+export { InMemoryQueueMessageProducerLive, makeInMemoryQueueMessageProducer, makeInMemoryQueueMessageProducerWith, QueueMessageProducerUnavailableLive, } from './queue-message-producer.js';
+export { InMemoryQueueMessageSourceLive, makeInMemoryQueueMessageSource, makeInMemoryQueueMessageSourceWith, makeScriptedMessageSource, messageOf, type PendingQueueMessages, QueueMessageSourceUnavailableLive, scriptedQueueMessageSourceLive, } from './queue-message-source.js';
+export { QuietReporter, quietReporters, verboseOutputWanted, } from './quiet-reporter.js';
+export { InMemoryReadinessProbeLive, ReadinessProbeUnavailableLive, } from './readiness-probe.js';
+export { contextOf, ensureStepsAreInOrder, firstPassLabelsOf, labelOf, labelOfFailure, momentsOfSteps, playScenario, replayLabelsOf, type Scenario, type ScenarioPlayback, type ScenarioService, type ScenarioStep, } from './scenario.js';
+export { inMemoryTransactionBoundaryLive, makeInMemoryTransactionBoundary, stateOfRef, type TransactionalState, TransactionBoundaryUnavailableLive, } from './transaction-boundary.js';
+export { typedFailureOf } from './typed-failure.js';

package/dist/testing/index.js

@@ -0,0 +1,24 @@
+/**
+ * Public entry to the testing mechanism: a stand-in for every port, a clock a
+ * test drives, and the scenario player. It gives you an in-memory stand-in and
+ * a deliberately unavailable one for every port, a clock a test drives, the
+ * scenario player, the small readers a test uses to look inside what it just
+ * ran, and the settings a test runner and a mutation runner read before either
+ * runtime exists. No production file imports any of it.
+ */
+export { BlobStoreUnavailableLive, InMemoryBlobStoreLive, makeInMemoryBlobStore, makeInMemoryBlobStoreWith, } from './blob-store.js';
+export { advanceBy, atTheMoment, clockPinnedAt, nowAsDateTime, nowAsIsoString, setNowTo, } from './clock.js';
+export { DocumentNumberCounterUnavailableLive, InMemoryDocumentNumberCounterLive, makeInMemoryDocumentNumberCounter, makeInMemoryDocumentNumberCounterWith, } from './document-number-counter.js';
+export { EventPublisherUnavailableLive, InMemoryEventPublisherLive, makeInMemoryEventPublisher, makeInMemoryEventPublisherWith, } from './event-publisher.js';
+export { ExternalHttpClientUnavailableLive, inMemoryExternalHttpClientLive, makeInMemoryExternalHttpClient, makeInMemoryExternalHttpClientWith, } from './external-http-client.js';
+export { InMemoryIntegrationEventOutboxLive, IntegrationEventOutboxUnavailableLive, IntegrationEventOutboxUnreadableLive, makeInMemoryIntegrationEventOutbox, makeInMemoryIntegrationEventOutboxWith, } from './integration-event-outbox.js';
+export { mutationSettings, SUITES_THAT_START_A_STAND, } from './mutation-settings.js';
+export { distinctMomentsIn, emptiedTables, } from './postgres-rows.js';
+export { InMemoryProcessedEventRegistryLive, makeInMemoryProcessedEventRegistry, makeInMemoryProcessedEventRegistryWith, ProcessedEventRegistryUnavailableLive, } from './processed-event-registry.js';
+export { InMemoryQueueMessageProducerLive, makeInMemoryQueueMessageProducer, makeInMemoryQueueMessageProducerWith, QueueMessageProducerUnavailableLive, } from './queue-message-producer.js';
+export { InMemoryQueueMessageSourceLive, makeInMemoryQueueMessageSource, makeInMemoryQueueMessageSourceWith, makeScriptedMessageSource, messageOf, QueueMessageSourceUnavailableLive, scriptedQueueMessageSourceLive, } from './queue-message-source.js';
+export { QuietReporter, quietReporters, verboseOutputWanted, } from './quiet-reporter.js';
+export { InMemoryReadinessProbeLive, ReadinessProbeUnavailableLive, } from './readiness-probe.js';
+export { contextOf, ensureStepsAreInOrder, firstPassLabelsOf, labelOf, labelOfFailure, momentsOfSteps, playScenario, replayLabelsOf, } from './scenario.js';
+export { inMemoryTransactionBoundaryLive, makeInMemoryTransactionBoundary, stateOfRef, TransactionBoundaryUnavailableLive, } from './transaction-boundary.js';
+export { typedFailureOf } from './typed-failure.js';

package/dist/testing/integration-event-outbox.d.ts

@@ -0,0 +1,37 @@
+import { IntegrationEventOutbox, type IntegrationEventOutboxShape, type OutboxMessage } from '@satorio/machinery/ports';
+import { Effect, Layer, Ref } from 'effect';
+/**
+ * What an in-memory outbox holds on the write side: every message
+ * enqueued, in the order it arrived.
+ */
+export type QueuedOutboxMessages = readonly OutboxMessage[];
+/**
+ * What an in-memory outbox holds on the read side: the ids a relay has
+ * already marked as sent.
+ */
+export type DispatchedMessageIds = ReadonlySet<string>;
+/**
+ * An in-memory outbox over two `Ref`s you keep, so a test can seed what
+ * is waiting and read back what the relay dispatched.
+ */
+export declare const makeInMemoryIntegrationEventOutboxWith: (queued: Ref.Ref<QueuedOutboxMessages>, dispatched: Ref.Ref<DispatchedMessageIds>) => IntegrationEventOutboxShape;
+/**
+ * An in-memory outbox over `Ref`s of its own, empty at the start.
+ */
+export declare const makeInMemoryIntegrationEventOutbox: Effect.Effect<IntegrationEventOutboxShape, never, never>;
+/**
+ * The in-memory outbox, mounted.
+ */
+export declare const InMemoryIntegrationEventOutboxLive: Layer.Layer<IntegrationEventOutbox, never, never>;
+/**
+ * An outbox that accepts nothing: `enqueue` refuses, so a use case's
+ * write and its message go down together. Mount it to prove a caller
+ * that records an event keeps the refusal instead of losing it.
+ */
+export declare const IntegrationEventOutboxUnavailableLive: Layer.Layer<IntegrationEventOutbox>;
+/**
+ * An outbox that takes messages and then refuses to hand them back:
+ * `pending` fails while `enqueue` succeeds. Mount it to prove a relay
+ * reports a read it could not make instead of reporting an empty beat.
+ */
+export declare const IntegrationEventOutboxUnreadableLive: Layer.Layer<IntegrationEventOutbox>;

package/dist/testing/integration-event-outbox.js

@@ -0,0 +1,67 @@
+import { IntegrationEventOutbox, IntegrationEventOutboxUnavailableError, } from '@satorio/machinery/ports';
+import { Effect, Layer, Ref } from 'effect';
+const NOT_MOUNTED = 'integration event outbox unavailable (test)';
+/**
+ * An in-memory outbox over two `Ref`s you keep, so a test can seed what
+ * is waiting and read back what the relay dispatched.
+ */
+export const makeInMemoryIntegrationEventOutboxWith = (queued, dispatched) => {
+    const enqueue = (messages) => Ref.update(queued, (current) => {
+        const knownIds = new Set(current.map((message) => message.messageId));
+        const firstAppearance = messages.filter((message) => !knownIds.has(message.messageId));
+        return firstAppearance.length === 0
+            ? current
+            : [...current, ...firstAppearance];
+    });
+    const pending = (limit) => Effect.gen(function* () {
+        const current = yield* Ref.get(queued);
+        const alreadySent = yield* Ref.get(dispatched);
+        return current
+            .filter((message) => !alreadySent.has(message.messageId))
+            .slice(0, limit);
+    });
+    const markDispatched = (messageIds) => Ref.update(dispatched, (current) => new Set([...current, ...messageIds]));
+    return {
+        enqueue,
+        pending,
+        markDispatched,
+    };
+};
+/**
+ * An in-memory outbox over `Ref`s of its own, empty at the start.
+ */
+export const makeInMemoryIntegrationEventOutbox = Effect.gen(function* () {
+    const queued = yield* Ref.make([]);
+    const dispatched = yield* Ref.make(new Set());
+    return makeInMemoryIntegrationEventOutboxWith(queued, dispatched);
+});
+/**
+ * The in-memory outbox, mounted.
+ */
+export const InMemoryIntegrationEventOutboxLive = Layer.effect(IntegrationEventOutbox, makeInMemoryIntegrationEventOutbox);
+/**
+ * An outbox that accepts nothing: `enqueue` refuses, so a use case's
+ * write and its message go down together. Mount it to prove a caller
+ * that records an event keeps the refusal instead of losing it.
+ */
+export const IntegrationEventOutboxUnavailableLive = Layer.succeed(IntegrationEventOutbox, {
+    enqueue: () => new IntegrationEventOutboxUnavailableError({
+        operation: 'enqueue',
+        cause: NOT_MOUNTED,
+    }),
+    pending: () => Effect.succeed([]),
+    markDispatched: () => Effect.void,
+});
+/**
+ * An outbox that takes messages and then refuses to hand them back:
+ * `pending` fails while `enqueue` succeeds. Mount it to prove a relay
+ * reports a read it could not make instead of reporting an empty beat.
+ */
+export const IntegrationEventOutboxUnreadableLive = Layer.succeed(IntegrationEventOutbox, {
+    enqueue: () => Effect.void,
+    pending: () => new IntegrationEventOutboxUnavailableError({
+        operation: 'pending',
+        cause: NOT_MOUNTED,
+    }),
+    markDispatched: () => Effect.void,
+});

package/dist/testing/mutation-settings.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The suites that start a live stand, by the file name A11 gives them.
+ * A mutation run never wants these: every mutant would start its own
+ * database or its own AWS stand, and a container that never comes up
+ * looks exactly like a mutant that never returns.
+ */
+export declare const SUITES_THAT_START_A_STAND: readonly string[];
+/**
+ * What a service tells the mutation runner about itself: which files to
+ * mutate, which test-runner configuration the mutant runs against, and
+ * the two numbers a bigger machine may raise.
+ *
+ * @internal
+ */
+export interface MutationSettingsOptions {
+    readonly mutate: readonly string[];
+    readonly vitestConfigFile: string;
+    readonly tsconfigFile?: string;
+    readonly concurrency?: number;
+}
+/**
+ * The settings of one mutation run, in the shape the runner's own
+ * configuration file takes.
+ *
+ * @internal
+ */
+export interface MutationSettings {
+    readonly testRunner: string;
+    readonly plugins: readonly string[];
+    readonly vitest: {
+        readonly configFile: string;
+    };
+    readonly checkers: readonly string[];
+    readonly tsconfigFile: string;
+    readonly mutate: readonly string[];
+    readonly reporters: readonly string[];
+    readonly thresholds: {
+        readonly high: number;
+        readonly low: number;
+        readonly break: number | null;
+    };
+    readonly concurrency: number;
+    readonly timeoutMS: number;
+    readonly timeoutFactor: number;
+    readonly dryRunTimeoutMinutes: number;
+    readonly tempDirName: string;
+    readonly cleanTempDir: boolean;
+}
+/**
+ * How many mutants run beside each other when nobody says. The runner
+ * starts one type checker and one test runner per unit of concurrency,
+ * and each type checker holds a whole TypeScript program in memory, so
+ * the default here stays well under the core count a machine reports.
+ * Raise it deliberately, on a machine you know has the memory.
+ *
+ * @internal
+ */
+export declare const defaultConcurrency: (cores: number) => number;
+/**
+ * Everything a mutation run needs, with the waits bounded and the live
+ * stands kept out. Hand it the files to mutate and the test-runner
+ * configuration the mutants run against; take the rest as it comes.
+ *
+ * Three of these numbers exist because a run that hangs reports no score
+ * at all. `timeoutMS` and `timeoutFactor` bound one mutant, so a mutant
+ * that turns a loop endless is killed as a timeout rather than waited
+ * on. `dryRunTimeoutMinutes` bounds the run that happens before any
+ * mutant, where a suite that needs a stand nobody started would
+ * otherwise wait for ever.
+ */
+export declare const mutationSettings: (options: MutationSettingsOptions) => MutationSettings;

package/dist/testing/mutation-settings.js

@@ -0,0 +1,57 @@
+import { availableParallelism } from 'node:os';
+/**
+ * The suites that start a live stand, by the file name A11 gives them.
+ * A mutation run never wants these: every mutant would start its own
+ * database or its own AWS stand, and a container that never comes up
+ * looks exactly like a mutant that never returns.
+ */
+export const SUITES_THAT_START_A_STAND = [
+    '**/*.postgres.test.ts',
+    '**/*.localstack.test.ts',
+];
+const HIGHEST_DEFAULT_CONCURRENCY = 4;
+/**
+ * How many mutants run beside each other when nobody says. The runner
+ * starts one type checker and one test runner per unit of concurrency,
+ * and each type checker holds a whole TypeScript program in memory, so
+ * the default here stays well under the core count a machine reports.
+ * Raise it deliberately, on a machine you know has the memory.
+ *
+ * @internal
+ */
+export const defaultConcurrency = (cores) => Math.max(1, Math.min(HIGHEST_DEFAULT_CONCURRENCY, cores - 1));
+/**
+ * Everything a mutation run needs, with the waits bounded and the live
+ * stands kept out. Hand it the files to mutate and the test-runner
+ * configuration the mutants run against; take the rest as it comes.
+ *
+ * Three of these numbers exist because a run that hangs reports no score
+ * at all. `timeoutMS` and `timeoutFactor` bound one mutant, so a mutant
+ * that turns a loop endless is killed as a timeout rather than waited
+ * on. `dryRunTimeoutMinutes` bounds the run that happens before any
+ * mutant, where a suite that needs a stand nobody started would
+ * otherwise wait for ever.
+ */
+export const mutationSettings = (options) => ({
+    testRunner: 'vitest',
+    plugins: [
+        '@stryker-mutator/vitest-runner',
+        '@stryker-mutator/typescript-checker',
+    ],
+    vitest: { configFile: options.vitestConfigFile },
+    checkers: ['typescript'],
+    tsconfigFile: options.tsconfigFile ?? 'tsconfig.json',
+    mutate: [
+        ...options.mutate,
+        '!**/*.test.ts',
+        ...SUITES_THAT_START_A_STAND.map((suite) => `!${suite}`),
+    ],
+    reporters: ['clear-text', 'progress', 'html', 'json'],
+    thresholds: { high: 80, low: 60, break: null },
+    concurrency: options.concurrency ?? defaultConcurrency(availableParallelism()),
+    timeoutMS: 15_000,
+    timeoutFactor: 2,
+    dryRunTimeoutMinutes: 5,
+    tempDirName: '.stryker-tmp',
+    cleanTempDir: true,
+});

package/dist/testing/postgres-rows.d.ts

@@ -0,0 +1,12 @@
+import { SqlClient } from '@effect/sql';
+import { Effect } from 'effect';
+/**
+ * Empties the given tables on the live stand so a scenario starts
+ * from zero, the way a freshly reset database does for the seeder.
+ */
+export declare const emptiedTables: (tables: readonly string[]) => Effect.Effect<void, never, SqlClient.SqlClient>;
+/**
+ * Reads the distinct moments in one timestamp column, as sorted ISO
+ * strings in the same format `momentsOfSteps` returns for a scenario.
+ */
+export declare const distinctMomentsIn: (table: string, column: string) => Effect.Effect<readonly string[], never, SqlClient.SqlClient>;

package/dist/testing/postgres-rows.js

@@ -0,0 +1,19 @@
+import { SqlClient } from '@effect/sql';
+import { DateTime, Effect } from 'effect';
+/**
+ * Empties the given tables on the live stand so a scenario starts
+ * from zero, the way a freshly reset database does for the seeder.
+ */
+export const emptiedTables = (tables) => Effect.flatMap(SqlClient.SqlClient, (sql) => sql.unsafe(`TRUNCATE TABLE ${tables.join(', ')}`)).pipe(Effect.asVoid, Effect.orDie);
+/**
+ * Reads the distinct moments in one timestamp column, as sorted ISO
+ * strings in the same format `momentsOfSteps` returns for a scenario.
+ */
+export const distinctMomentsIn = (table, column) => Effect.flatMap(SqlClient.SqlClient, (sql) => sql `
+      SELECT DISTINCT ${sql.unsafe(column)} AS moment
+      FROM ${sql.unsafe(table)}
+    `).pipe(Effect.map((rows) => rows
+    .flatMap((row) => row.moment === null
+    ? []
+    : [DateTime.formatIso(DateTime.unsafeMake(row.moment))])
+    .toSorted()), Effect.orDie);

package/dist/testing/processed-event-registry.d.ts

@@ -0,0 +1,25 @@
+import { ProcessedEventRegistry, type ProcessedEventRegistryShape } from '@satorio/machinery/ports';
+import { type DateTime, Effect, Layer, Ref } from 'effect';
+/**
+ * What an in-memory registry holds: the moment each event id was first
+ * claimed. A scenario seeds this map to say an event was handled before.
+ */
+export type ProcessedEventsById = ReadonlyMap<string, DateTime.Utc>;
+/**
+ * An in-memory registry over a `Ref` you keep, so a test can seed what
+ * was already claimed and read back what the run added.
+ */
+export declare const makeInMemoryProcessedEventRegistryWith: (processed: Ref.Ref<ProcessedEventsById>) => ProcessedEventRegistryShape;
+/**
+ * An in-memory registry over a `Ref` of its own, empty at the start.
+ */
+export declare const makeInMemoryProcessedEventRegistry: Effect.Effect<ProcessedEventRegistryShape, never, never>;
+/**
+ * The in-memory registry, mounted.
+ */
+export declare const InMemoryProcessedEventRegistryLive: Layer.Layer<ProcessedEventRegistry, never, never>;
+/**
+ * A registry that claims nothing: every claim comes back as a refusal.
+ * Mount it to walk the branch a working stand-in never reaches.
+ */
+export declare const ProcessedEventRegistryUnavailableLive: Layer.Layer<ProcessedEventRegistry>;

package/dist/testing/processed-event-registry.js

@@ -0,0 +1,39 @@
+import { alreadyProcessed, claimAccepted, ProcessedEventRegistry, ProcessedEventRegistryUnavailableError, } from '@satorio/machinery/ports';
+import { Effect, Layer, Ref } from 'effect';
+const NOT_MOUNTED = 'processed event registry unavailable (test)';
+/**
+ * An in-memory registry over a `Ref` you keep, so a test can seed what
+ * was already claimed and read back what the run added.
+ */
+export const makeInMemoryProcessedEventRegistryWith = (processed) => ({
+    claim: (input) => Ref.modify(processed, (current) => {
+        const seenAt = current.get(input.eventId);
+        return seenAt === undefined
+            ? [
+                claimAccepted,
+                new Map(current).set(input.eventId, input.processedAt),
+            ]
+            : [alreadyProcessed(seenAt), current];
+    }),
+});
+/**
+ * An in-memory registry over a `Ref` of its own, empty at the start.
+ */
+export const makeInMemoryProcessedEventRegistry = Effect.gen(function* () {
+    const processed = yield* Ref.make(new Map());
+    return makeInMemoryProcessedEventRegistryWith(processed);
+});
+/**
+ * The in-memory registry, mounted.
+ */
+export const InMemoryProcessedEventRegistryLive = Layer.effect(ProcessedEventRegistry, makeInMemoryProcessedEventRegistry);
+/**
+ * A registry that claims nothing: every claim comes back as a refusal.
+ * Mount it to walk the branch a working stand-in never reaches.
+ */
+export const ProcessedEventRegistryUnavailableLive = Layer.succeed(ProcessedEventRegistry, {
+    claim: () => new ProcessedEventRegistryUnavailableError({
+        operation: 'claim',
+        cause: NOT_MOUNTED,
+    }),
+});

package/dist/testing/queue-message-producer.d.ts

@@ -0,0 +1,27 @@
+import { QueueMessageProducer, type QueueMessageProducerShape } from '@satorio/machinery/ports';
+import { Effect, Layer, Ref } from 'effect';
+import { type PendingQueueMessages } from './queue-message-source.js';
+/**
+ * An in-memory producer over the same reference an in-memory source reads.
+ *
+ * An in-memory producer over the same `Ref` an in-memory source reads, so a
+ * test sends on one side and receives on the other, the way a real queue pairs
+ * the two. Each send gets its own message id, counted from what is already on
+ * the queue.
+ */
+export declare const makeInMemoryQueueMessageProducerWith: (pending: Ref.Ref<PendingQueueMessages>) => QueueMessageProducerShape;
+/**
+ * An in-memory producer over a `Ref` of its own, whose messages nobody
+ * receives. Use it where a test only cares that sending succeeded.
+ */
+export declare const makeInMemoryQueueMessageProducer: Effect.Effect<QueueMessageProducerShape, never, never>;
+/**
+ * The in-memory producer, mounted.
+ */
+export declare const InMemoryQueueMessageProducerLive: Layer.Layer<QueueMessageProducer, never, never>;
+/**
+ * A producer that answers nothing: every send fails with
+ * `QueueMessageProducerUnavailableError`. Mount it to walk the branch a
+ * working stand-in never reaches.
+ */
+export declare const QueueMessageProducerUnavailableLive: Layer.Layer<QueueMessageProducer>;

package/dist/testing/queue-message-producer.js

@@ -0,0 +1,41 @@
+import { QueueMessageProducer, QueueMessageProducerUnavailableError, } from '@satorio/machinery/ports';
+import { Effect, Layer, Ref } from 'effect';
+import { messageOf } from './queue-message-source.js';
+const NOT_MOUNTED = 'queue unavailable (test)';
+/**
+ * An in-memory producer over the same reference an in-memory source reads.
+ *
+ * An in-memory producer over the same `Ref` an in-memory source reads, so a
+ * test sends on one side and receives on the other, the way a real queue pairs
+ * the two. Each send gets its own message id, counted from what is already on
+ * the queue.
+ */
+export const makeInMemoryQueueMessageProducerWith = (pending) => ({
+    send: (body) => Ref.update(pending, (current) => [
+        ...current,
+        messageOf(`message-${current.length + 1}`, body),
+    ]),
+});
+/**
+ * An in-memory producer over a `Ref` of its own, whose messages nobody
+ * receives. Use it where a test only cares that sending succeeded.
+ */
+export const makeInMemoryQueueMessageProducer = Effect.gen(function* () {
+    const pending = yield* Ref.make([]);
+    return makeInMemoryQueueMessageProducerWith(pending);
+});
+/**
+ * The in-memory producer, mounted.
+ */
+export const InMemoryQueueMessageProducerLive = Layer.effect(QueueMessageProducer, makeInMemoryQueueMessageProducer);
+/**
+ * A producer that answers nothing: every send fails with
+ * `QueueMessageProducerUnavailableError`. Mount it to walk the branch a
+ * working stand-in never reaches.
+ */
+export const QueueMessageProducerUnavailableLive = Layer.succeed(QueueMessageProducer, {
+    send: () => Effect.fail(new QueueMessageProducerUnavailableError({
+        operation: 'send',
+        cause: NOT_MOUNTED,
+    })),
+});

package/dist/testing/queue-message-source.d.ts

@@ -0,0 +1,54 @@
+import { QueueMessageSource, type QueueMessageSourceShape, type RawQueueMessage } from '@satorio/machinery/ports';
+import { Effect, Layer, Ref } from 'effect';
+/**
+ * What an in-memory queue holds: the messages waiting to be received, in
+ * the order they were put there. A scenario keeps the `Ref` and reads it
+ * to see what is still on the queue.
+ */
+export type PendingQueueMessages = readonly RawQueueMessage[];
+/**
+ * One raw message, built the way a queue hands it over: an id, the
+ * receipt an acknowledgement quotes, and the body.
+ */
+export declare const messageOf: (messageId: string, body: string) => RawQueueMessage;
+/**
+ * An in-memory message source over a `Ref` you keep, so a test seeds the
+ * queue before the run and reads what is left after it. `receive` hands
+ * back everything waiting; `acknowledge` takes one message off for good,
+ * as a real queue does when the receipt is deleted.
+ */
+export declare const makeInMemoryQueueMessageSourceWith: (pending: Ref.Ref<PendingQueueMessages>) => QueueMessageSourceShape;
+/**
+ * An in-memory message source over a `Ref` of its own, empty at the
+ * start.
+ */
+export declare const makeInMemoryQueueMessageSource: Effect.Effect<QueueMessageSourceShape, never, never>;
+/**
+ * The in-memory message source, mounted.
+ */
+export declare const InMemoryQueueMessageSourceLive: Layer.Layer<QueueMessageSource, never, never>;
+/**
+ * A message source that answers nothing: every operation fails with
+ * `QueueMessageSourceUnavailableError`. Mount it to walk the branch a
+ * working stand-in never reaches.
+ */
+export declare const QueueMessageSourceUnavailableLive: Layer.Layer<QueueMessageSource>;
+/**
+ * A queue source scripted ahead of time: the test writes what each
+ * `receive` call returns. Once the script runs out, it stays silent.
+ *
+ * @internal
+ */
+export interface ScriptedQueue {
+    readonly source: QueueMessageSourceShape;
+    readonly acknowledged: Effect.Effect<readonly string[]>;
+}
+/**
+ * Builds the scripted source and the reader for what it acknowledged.
+ */
+export declare const makeScriptedMessageSource: (script: readonly (readonly RawQueueMessage[])[]) => Effect.Effect<ScriptedQueue>;
+/**
+ * The scripted source, mounted: each `receive` answers with the next
+ * batch of the script.
+ */
+export declare const scriptedQueueMessageSourceLive: (script: readonly (readonly RawQueueMessage[])[]) => Layer.Layer<QueueMessageSource>;