@satorio/machinery 0.2.1

package/dist/money/percent.d.ts

@@ -0,0 +1,35 @@
+import { Either } from 'effect';
+import { NotAPercentError } from './failures.js';
+/**
+ * A share of an amount, held exactly. Thirty percent is the ratio three
+ * tenths, and this value carries it as a whole number of units and the
+ * count of decimals those units are counted in. Two sources write the
+ * same share in two forms — a price list writes `30`, a table of rates
+ * writes `0.3` — so each form has its own reader and its own writer, and
+ * nothing in between guesses which one arrived.
+ */
+export interface Percent {
+    readonly amount: bigint;
+    readonly scale: bigint;
+}
+/**
+ * Reads the form a price list writes: `30` means thirty percent.
+ */
+export declare const percentFromPercentageForm: (text: string) => Either.Either<Percent, NotAPercentError>;
+/**
+ * Reads the form a table of rates writes: `0.3` means thirty percent.
+ */
+export declare const percentFromRatioForm: (text: string) => Either.Either<Percent, NotAPercentError>;
+/**
+ * Writes the percentage form back, trimmed: thirty percent reads `30`.
+ */
+export declare const percentInPercentageForm: (percent: Percent) => string;
+/**
+ * Writes the ratio form back, trimmed: thirty percent reads `0.3`.
+ */
+export declare const percentInRatioForm: (percent: Percent) => string;
+/**
+ * Whether two shares are the same share, whichever form each was read
+ * from. `30` and `0.30` are one share, and this says so.
+ */
+export declare const samePercent: (left: Percent, right: Percent) => boolean;

package/dist/money/percent.js

@@ -0,0 +1,50 @@
+import { Either } from 'effect';
+import { exactDecimalOf, trimmedDecimalOf } from './decimal.js';
+import { NotAPercentError } from './failures.js';
+const PERCENTAGE_TO_RATIO = 2n;
+/**
+ * Reads the form a price list writes: `30` means thirty percent.
+ */
+export const percentFromPercentageForm = (text) => {
+    const read = exactDecimalOf(text);
+    return read === null
+        ? Either.left(new NotAPercentError({ text, form: 'percentage' }))
+        : Either.right({
+            amount: read.units,
+            scale: read.scale + PERCENTAGE_TO_RATIO,
+        });
+};
+/**
+ * Reads the form a table of rates writes: `0.3` means thirty percent.
+ */
+export const percentFromRatioForm = (text) => {
+    const read = exactDecimalOf(text);
+    return read === null
+        ? Either.left(new NotAPercentError({ text, form: 'ratio' }))
+        : Either.right({ amount: read.units, scale: read.scale });
+};
+const liftedTo = (percent, scale) => percent.scale >= scale
+    ? percent
+    : { amount: percent.amount * 10n ** (scale - percent.scale), scale };
+/**
+ * Writes the percentage form back, trimmed: thirty percent reads `30`.
+ */
+export const percentInPercentageForm = (percent) => {
+    const lifted = liftedTo(percent, PERCENTAGE_TO_RATIO);
+    return trimmedDecimalOf({
+        units: lifted.amount,
+        scale: lifted.scale - PERCENTAGE_TO_RATIO,
+    });
+};
+/**
+ * Writes the ratio form back, trimmed: thirty percent reads `0.3`.
+ */
+export const percentInRatioForm = (percent) => trimmedDecimalOf({ units: percent.amount, scale: percent.scale });
+/**
+ * Whether two shares are the same share, whichever form each was read
+ * from. `30` and `0.30` are one share, and this says so.
+ */
+export const samePercent = (left, right) => {
+    const finest = left.scale > right.scale ? left.scale : right.scale;
+    return liftedTo(left, finest).amount === liftedTo(right, finest).amount;
+};

package/dist/money/schema.d.ts

