@satorio/machinery 0.2.1

package/dist/vitest/testclock-fork-isolated-files.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The test files that need their own fresh module state, because they fork a
+ * fiber and move the clock.
+ *
+ * Files that fork a fiber and adjust TestClock (`Effect.fork` +
+ * `TestClock.adjust` + `Fiber.join`) and so need their own fresh module state
+ * (`isolate:true`) instead of the suite's shared worker. Guarded by
+ * `testclockForkIsolationGuard` (see `testclock-fork-isolation.ts`). Paths are
+ * relative to the package's own repository root. This file carries no `vitest`
+ * import on purpose: `vitest.config.ts` reads this list while building the
+ * test-runner config, before the `vitest` runtime exists.
+ */
+export declare const FILES_THAT_FORK_A_FIBER_AND_ADJUST_TEST_CLOCK: readonly string[];

package/dist/vitest/testclock-fork-isolated-files.js

@@ -0,0 +1,18 @@
+/**
+ * The test files that need their own fresh module state, because they fork a
+ * fiber and move the clock.
+ *
+ * Files that fork a fiber and adjust TestClock (`Effect.fork` +
+ * `TestClock.adjust` + `Fiber.join`) and so need their own fresh module state
+ * (`isolate:true`) instead of the suite's shared worker. Guarded by
+ * `testclockForkIsolationGuard` (see `testclock-fork-isolation.ts`). Paths are
+ * relative to the package's own repository root. This file carries no `vitest`
+ * import on purpose: `vitest.config.ts` reads this list while building the
+ * test-runner config, before the `vitest` runtime exists.
+ */
+export const FILES_THAT_FORK_A_FIBER_AND_ADJUST_TEST_CLOCK = [
+    'src/postgres/readiness-probe.test.ts',
+    'src/integration/external-http-client.test.ts',
+    'src/queue/readiness-deadline.test.ts',
+    'src/workflow/publish-pending-events.test.ts',
+];

package/dist/vitest/testclock-fork-isolation.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Held inside this mechanism. The guard's own violations test can prove the
+ * pattern `testclockForkIsolationGuard` scans
+ * for directly, instead of only ever observing a clean tree.
+ *
+ * @internal
+ */
+export declare const forksAFiberAndAdjustsTestClock: (source: string) => boolean;
+/**
+ * A module opens a real client when it imports one of the AWS SDK's
+ * clients. Held inside this mechanism so the guard's own violations test
+ * can feed a constructed module instead of only ever reading a clean tree.
+ *
+ * @internal
+ */
+export declare const opensARealClient: (source: string) => boolean;
+/**
+ * One name a test takes from a module that opens a real client, and the
+ * module it takes it from.
+ *
+ * @internal
+ */
+export interface TestclockImportFinding {
+    readonly name: string;
+    readonly specifier: string;
+}
+/**
+ * Every name a source takes from a module that opens a real client, minus
+ * the ones the caller excused. `opensAClientAt` answers for one import
+ * specifier, so the guard's own violations test can answer from a
+ * constructed map instead of the file system.
+ *
+ * @internal
+ */
+export declare const namesTakenFromAModuleThatOpensAClient: (source: string, opensAClientAt: (specifier: string) => boolean, excusedNames: ReadonlySet<string>) => readonly TestclockImportFinding[];
+/**
+ * One name a clock-driving test may keep importing from a module that
+ * opens a real client, and why that name opens nothing itself.
+ *
+ * @internal
+ */
+export interface TestclockImportException {
+    readonly name: string;
+    readonly why: string;
+}
+/**
+ * Options for `testclockForkIsolationGuard`. `directories` default to
+ * `['src']`, the package's own source root; a consumer names its own
+ * source directories. `exceptions` name the imports a clock-driving test
+ * may keep taking from a module that opens a real client — a type, a
+ * constant, an entry the caller hands its own stand-in to — each with the
+ * reason.
+ *
+ * @internal
+ */
+export interface TestclockForkIsolationOptions {
+    readonly root?: string;
+    readonly directories?: readonly string[];
+    readonly minimumFiles: number;
+    readonly exceptions?: readonly TestclockImportException[];
+}
+/**
+ * Registers a vitest suite that fails when a test moves the clock in a forked
+ * fiber outside its own list.
+ *
+ * Registers a vitest suite that fails if a `*.test.ts` file under the scanned
+ * directories forks a fiber and adjusts `TestClock` without being listed in
+ * `knownIsolatedFiles` — such a file needs `isolate:true` (see
+ * `vitest.config.ts`'s `testclock-fork-isolated` project), or it occasionally
+ * hits "testClock.adjust is not a function" under a shared worker. The same
+ * suite fails when one of those files imports a real client, straight from the
+ * AWS SDK or through a module that opens one: a real client can fail on its
+ * own, faster than the virtual clock moves, and then the test reports that
+ * failure instead of the deadline it was written for. Call it from a
+ * consumer's `*.test.ts` file with the consumer's own list.
+ */
+export declare const testclockForkIsolationGuard: (knownIsolatedFiles: readonly string[], options: TestclockForkIsolationOptions) => void;