@@ -0,0 +1,25 @@
+import { Schema } from 'effect';
+import { type Money } from './amount.js';
+import type { Currency } from './currency.js';
+import { type Percent } from './percent.js';
+/**
+ * Reads and writes an amount on the wire as decimal text, in the currency you
+ * name.
+ *
+ * Reads an amount off the wire as the decimal text a sender wrote, in the
+ * currency you name, and writes it back in that same form. A text this schema
+ * refuses carries the whole three-part refusal into the parse error, so
+ * whoever sent a bad command reads a sentence about their own amount rather
+ * than a bare type name.
+ */
+export declare const MoneyFromDecimalString: (currency: Currency) => Schema.Schema<Money, string>;
+/**
+ * Reads a share off the wire in the form a price list writes: `30` means
+ * thirty percent. It writes that same form back.
+ */
+export declare const PercentFromPercentageString: Schema.Schema<Percent, string>;
+/**
+ * Reads a share off the wire in the form a table of rates writes: `0.3`
+ * means thirty percent. It writes that same form back.
+ */
+export declare const PercentFromRatioString: Schema.Schema<Percent, string>;

package/dist/money/schema.js

@@ -0,0 +1,41 @@
+import { refusalText } from '@satorio/machinery/core';
+import { Either, ParseResult, Schema } from 'effect';
+import { moneyFromDecimalForm, moneyInDecimalForm } from './amount.js';
+import { percentFromPercentageForm, percentFromRatioForm, percentInPercentageForm, percentInRatioForm, } from './percent.js';
+const MoneyValue = Schema.declare((value) => typeof value === 'object' && value !== null && 'calculator' in value, { identifier: 'Money' });
+const PercentValue = Schema.declare((value) => typeof value === 'object' &&
+    value !== null &&
+    typeof value.amount === 'bigint', { identifier: 'Percent' });
+/**
+ * Reads and writes an amount on the wire as decimal text, in the currency you
+ * name.
+ *
+ * Reads an amount off the wire as the decimal text a sender wrote, in the
+ * currency you name, and writes it back in that same form. A text this schema
+ * refuses carries the whole three-part refusal into the parse error, so
+ * whoever sent a bad command reads a sentence about their own amount rather
+ * than a bare type name.
+ */
+export const MoneyFromDecimalString = (currency) => Schema.transformOrFail(Schema.String, MoneyValue, {
+    strict: true,
+    decode: (text, _options, ast) => Either.mapLeft(moneyFromDecimalForm(currency, text), (failure) => new ParseResult.Type(ast, text, refusalText(failure.refusal))),
+    encode: (amount) => ParseResult.succeed(moneyInDecimalForm(amount)),
+});
+/**
+ * Reads a share off the wire in the form a price list writes: `30` means
+ * thirty percent. It writes that same form back.
+ */
+export const PercentFromPercentageString = Schema.transformOrFail(Schema.String, PercentValue, {
+    strict: true,
+    decode: (text, _options, ast) => Either.mapLeft(percentFromPercentageForm(text), (failure) => new ParseResult.Type(ast, text, refusalText(failure.refusal))),
+    encode: (percent) => ParseResult.succeed(percentInPercentageForm(percent)),
+});
+/**
+ * Reads a share off the wire in the form a table of rates writes: `0.3`
+ * means thirty percent. It writes that same form back.
+ */
+export const PercentFromRatioString = Schema.transformOrFail(Schema.String, PercentValue, {
+    strict: true,
+    decode: (text, _options, ast) => Either.mapLeft(percentFromRatioForm(text), (failure) => new ParseResult.Type(ast, text, refusalText(failure.refusal))),
+    encode: (percent) => ParseResult.succeed(percentInRatioForm(percent)),
+});

package/dist/ports/blob-store.d.ts

@@ -0,0 +1,42 @@
+import { Context, type Effect, type Option } from 'effect';
+declare const BlobStoreUnavailableError_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: "BlobStoreUnavailableError";
+} & Readonly<A>;
+/**
+ * The object store did not answer; a key that is not there at all is never
+ * this failure.
+ */
+export declare class BlobStoreUnavailableError extends BlobStoreUnavailableError_base<{
+    readonly operation: string;
+    readonly cause: unknown;
+}> {
+}
+/**
+ * A stored blob's bytes, content type, and free-form text metadata. The key
+ * lives outside this shape, as a separate argument to each operation — a
+ * blob does not know its own key.
+ */
+export interface StoredBlob {
+    readonly body: Uint8Array;
+    readonly contentType: string;
+    readonly metadata: Readonly<Record<string, string>>;
+}
+/**
+ * The blob store's operations. A missing key is not a failure: `get`
+ * returns `Option.none` and `exists` returns `false`.
+ * `BlobStoreUnavailableError` means only one thing: the store did not answer.
+ */
+export interface BlobStoreShape {
+    readonly put: (key: string, blob: StoredBlob) => Effect.Effect<void, BlobStoreUnavailableError>;
+    readonly get: (key: string) => Effect.Effect<Option.Option<StoredBlob>, BlobStoreUnavailableError>;
+    readonly exists: (key: string) => Effect.Effect<boolean, BlobStoreUnavailableError>;
+    readonly delete: (key: string) => Effect.Effect<void, BlobStoreUnavailableError>;
+}
+declare const BlobStore_base: Context.TagClass<BlobStore, "BlobStore", BlobStoreShape>;
+/**
+ * The port a use case asks for when it stores whole objects under a key and
+ * reads them back.
+ */
+export declare class BlobStore extends BlobStore_base {
+}
+export {};

package/dist/ports/blob-store.js

@@ -0,0 +1,13 @@
+import { Context, Data } from 'effect';
+/**
+ * The object store did not answer; a key that is not there at all is never
+ * this failure.
+ */
+export class BlobStoreUnavailableError extends Data.TaggedError('BlobStoreUnavailableError') {
+}
+/**
+ * The port a use case asks for when it stores whole objects under a key and
+ * reads them back.
+ */
+export class BlobStore extends Context.Tag('BlobStore')() {
+}

package/dist/ports/document-number-counter.d.ts

@@ -0,0 +1,36 @@
+import { Context, type Effect } from 'effect';
+declare const DocumentNumberCounterUnavailableError_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: "DocumentNumberCounterUnavailableError";
+} & Readonly<A>;
+/**
+ * The counter behind a document number did not answer; `operation` names the
+ * call and `cause` carries the driver's own error.
+ */
+export declare class DocumentNumberCounterUnavailableError extends DocumentNumberCounterUnavailableError_base<{
+    readonly operation: string;
+    readonly cause: unknown;
+}> {
+}
+/**
+ * Which counter to move on: one client, one reporting month. Every series
+ * of documents a client is sent in that month shares this counter, so two
+ * documents never carry the same digits.
+ */
+export interface DocumentNumberCountInput {
+    readonly clientCode: string;
+    readonly reportingMonth: string;
+}
+/**
+ * What the counter offers: one call that moves a client's month on and hands
+ * back the count the next document takes.
+ */
+export interface DocumentNumberCounterShape {
+    readonly nextCount: (input: DocumentNumberCountInput) => Effect.Effect<number, DocumentNumberCounterUnavailableError>;
+}
+declare const DocumentNumberCounter_base: Context.TagClass<DocumentNumberCounter, "DocumentNumberCounter", DocumentNumberCounterShape>;
+/**
+ * The port a use case asks for when it numbers a document a person will read.
+ */
+export declare class DocumentNumberCounter extends DocumentNumberCounter_base {
+}
+export {};

package/dist/ports/document-number-counter.js

@@ -0,0 +1,12 @@
+import { Context, Data } from 'effect';
+/**
+ * The counter behind a document number did not answer; `operation` names the
+ * call and `cause` carries the driver's own error.
+ */
+export class DocumentNumberCounterUnavailableError extends Data.TaggedError('DocumentNumberCounterUnavailableError') {
+}
+/**
+ * The port a use case asks for when it numbers a document a person will read.
+ */
+export class DocumentNumberCounter extends Context.Tag('DocumentNumberCounter')() {
+}

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

@@ -0,0 +1,29 @@
+import { Context, type Effect } from 'effect';
+import type { OutboxMessage } from './integration-event-outbox.js';
+declare const EventPublisherUnavailableError_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: "EventPublisherUnavailableError";
+} & Readonly<A>;
+/**
+ * The publisher did not answer, or no topic is configured; `cause` says which
+ * of the two it was.
+ */
+export declare class EventPublisherUnavailableError extends EventPublisherUnavailableError_base<{
+    readonly operation: string;
+    readonly cause: unknown;
+}> {
+}
+/**
+ * What a publisher offers: one call that sends a batch of outbox messages out
+ * of this service.
+ */
+export interface EventPublisherShape {
+    readonly publish: (messages: readonly OutboxMessage[]) => Effect.Effect<void, EventPublisherUnavailableError>;
+}
+declare const EventPublisher_base: Context.TagClass<EventPublisher, "EventPublisher", EventPublisherShape>;
+/**
+ * The port the outbox relay asks for when it announces what has already
+ * happened.
+ */
+export declare class EventPublisher extends EventPublisher_base {
+}
+export {};