package/dist/vitest/testclock-fork-isolation.js

@@ -0,0 +1,188 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { repoFilesUnder, repoRoot } from './repo-source-files.js';
+const AWS_CLIENT_PACKAGE = '@aws-sdk/client-';
+const IMPORT_CLAUSE = /import\s+([^'"]*?)\s*from\s*['"]([^'"]+)['"]/g;
+/**
+ * Held inside this mechanism. The guard's own violations test can prove the
+ * pattern `testclockForkIsolationGuard` scans
+ * for directly, instead of only ever observing a clean tree.
+ *
+ * @internal
+ */
+export const forksAFiberAndAdjustsTestClock = (source) => source.includes('TestClock.adjust') &&
+    (source.includes('Effect.fork') || source.includes('Fiber.join'));
+/**
+ * A module opens a real client when it imports one of the AWS SDK's
+ * clients. Held inside this mechanism so the guard's own violations test
+ * can feed a constructed module instead of only ever reading a clean tree.
+ *
+ * @internal
+ */
+export const opensARealClient = (source) => source.includes(AWS_CLIENT_PACKAGE);
+const namesInClause = (clause) => {
+    const withoutTypeKeyword = clause.replace(/^type\s+/, '');
+    const opening = withoutTypeKeyword.indexOf('{');
+    const outside = opening === -1 ? withoutTypeKeyword : withoutTypeKeyword.slice(0, opening);
+    const inside = opening === -1
+        ? ''
+        : withoutTypeKeyword.slice(opening + 1).replace(/\}[\s\S]*$/, '');
+    return [...outside.split(','), ...inside.split(',')]
+        .map((part) => part
+        .trim()
+        .replace(/^type\s+/, '')
+        .split(/\s+as\s+/)[0])
+        .map((name) => (name === undefined ? '' : name.trim()))
+        .filter((name) => name !== '' && name !== '*');
+};
+/**
+ * Every name a source takes from a module that opens a real client, minus
+ * the ones the caller excused. `opensAClientAt` answers for one import
+ * specifier, so the guard's own violations test can answer from a
+ * constructed map instead of the file system.
+ *
+ * @internal
+ */
+export const namesTakenFromAModuleThatOpensAClient = (source, opensAClientAt, excusedNames) => [...source.matchAll(IMPORT_CLAUSE)].flatMap((match) => {
+    const clause = match[1] ?? '';
+    const specifier = match[2] ?? '';
+    if (!opensAClientAt(specifier))
+        return [];
+    return namesInClause(clause)
+        .filter((name) => !excusedNames.has(name))
+        .map((name) => ({ name, specifier }));
+});
+const readOrNothing = (path) => {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+};
+const codeOf = (error) => typeof error === 'object' &&
+    error !== null &&
+    typeof error.code === 'string'
+    ? error.code
+    : 'an error with no code';
+const readSource = (path) => {
+    try {
+        return { kind: 'ok', text: readFileSync(path, 'utf8') };
+    }
+    catch (error) {
+        return {
+            kind: 'unreadable',
+            reason: `the read failed with ${codeOf(error)}`,
+        };
+    }
+};
+const opensAClientAtFrom = (root, file) => (specifier) => {
+    if (specifier.startsWith(AWS_CLIENT_PACKAGE))
+        return true;
+    if (!specifier.startsWith('.'))
+        return false;
+    const base = join(root, dirname(file), specifier);
+    const source = readOrNothing(`${base}.ts`) ?? readOrNothing(join(base, 'index.ts'));
+    return source !== undefined && opensARealClient(source);
+};
+/**
+ * Registers a vitest suite that fails when a test moves the clock in a forked
+ * fiber outside its own list.
+ *
+ * Registers a vitest suite that fails if a `*.test.ts` file under the scanned
+ * directories forks a fiber and adjusts `TestClock` without being listed in
+ * `knownIsolatedFiles` — such a file needs `isolate:true` (see
+ * `vitest.config.ts`'s `testclock-fork-isolated` project), or it occasionally
+ * hits "testClock.adjust is not a function" under a shared worker. The same
+ * suite fails when one of those files imports a real client, straight from the
+ * AWS SDK or through a module that opens one: a real client can fail on its
+ * own, faster than the virtual clock moves, and then the test reports that
+ * failure instead of the deadline it was written for. Call it from a
+ * consumer's `*.test.ts` file with the consumer's own list.
+ */
+export const testclockForkIsolationGuard = (knownIsolatedFiles, options) => {
+    const root = options.root ?? repoRoot();
+    const directories = options.directories ?? ['src'];
+    const known = new Set(knownIsolatedFiles);
+    const exceptions = options.exceptions ?? [];
+    const excusedNames = new Set(exceptions.map((exception) => exception.name));
+    const testFiles = repoFilesUnder(root, directories, '.ts').filter((file) => file.endsWith('.test.ts'));
+    const testFileSet = new Set(testFiles);
+    const reads = testFiles.map((file) => ({
+        file,
+        read: readSource(join(root, file)),
+    }));
+    const unreadableFiles = reads.flatMap((entry) => entry.read.kind === 'unreadable'
+        ? [{ file: entry.file, reason: entry.read.reason }]
+        : []);
+    const sourcesMatchingThePattern = reads
+        .flatMap((entry) => entry.read.kind === 'ok'
+        ? [{ file: entry.file, text: entry.read.text }]
+        : [])
+        .filter((entry) => forksAFiberAndAdjustsTestClock(entry.text));
+    const filesMatchingThePattern = sourcesMatchingThePattern.map((entry) => entry.file);
+    const matchingSet = new Set(filesMatchingThePattern);
+    const importsOfARealClient = sourcesMatchingThePattern.flatMap((entry) => namesTakenFromAModuleThatOpensAClient(entry.text, opensAClientAtFrom(root, entry.file), excusedNames).map((finding) => ({ file: entry.file, ...finding })));
+    const namesEveryExceptionCouldExcuse = new Set(sourcesMatchingThePattern.flatMap((entry) => namesTakenFromAModuleThatOpensAClient(entry.text, opensAClientAtFrom(root, entry.file), new Set()).map((finding) => finding.name)));
+    describe('testclock-fork-isolated list: a guard against a new flake', () => {
+        it('every test file with TestClock.adjust + fork/join is listed', () => {
+            const missingFromTheList = filesMatchingThePattern.filter((file) => !known.has(file));
+            expect(missingFromTheList, missingFromTheList
+                .map((file) => `${file} forks a fiber and adjusts TestClock, but is not in ` +
+                `the known-isolated list passed to testclockForkIsolationGuard. ` +
+                `Add a line there — otherwise this file, under the shared ` +
+                `worker, occasionally hits "testClock.adjust is not a ` +
+                `function".`)
+                .join('\n')).toEqual([]);
+        });
+        it('no listed file is stale', () => {
+            const staleEntries = knownIsolatedFiles.filter((file) => !testFileSet.has(file) || !matchingSet.has(file));
+            expect(staleEntries, staleEntries
+                .map((file) => testFileSet.has(file)
+                ? `${file} is listed in testclockForkIsolationGuard's ` +
+                    `known-isolated list, but no longer forks a fiber and ` +
+                    'adjusts TestClock — STALE, prune the baseline.'
+                : `${file} is listed in testclockForkIsolationGuard's ` +
+                    `known-isolated list, but no test file exists there ` +
+                    'any more — STALE, prune the baseline.')
+                .join('\n')).toEqual([]);
+        });
+        it('no file that adjusts the clock imports a real client', () => {
+            expect(importsOfARealClient, importsOfARealClient
+                .map((finding) => `${finding.file} imports ${finding.name} from ` +
+                `${finding.specifier}, which opens a real client. A real ` +
+                `client can fail on its own — a missing region, a refused ` +
+                `connection — faster than the virtual clock moves, and then ` +
+                `this test reports that failure instead of the deadline it ` +
+                `was written for. Hand the code under test a stand-in, or ` +
+                `name ${finding.name} in the guard's exceptions with the ` +
+                `reason it opens nothing.`)
+                .join('\n')).toEqual([]);
+        });
+        it('every exception carries a reason and still matches an import', () => {
+            const badExceptions = exceptions.filter((exception) => exception.why.trim() === '' ||
+                !namesEveryExceptionCouldExcuse.has(exception.name));
+            expect(badExceptions, badExceptions
+                .map((exception) => exception.why.trim() === ''
+                ? `${exception.name} is excused with no reason. Say why the ` +
+                    'name opens nothing, or drop the exception.'
+                : `${exception.name} is excused, but no file that adjusts ` +
+                    'the clock imports it from a module that opens a real ' +
+                    'client any more — STALE, prune the exception.')
+                .join('\n')).toEqual([]);
+        });
+        it('every file the walk listed could be read', () => {
+            expect(unreadableFiles.map((entry) => entry.file), unreadableFiles
+                .map((entry) => `${entry.file} is on the walk's list, and this guard cannot ` +
+                `read it: ${entry.reason}. A file the guard passes over in ` +
+                'silence is a file nothing holds — delete the path, or repair ' +
+                'it.')
+                .join('\n')).toEqual([]);
+        });
+        it('read at least minimumFiles test files', () => {
+            console.log(`testclock fork isolation: read ${testFiles.length} test files`);
+            expect(testFiles.length).toBeGreaterThanOrEqual(options.minimumFiles);
+        });
+    });
+};