package/dist/ports/event-publisher.js

@@ -0,0 +1,13 @@
+import { Context, Data } from 'effect';
+/**
+ * The publisher did not answer, or no topic is configured; `cause` says which
+ * of the two it was.
+ */
+export class EventPublisherUnavailableError extends Data.TaggedError('EventPublisherUnavailableError') {
+}
+/**
+ * The port the outbox relay asks for when it announces what has already
+ * happened.
+ */
+export class EventPublisher extends Context.Tag('EventPublisher')() {
+}

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

@@ -0,0 +1,60 @@
+import { Context, type Effect, type Schema } from 'effect';
+declare const ExternalServiceUnavailableError_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: "ExternalServiceUnavailableError";
+} & Readonly<A>;
+/**
+ * A network failure, a timeout, or a server error after the retries ran out;
+ * the same request may well succeed later.
+ */
+export declare class ExternalServiceUnavailableError extends ExternalServiceUnavailableError_base<{
+    readonly service: string;
+    readonly operation: string;
+    readonly cause: unknown;
+}> {
+}
+declare const ExternalServiceRefusedError_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: "ExternalServiceRefusedError";
+} & Readonly<A>;
+/**
+ * The external service answered with a refusal of its own, so the same request
+ * will fail again until the request changes.
+ */
+export declare class ExternalServiceRefusedError extends ExternalServiceRefusedError_base<{
+    readonly service: string;
+    readonly operation: string;
+    readonly status: number;
+}> {
+}
+declare const ExternalServiceResponseMalformedError_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: "ExternalServiceResponseMalformedError";
+} & Readonly<A>;
+/**
+ * The external service answered, but the body did not fit the schema the
+ * caller handed in.
+ */
+export declare class ExternalServiceResponseMalformedError extends ExternalServiceResponseMalformedError_base<{
+    readonly service: string;
+    readonly operation: string;
+    readonly cause: unknown;
+}> {
+}
+/**
+ * One external HTTP service, read through one operation. `getJson` asks
+ * for a path under the service's own address and decodes the answer
+ * through the schema you hand it, so a caller reads a value of its own
+ * type or one of exactly three failures: the service did not answer
+ * (`ExternalServiceUnavailableError`), the service said a specific no
+ * (`ExternalServiceRefusedError`), or the body did not fit the schema
+ * (`ExternalServiceResponseMalformedError`).
+ */
+export interface ExternalHttpClientShape {
+    readonly getJson: <A, I>(path: string, schema: Schema.Schema<A, I>) => Effect.Effect<A, ExternalServiceUnavailableError | ExternalServiceRefusedError | ExternalServiceResponseMalformedError>;
+}
+declare const ExternalHttpClient_base: Context.TagClass<ExternalHttpClient, "ExternalHttpClient", ExternalHttpClientShape>;
+/**
+ * The port a use case asks for when it reads reference data from a service
+ * outside this one.
+ */
+export declare class ExternalHttpClient extends ExternalHttpClient_base {
+}
+export {};

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

@@ -0,0 +1,25 @@
+import { Context, Data } from 'effect';
+/**
+ * A network failure, a timeout, or a server error after the retries ran out;
+ * the same request may well succeed later.
+ */
+export class ExternalServiceUnavailableError extends Data.TaggedError('ExternalServiceUnavailableError') {
+}
+/**
+ * The external service answered with a refusal of its own, so the same request
+ * will fail again until the request changes.
+ */
+export class ExternalServiceRefusedError extends Data.TaggedError('ExternalServiceRefusedError') {
+}
+/**
+ * The external service answered, but the body did not fit the schema the
+ * caller handed in.
+ */
+export class ExternalServiceResponseMalformedError extends Data.TaggedError('ExternalServiceResponseMalformedError') {
+}
+/**
+ * The port a use case asks for when it reads reference data from a service
+ * outside this one.
+ */
+export class ExternalHttpClient extends Context.Tag('ExternalHttpClient')() {
+}