package/dist/workflow/claim-once.d.ts

@@ -0,0 +1,16 @@
+import { type ProcessedEventClaim, ProcessedEventRegistry, type ProcessedEventRegistryUnavailableError } from '@satorio/machinery/ports';
+import { DateTime, Effect } from 'effect';
+/**
+ * The exactly-once claim: shared ground for every use case that takes an
+ * event or command once. The use case itself builds the idempotency key
+ * (an event id, a command id, "payment:<id>") — only it knows what counts
+ * as "the same" for its own case. This type carries the claim, nothing more.
+ */
+export type ClaimOnce = Effect.Effect<ProcessedEventClaim, ProcessedEventRegistryUnavailableError, ProcessedEventRegistry>;
+/**
+ * Claims with a processedAt supplied by the caller, for a handler that has
+ * already read the clock and must store that exact moment.
+ */
+export declare const claimAsProcessedAt: (idempotencyKey: string, processedAt: DateTime.Utc) => ClaimOnce;
+/** Claims with the current time, for a caller that only needs the claim. */
+export declare const claimAsProcessedNow: (idempotencyKey: string) => ClaimOnce;

package/dist/workflow/claim-once.js

@@ -0,0 +1,9 @@
+import { ProcessedEventRegistry, } from '@satorio/machinery/ports';
+import { DateTime, Effect } from 'effect';
+/**
+ * Claims with a processedAt supplied by the caller, for a handler that has
+ * already read the clock and must store that exact moment.
+ */
+export const claimAsProcessedAt = (idempotencyKey, processedAt) => Effect.flatMap(ProcessedEventRegistry, (registry) => registry.claim({ eventId: idempotencyKey, processedAt }));
+/** Claims with the current time, for a caller that only needs the claim. */
+export const claimAsProcessedNow = (idempotencyKey) => Effect.flatMap(DateTime.now, (processedAt) => claimAsProcessedAt(idempotencyKey, processedAt));