package/dist/ports/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Public entry to the ports mechanism: every boundary a use case may ask for,
+ * and the failure each one raises. It gives you every boundary a use case may
+ * ask for, each one a `Context.Tag` with a shape, the value types that shape
+ * uses, and the failure it raises when the driver behind it does not answer.
+ */
+export { BlobStore, type BlobStoreShape, BlobStoreUnavailableError, type StoredBlob, } from './blob-store.js';
+export { DocumentNumberCounter, type DocumentNumberCounterShape, DocumentNumberCounterUnavailableError, type DocumentNumberCountInput, } from './document-number-counter.js';
+export { EventPublisher, type EventPublisherShape, EventPublisherUnavailableError, } from './event-publisher.js';
+export { ExternalHttpClient, type ExternalHttpClientShape, ExternalServiceRefusedError, ExternalServiceResponseMalformedError, ExternalServiceUnavailableError, } from './external-http-client.js';
+export { IntegrationEventOutbox, type IntegrationEventOutboxShape, IntegrationEventOutboxUnavailableError, type OutboxMessage, } from './integration-event-outbox.js';
+export { PORT_FAILURES_IN_THE_EVENTS_LANGUAGE, portUnavailable, } from './port-unavailable.js';
+export { alreadyProcessed, type ClaimProcessedEventInput, claimAccepted, type ProcessedEventClaim, ProcessedEventRegistry, type ProcessedEventRegistryShape, ProcessedEventRegistryUnavailableError, } from './processed-event-registry.js';
+export { QueueMessageProducer, type QueueMessageProducerShape, QueueMessageProducerUnavailableError, } from './queue-message-producer.js';
+export { QueueMessageSource, type QueueMessageSourceShape, QueueMessageSourceUnavailableError, type RawQueueMessage, } from './queue-message-source.js';
+export { DatabaseDidNotAnswerError, ReadinessProbe, type ReadinessProbeShape, } from './readiness-probe.js';
+export { TransactionBoundary, type TransactionBoundaryShape, TransactionBoundaryUnavailableError, } from './transaction-boundary.js';

package/dist/ports/index.js

@@ -0,0 +1,17 @@
+/**
+ * Public entry to the ports mechanism: every boundary a use case may ask for,
+ * and the failure each one raises. It gives you every boundary a use case may
+ * ask for, each one a `Context.Tag` with a shape, the value types that shape
+ * uses, and the failure it raises when the driver behind it does not answer.
+ */
+export { BlobStore, BlobStoreUnavailableError, } from './blob-store.js';
+export { DocumentNumberCounter, DocumentNumberCounterUnavailableError, } from './document-number-counter.js';
+export { EventPublisher, EventPublisherUnavailableError, } from './event-publisher.js';
+export { ExternalHttpClient, ExternalServiceRefusedError, ExternalServiceResponseMalformedError, ExternalServiceUnavailableError, } from './external-http-client.js';
+export { IntegrationEventOutbox, IntegrationEventOutboxUnavailableError, } from './integration-event-outbox.js';
+export { PORT_FAILURES_IN_THE_EVENTS_LANGUAGE, portUnavailable, } from './port-unavailable.js';
+export { alreadyProcessed, claimAccepted, ProcessedEventRegistry, ProcessedEventRegistryUnavailableError, } from './processed-event-registry.js';
+export { QueueMessageProducer, QueueMessageProducerUnavailableError, } from './queue-message-producer.js';
+export { QueueMessageSource, QueueMessageSourceUnavailableError, } from './queue-message-source.js';
+export { DatabaseDidNotAnswerError, ReadinessProbe, } from './readiness-probe.js';
+export { TransactionBoundary, TransactionBoundaryUnavailableError, } from './transaction-boundary.js';

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

@@ -0,0 +1,44 @@
+import { Context, type DateTime, type Effect } from 'effect';
+declare const IntegrationEventOutboxUnavailableError_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: "IntegrationEventOutboxUnavailableError";
+} & Readonly<A>;
+/**
+ * The outbox driver did not answer; `operation` names the call and `cause`
+ * carries the driver's own error.
+ */
+export declare class IntegrationEventOutboxUnavailableError extends IntegrationEventOutboxUnavailableError_base<{
+    readonly operation: string;
+    readonly cause: unknown;
+}> {
+}
+/**
+ * One message waiting in the outbox: its own id, what it is, which schema
+ * shaped it, when it happened, and what it carries.
+ */
+export interface OutboxMessage {
+    readonly messageId: string;
+    readonly eventType: string;
+    readonly schemaVersion: number;
+    readonly occurredAt: DateTime.Utc;
+    readonly payload: {
+        readonly [key: string]: unknown;
+    };
+}
+/**
+ * The outbox holds messages a use case enqueues in the same transaction as
+ * its state change. The outbox relay reads and sends them out separately,
+ * so "saved" and "announced" never drift apart.
+ */
+export interface IntegrationEventOutboxShape {
+    readonly enqueue: (messages: readonly OutboxMessage[]) => Effect.Effect<void, IntegrationEventOutboxUnavailableError>;
+    readonly pending: (limit: number) => Effect.Effect<readonly OutboxMessage[], IntegrationEventOutboxUnavailableError>;
+    readonly markDispatched: (messageIds: readonly string[]) => Effect.Effect<void, IntegrationEventOutboxUnavailableError>;
+}
+declare const IntegrationEventOutbox_base: Context.TagClass<IntegrationEventOutbox, "IntegrationEventOutbox", IntegrationEventOutboxShape>;
+/**
+ * The port a use case asks for when it enqueues an event in the same
+ * transaction as the state change that caused it.
+ */
+export declare class IntegrationEventOutbox extends IntegrationEventOutbox_base {
+}
+export {};

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

@@ -0,0 +1,13 @@
+import { Context, Data } from 'effect';
+/**
+ * The outbox driver did not answer; `operation` names the call and `cause`
+ * carries the driver's own error.
+ */
+export class IntegrationEventOutboxUnavailableError extends Data.TaggedError('IntegrationEventOutboxUnavailableError') {
+}
+/**
+ * The port a use case asks for when it enqueues an event in the same
+ * transaction as the state change that caused it.
+ */
+export class IntegrationEventOutbox extends Context.Tag('IntegrationEventOutbox')() {
+}

package/dist/ports/port-unavailable.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Builds the "did not answer" failure factory around one port's own
+ * `<Port>UnavailableError` constructor. An adapter writes
+ * `const unavailable = portUnavailable(XUnavailableError)` once, then
+ * calls `unavailable('byId')(cause)` on every path that reaches the
+ * driver.
+ */
+export declare const portUnavailable: <E>(Unavailable: new (fields: {
+    readonly operation: string;
+    readonly cause: unknown;
+}) => E) => (operation: string) => (cause: unknown) => E;
+/**
+ * A port failure named in the event's language rather than as
+ * `<Port>UnavailableError`, with the sentence that earns the exception.
+ * The list is short on purpose: every member is a place where the
+ * uniform name would have told the reader less than the event does.
+ * The canon package's mechanism-form rule reads its own copy of this
+ * roster, so the two tables are held equal by hand: a name added here
+ * has to reach `@satorio/canon` before the guard allows it.
+ */
+export declare const PORT_FAILURES_IN_THE_EVENTS_LANGUAGE: Readonly<Record<string, string>>;

package/dist/ports/port-unavailable.js