package/dist/workflow/failures.d.ts

@@ -0,0 +1,47 @@
+declare const SchemaVersionFromTheFutureError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SchemaVersionFromTheFutureError";
+} & Readonly<A>;
+/**
+ * The stored payload says it was written by a newer version of this code
+ * than the one reading it. There is no upcast step downwards, so the
+ * reader stops rather than guessing which fields it does not know about.
+ */
+export declare class SchemaVersionFromTheFutureError extends SchemaVersionFromTheFutureError_base<{
+    readonly eventType: string;
+    readonly storedVersion: number;
+    readonly currentVersion: number;
+}> {
+}
+declare const MissingUpcastStepError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "MissingUpcastStepError";
+} & Readonly<A>;
+/**
+ * One version between the stored payload and the current one has no
+ * upcast step, so the lift cannot finish. The payload stays where it is
+ * rather than arriving half-lifted.
+ */
+export declare class MissingUpcastStepError extends MissingUpcastStepError_base<{
+    readonly eventType: string;
+    readonly fromVersion: number;
+    readonly currentVersion: number;
+}> {
+}
+declare const UpcastStepFailedError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "UpcastStepFailedError";
+} & Readonly<A>;
+/**
+ * An upcast step threw while lifting the payload one version up. The
+ * throw becomes a typed failure here, so a caller reads it in the error
+ * channel rather than meeting an exception.
+ */
+export declare class UpcastStepFailedError extends UpcastStepFailedError_base<{
+    readonly eventType: string;
+    readonly fromVersion: number;
+    readonly cause: unknown;
+}> {
+}
+/**
+ * Every way reading a stored payload can refuse.
+ */
+export type VersionedPayloadFailure = SchemaVersionFromTheFutureError | MissingUpcastStepError | UpcastStepFailedError;
+export {};