@@ -0,0 +1,30 @@
+/**
+ * Builds the "did not answer" failure factory around one port's own
+ * `<Port>UnavailableError` constructor. An adapter writes
+ * `const unavailable = portUnavailable(XUnavailableError)` once, then
+ * calls `unavailable('byId')(cause)` on every path that reaches the
+ * driver.
+ */
+export const portUnavailable = (Unavailable) => (operation) => (cause) => new Unavailable({ operation, cause });
+/**
+ * A port failure named in the event's language rather than as
+ * `<Port>UnavailableError`, with the sentence that earns the exception.
+ * The list is short on purpose: every member is a place where the
+ * uniform name would have told the reader less than the event does.
+ * The canon package's mechanism-form rule reads its own copy of this
+ * roster, so the two tables are held equal by hand: a name added here
+ * has to reach `@satorio/canon` before the guard allows it.
+ */
+export const PORT_FAILURES_IN_THE_EVENTS_LANGUAGE = {
+    DatabaseDidNotAnswerError: 'the probe has one operation and two named reasons, so `reason` says ' +
+        'more in a log line than `operation` and `cause` ever could.',
+    ExternalServiceUnavailableError: 'one process calls several external services through this one port, ' +
+        'so the failure has to say which service went quiet before anybody ' +
+        'can act on it.',
+    ExternalServiceRefusedError: 'the service answered, and the status code is the answer: a 404 sends ' +
+        'a caller down a different path than a 403, and `cause` would hide ' +
+        'that behind a word.',
+    ExternalServiceResponseMalformedError: 'the service answered and the body did not fit the schema, which is a ' +
+        'different event from silence and asks a different question of ' +
+        'whoever reads it.',
+};

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

@@ -0,0 +1,57 @@
+import { Context, type DateTime, type Effect } from 'effect';
+declare const ProcessedEventRegistryUnavailableError_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: "ProcessedEventRegistryUnavailableError";
+} & Readonly<A>;
+/**
+ * The claim-once driver did not answer; `operation` names the call and `cause`
+ * carries the driver's own error.
+ */
+export declare class ProcessedEventRegistryUnavailableError extends ProcessedEventRegistryUnavailableError_base<{
+    readonly operation: string;
+    readonly cause: unknown;
+}> {
+}
+/**
+ * The two states of the claim-once lock: this run took the event, or somebody
+ * already had.
+ *
+ * The claim-once lock has exactly two states: an event is claimed for the
+ * first time, or it was already claimed, and then the timestamp is known.
+ */
+export type ProcessedEventClaim = {
+    readonly _tag: 'ClaimAccepted';
+} | {
+    readonly _tag: 'AlreadyProcessed';
+    readonly processedAt: DateTime.Utc;
+};
+/**
+ * The claim nobody had taken yet, so this run is the one that does the work.
+ */
+export declare const claimAccepted: ProcessedEventClaim;
+/**
+ * The claim somebody else already took, with the moment they took it.
+ */
+export declare const alreadyProcessed: (processedAt: DateTime.Utc) => ProcessedEventClaim;
+/**
+ * What a claim needs: which event is being claimed, and the moment it is
+ * claimed at.
+ */
+export interface ClaimProcessedEventInput {
+    readonly eventId: string;
+    readonly processedAt: DateTime.Utc;
+}
+/**
+ * What the claim-once lock offers: one call that either takes an event for the
+ * first time or says when it was taken before.
+ */
+export interface ProcessedEventRegistryShape {
+    readonly claim: (input: ClaimProcessedEventInput) => Effect.Effect<ProcessedEventClaim, ProcessedEventRegistryUnavailableError>;
+}
+declare const ProcessedEventRegistry_base: Context.TagClass<ProcessedEventRegistry, "ProcessedEventRegistry", ProcessedEventRegistryShape>;
+/**
+ * The port a use case asks for when an event must be acted on exactly once,
+ * however many times it arrives.
+ */
+export declare class ProcessedEventRegistry extends ProcessedEventRegistry_base {
+}
+export {};

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

@@ -0,0 +1,24 @@
+import { Context, Data } from 'effect';
+/**
+ * The claim-once driver did not answer; `operation` names the call and `cause`
+ * carries the driver's own error.
+ */
+export class ProcessedEventRegistryUnavailableError extends Data.TaggedError('ProcessedEventRegistryUnavailableError') {
+}
+/**
+ * The claim nobody had taken yet, so this run is the one that does the work.
+ */
+export const claimAccepted = { _tag: 'ClaimAccepted' };
+/**
+ * The claim somebody else already took, with the moment they took it.
+ */
+export const alreadyProcessed = (processedAt) => ({
+    _tag: 'AlreadyProcessed',
+    processedAt,
+});
+/**
+ * The port a use case asks for when an event must be acted on exactly once,
+ * however many times it arrives.
+ */
+export class ProcessedEventRegistry extends Context.Tag('ProcessedEventRegistry')() {
+}