package/dist/workflow/failures.js

@@ -0,0 +1,22 @@
+import { Data } from 'effect';
+/**
+ * The stored payload says it was written by a newer version of this code
+ * than the one reading it. There is no upcast step downwards, so the
+ * reader stops rather than guessing which fields it does not know about.
+ */
+export class SchemaVersionFromTheFutureError extends Data.TaggedError('SchemaVersionFromTheFutureError') {
+}
+/**
+ * One version between the stored payload and the current one has no
+ * upcast step, so the lift cannot finish. The payload stays where it is
+ * rather than arriving half-lifted.
+ */
+export class MissingUpcastStepError extends Data.TaggedError('MissingUpcastStepError') {
+}
+/**
+ * An upcast step threw while lifting the payload one version up. The
+ * throw becomes a typed failure here, so a caller reads it in the error
+ * channel rather than meeting an exception.
+ */
+export class UpcastStepFailedError extends Data.TaggedError('UpcastStepFailedError') {
+}

package/dist/workflow/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Public entry to the workflow mechanism: the combinators a use case composes
+ * its own beat from. It gives you the combinators a use case composes its own
+ * beat from — a transaction boundary, the exactly-once claim, versioned
+ * payloads, and the outbox relay.
+ */
+export { type ClaimOnce, claimAsProcessedAt, claimAsProcessedNow, } from './claim-once.js';
+export { MissingUpcastStepError, SchemaVersionFromTheFutureError, UpcastStepFailedError, type VersionedPayloadFailure, } from './failures.js';
+export { type OnClaimMatchers, onClaim, } from './on-claim.js';
+export { DEFAULT_PUBLISH_PENDING_EVENTS_SETTINGS, keepPublishingPendingEvents, type PublishPendingEventsFailure, type PublishPendingEventsSettings, publishOneBatch, } from './publish-pending-events.js';
+export { transactionally } from './transactionally.js';
+export { decodeStoredPayload, type UpcastStep, upcastToCurrentVersion, type VersionedEventDefinition, } from './versioned-payload.js';

package/dist/workflow/index.js

@@ -0,0 +1,12 @@
+/**
+ * Public entry to the workflow mechanism: the combinators a use case composes
+ * its own beat from. It gives you the combinators a use case composes its own
+ * beat from — a transaction boundary, the exactly-once claim, versioned
+ * payloads, and the outbox relay.
+ */
+export { claimAsProcessedAt, claimAsProcessedNow, } from './claim-once.js';
+export { MissingUpcastStepError, SchemaVersionFromTheFutureError, UpcastStepFailedError, } from './failures.js';
+export { onClaim, } from './on-claim.js';
+export { DEFAULT_PUBLISH_PENDING_EVENTS_SETTINGS, keepPublishingPendingEvents, publishOneBatch, } from './publish-pending-events.js';
+export { transactionally } from './transactionally.js';
+export { decodeStoredPayload, upcastToCurrentVersion, } from './versioned-payload.js';

package/dist/workflow/on-claim.d.ts

@@ -0,0 +1,17 @@
+import type { ProcessedEventClaim } from '@satorio/machinery/ports';
+import { type DateTime, Effect } from 'effect';
+/**
+ * The two branches `onClaim` takes: what to do when the event was already
+ * claimed, and what to do when this run claims it.
+ */
+export interface OnClaimMatchers<A1, E1, R1, A2, E2, R2> {
+    readonly alreadyProcessed: (processedAt: DateTime.Utc) => Effect.Effect<A1, E1, R1>;
+    readonly accepted: () => Effect.Effect<A2, E2, R2>;
+}
+/**
+ * Branches on the state of the exactly-once claim: AlreadyProcessed goes one
+ * way, ClaimAccepted the other. The claim is shared by every use case that
+ * takes an event once, so this combinator lives in the machinery, not in a
+ * service.
+ */
+export declare const onClaim: <A1, E1, R1, A2, E2, R2, EClaim, RClaim>(claim: Effect.Effect<ProcessedEventClaim, EClaim, RClaim>, matchers: OnClaimMatchers<A1, E1, R1, A2, E2, R2>) => Effect.Effect<A1 | A2, EClaim | E1 | E2, RClaim | R1 | R2>;

package/dist/workflow/on-claim.js

@@ -0,0 +1,8 @@
+import { Effect, Match } from 'effect';
+/**
+ * Branches on the state of the exactly-once claim: AlreadyProcessed goes one
+ * way, ClaimAccepted the other. The claim is shared by every use case that
+ * takes an event once, so this combinator lives in the machinery, not in a
+ * service.
+ */
+export const onClaim = (claim, matchers) => Effect.flatMap(claim, Match.type().pipe(Match.tag('AlreadyProcessed', ({ processedAt }) => matchers.alreadyProcessed(processedAt)), Match.tag('ClaimAccepted', () => matchers.accepted()), Match.exhaustive));

package/dist/workflow/publish-pending-events.d.ts

@@ -0,0 +1,31 @@
+import { EventPublisher, type EventPublisherUnavailableError, IntegrationEventOutbox, type IntegrationEventOutboxUnavailableError } from '@satorio/machinery/ports';
+import { Duration, Effect } from 'effect';
+/**
+ * What one beat of the relay can meet: the outbox did not answer, or the
+ * publisher did not.
+ */
+export type PublishPendingEventsFailure = IntegrationEventOutboxUnavailableError | EventPublisherUnavailableError;
+/**
+ * How the relay paces itself: how many messages one beat takes, and how long
+ * it waits between beats.
+ */
+export interface PublishPendingEventsSettings {
+    readonly batchLimit: number;
+    readonly pollInterval: Duration.Duration;
+}
+/**
+ * The pace the relay keeps when a service names none of its own.
+ */
+export declare const DEFAULT_PUBLISH_PENDING_EVENTS_SETTINGS: PublishPendingEventsSettings;
+/**
+ * One outbox relay beat: take a batch of undelivered messages, hand it to
+ * the publisher, then mark it dispatched. The order matters — marking comes
+ * after a successful hand-off, so a failure leaves the message in the
+ * outbox instead of losing it.
+ */
+export declare const publishOneBatch: (batchLimit: number) => Effect.Effect<number, PublishPendingEventsFailure, IntegrationEventOutbox | EventPublisher>;
+/**
+ * Runs the outbox relay for as long as the service lives. A beat that fails is
+ * logged, and its messages stay in the outbox for the next one.
+ */
+export declare const keepPublishingPendingEvents: (settings?: PublishPendingEventsSettings) => Effect.Effect<never, never, IntegrationEventOutbox | EventPublisher>;

package/dist/workflow/publish-pending-events.js

@@ -0,0 +1,31 @@
+import { EventPublisher, IntegrationEventOutbox, } from '@satorio/machinery/ports';
+import { Duration, Effect, Schedule } from 'effect';
+/**
+ * The pace the relay keeps when a service names none of its own.
+ */
+export const DEFAULT_PUBLISH_PENDING_EVENTS_SETTINGS = {
+    batchLimit: 50,
+    pollInterval: Duration.seconds(5),
+};
+/**
+ * One outbox relay beat: take a batch of undelivered messages, hand it to
+ * the publisher, then mark it dispatched. The order matters — marking comes
+ * after a successful hand-off, so a failure leaves the message in the
+ * outbox instead of losing it.
+ */
+export const publishOneBatch = (batchLimit) => Effect.gen(function* () {
+    const outbox = yield* IntegrationEventOutbox;
+    const publisher = yield* EventPublisher;
+    const batch = yield* outbox.pending(batchLimit);
+    if (batch.length === 0)
+        return 0;
+    yield* publisher.publish(batch);
+    yield* outbox.markDispatched(batch.map((message) => message.messageId));
+    return batch.length;
+});
+const oneBatchSwallowingFailuresLoudly = (batchLimit) => publishOneBatch(batchLimit).pipe(Effect.asVoid, Effect.catchAll((failure) => Effect.logError('Event publishing: this beat failed, messages stay in the outbox until the next beat', { failure: failure._tag, operation: failure.operation })));
+/**
+ * Runs the outbox relay for as long as the service lives. A beat that fails is
+ * logged, and its messages stay in the outbox for the next one.
+ */
+export const keepPublishingPendingEvents = (settings = DEFAULT_PUBLISH_PENDING_EVENTS_SETTINGS) => oneBatchSwallowingFailuresLoudly(settings.batchLimit).pipe(Effect.repeat(Schedule.spaced(settings.pollInterval)), Effect.andThen(Effect.never));

package/dist/workflow/transactionally.d.ts

@@ -0,0 +1,8 @@
+import { TransactionBoundary } from '@satorio/machinery/ports';
+import { Effect } from 'effect';
+/**
+ * Wraps work in a transaction boundary: pulls TransactionBoundary from
+ * context and runs the work through it. A reusable combinator for use cases
+ * that must write within one transaction.
+ */
+export declare const transactionally: <A, E, R>(work: Effect.Effect<A, E, R>) => Effect.Effect<A, import("@satorio/machinery/ports").TransactionBoundaryUnavailableError | E, TransactionBoundary | R>;

package/dist/workflow/transactionally.js

@@ -0,0 +1,8 @@
+import { TransactionBoundary } from '@satorio/machinery/ports';
+import { Effect } from 'effect';
+/**
+ * Wraps work in a transaction boundary: pulls TransactionBoundary from
+ * context and runs the work through it. A reusable combinator for use cases
+ * that must write within one transaction.
+ */
+export const transactionally = (work) => Effect.flatMap(TransactionBoundary, (tx) => tx.inTransaction(work));

package/dist/workflow/versioned-payload.d.ts

@@ -0,0 +1,35 @@
+import { Effect, type ParseResult, Schema } from 'effect';
+import { type VersionedPayloadFailure } from './failures.js';
+/**
+ * One lift, from the version it names to the next one up.
+ */
+export interface UpcastStep {
+    readonly fromVersion: number;
+    readonly lift: (payload: unknown) => unknown;
+}
+/**
+ * An event stored yesterday is read by today's code. Between the two sit
+ * upcast steps: each lifts the payload one version up, and only after
+ * they run does the current schema's decoder take over. A definition
+ * carries the event's name, the version the code writes today, the
+ * schema that version decodes with, and the steps between.
+ */
+export interface VersionedEventDefinition<S extends Schema.Schema.AnyNoContext> {
+    readonly eventType: string;
+    readonly currentSchemaVersion: number;
+    readonly schema: S;
+    readonly upcastSteps: readonly UpcastStep[];
+}
+/**
+ * Lifts a stored payload from the version it was written at to the
+ * version this code reads, one step per version, in order.
+ */
+export declare const upcastToCurrentVersion: <S extends Schema.Schema.AnyNoContext>(definition: VersionedEventDefinition<S>, storedVersion: number, payload: unknown) => Effect.Effect<unknown, VersionedPayloadFailure>;
+/**
+ * Lifts a stored payload to the current version and decodes it with the
+ * current schema.
+ *
+ * Lifts a stored payload to the current version and then decodes it with the
+ * current schema, so a caller reads today's type or one named failure.
+ */
+export declare const decodeStoredPayload: <S extends Schema.Schema.AnyNoContext>(definition: VersionedEventDefinition<S>, storedVersion: number, payload: unknown) => Effect.Effect<Schema.Schema.Type<S>, VersionedPayloadFailure | ParseResult.ParseError>;

package/dist/workflow/versioned-payload.js

@@ -0,0 +1,43 @@
+import { Effect, Schema } from 'effect';
+import { MissingUpcastStepError, SchemaVersionFromTheFutureError, UpcastStepFailedError, } from './failures.js';
+/**
+ * Lifts a stored payload from the version it was written at to the
+ * version this code reads, one step per version, in order.
+ */
+export const upcastToCurrentVersion = (definition, storedVersion, payload) => Effect.gen(function* () {
+    if (storedVersion > definition.currentSchemaVersion) {
+        return yield* new SchemaVersionFromTheFutureError({
+            eventType: definition.eventType,
+            storedVersion,
+            currentVersion: definition.currentSchemaVersion,
+        });
+    }
+    let lifted = payload;
+    for (let version = storedVersion; version < definition.currentSchemaVersion; version = version + 1) {
+        const step = definition.upcastSteps.find((candidate) => candidate.fromVersion === version);
+        if (step === undefined) {
+            return yield* new MissingUpcastStepError({
+                eventType: definition.eventType,
+                fromVersion: version,
+                currentVersion: definition.currentSchemaVersion,
+            });
+        }
+        lifted = yield* Effect.try({
+            try: () => step.lift(lifted),
+            catch: (cause) => new UpcastStepFailedError({
+                eventType: definition.eventType,
+                fromVersion: step.fromVersion,
+                cause,
+            }),
+        });
+    }
+    return lifted;
+});
+/**
+ * Lifts a stored payload to the current version and decodes it with the
+ * current schema.
+ *
+ * Lifts a stored payload to the current version and then decodes it with the
+ * current schema, so a caller reads today's type or one named failure.
+ */
+export const decodeStoredPayload = (definition, storedVersion, payload) => upcastToCurrentVersion(definition, storedVersion, payload).pipe(Effect.flatMap((lifted) => Schema.decodeUnknown(definition.schema)(lifted)));