@satorio/machinery 0.2.1

package/dictionary/workflow.toon

@@ -0,0 +1,29 @@
+package: @satorio/machinery
+version: 0.2.1
+mechanism:
+  mechanism: workflow
+  import: @satorio/machinery/workflow
+  kind: foundation
+  page: mechanisms/workflow
+  what: "Public entry to the workflow mechanism: the combinators a use case composes its own beat from."
+  whatUk: "Публічний вхід до механізму workflow: комбінатори, з яких процедура складає власний такт."
+  rows[19]{name,kind,signature,fallback,caption,captionUk,anchor}:
+    ClaimOnce,value,type,"","The exactly-once claim: shared ground for every use case that takes an event or command once.","Резервація рівно один раз: спільний ґрунт для кожної процедури, яка бере подію або команду один раз.",workflow-ClaimOnce-value
+    DEFAULT_PUBLISH_PENDING_EVENTS_SETTINGS,value,PublishPendingEventsSettings,"",The pace the relay keeps when a service names none of its own.,"Темп, який тримає трансмітер вихідних подій, коли сервіс не називає власного.",workflow-DEFAULT-PUBLISH-PENDING-EVENTS-SETTINGS-value
+    OnClaimMatchers,value,interface,"","The two branches `onClaim` takes: what to do when the event was already claimed, and what to do when this run claims it.","Дві гілки, які бере `onClaim`: що робити, коли подію вже зарезервовано, і що робити, коли її резервує цей прогін.",workflow-OnClaimMatchers-value
+    PublishPendingEventsSettings,value,interface,"","How the relay paces itself: how many messages one beat takes, and how long it waits between beats.","Як трансмітер вихідних подій задає собі темп: скільки повідомлень бере один такт і скільки він чекає між тактами.",workflow-PublishPendingEventsSettings-value
+    UpcastStep,value,interface,"","One lift, from the version it names to the next one up.","Один підйом, від названої версії до наступної вгору.",workflow-UpcastStep-value
+    VersionedEventDefinition,value,interface,"",An event stored yesterday is read by today's code.,"Подію, збережену вчора, читає сьогоднішній код.",workflow-VersionedEventDefinition-value
+    claimAsProcessedAt,procedure,"(idempotencyKey: string, processedAt: DateTime.Utc) => ClaimOnce","","Claims with a processedAt supplied by the caller, for a handler that has already read the clock and must store that exact moment.","Резервує з `processedAt`, поданим викликачем, — для обробника, який уже прочитав годинник і мусить зберегти саме ту мить.",workflow-claimAsProcessedAt-procedure
+    claimAsProcessedNow,procedure,"(idempotencyKey: string) => ClaimOnce","","Claims with the current time, for a caller that only needs the claim.","Резервує з поточним часом — для викликача, якому потрібна лише резервація.",workflow-claimAsProcessedNow-procedure
+    decodeStoredPayload,procedure,"<S extends Schema.Schema.AnyNoContext>(definition: VersionedEventDefinition<S>, storedVersion: number, payload: unknown) => Effect.Effect<Schema.Schema.Type<S>, VersionedPayloadFailure | ParseResult.ParseError>","",Lifts a stored payload to the current version and decodes it with the current schema.,Підіймає збережений payload до поточної версії і декодує його поточною схемою.,workflow-decodeStoredPayload-procedure
+    keepPublishingPendingEvents,procedure,"(settings: PublishPendingEventsSettings = DEFAULT_PUBLISH_PENDING_EVENTS_SETTINGS) => Effect.Effect<never, never, IntegrationEventOutbox | EventPublisher>","",Runs the outbox relay for as long as the service lives.,"Крутить трансмітер вихідних подій стільки, скільки живе сервіс.",workflow-keepPublishingPendingEvents-procedure
+    onClaim,procedure,"<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>","","Branches on the state of the exactly-once claim: AlreadyProcessed goes one way, ClaimAccepted the other.","Розгалужується на стані резервації: `AlreadyProcessed` іде одним шляхом, `ClaimAccepted` — іншим.",workflow-onClaim-procedure
+    publishOneBatch,procedure,"(batchLimit: number) => Effect.Effect<number, PublishPendingEventsFailure, IntegrationEventOutbox | EventPublisher>","","One outbox relay beat: take a batch of undelivered messages, hand it to the publisher, then mark it dispatched.","Один такт трансмітера вихідних подій: узяти пачку недоставлених повідомлень, віддати її публікаторові, тоді позначити її відправленою.",workflow-publishOneBatch-procedure
+    transactionally,procedure,"<A, E, R>(work: Effect.Effect<A, E, R>)","","Wraps work in a transaction boundary: pulls TransactionBoundary from context and runs the work through it.","Загортає роботу в межу транзакції: дістає `TransactionBoundary` з контексту і проганяє роботу крізь неї.",workflow-transactionally-procedure
+    upcastToCurrentVersion,procedure,"<S extends Schema.Schema.AnyNoContext>(definition: VersionedEventDefinition<S>, storedVersion: number, payload: unknown) => Effect.Effect<unknown, VersionedPayloadFailure>","","Lifts a stored payload from the version it was written at to the version this code reads, one step per version, in order.","Підіймає збережений payload від версії, якою його записали, до версії, яку читає цей код, по одному кроку на версію, по порядку.",workflow-upcastToCurrentVersion-procedure
+    MissingUpcastStepError,failure,"Data.TaggedError<{ readonly eventType: string; readonly fromVersion: number; readonly currentVersion: number }>","","One version between the stored payload and the current one has no upcast step, so the lift cannot finish.","Одна версія між збереженим payload і поточною не має кроку підйому, тож підйом не доходить до кінця.",workflow-MissingUpcastStepError-failure
+    PublishPendingEventsFailure,failure,type,"","What one beat of the relay can meet: the outbox did not answer, or the publisher did not.","Що може зустріти один такт трансмітера: буфер трансмітера не відповів або публікатор не відповів.",workflow-PublishPendingEventsFailure-failure
+    SchemaVersionFromTheFutureError,failure,"Data.TaggedError<{ readonly eventType: string; readonly storedVersion: number; readonly currentVersion: number }>","",The stored payload says it was written by a newer version of this code than the one reading it.,"Збережений payload каже, що його записала новіша версія цього коду, ніж та, що його читає.",workflow-SchemaVersionFromTheFutureError-failure
+    UpcastStepFailedError,failure,"Data.TaggedError<{ readonly eventType: string; readonly fromVersion: number; readonly cause: unknown }>","",An upcast step threw while lifting the payload one version up.,"Крок підйому кинув помилку, поки підіймав payload на версію вгору.",workflow-UpcastStepFailedError-failure
+    VersionedPayloadFailure,failure,type,"",Every way reading a stored payload can refuse.,"Кожен спосіб, яким читання збереженого payload може відмовити.",workflow-VersionedPayloadFailure-failure

package/dist/bin/command.d.ts

@@ -0,0 +1,45 @@
+/**
+ * What one run of the command comes back with: the whole of what it
+ * prints, and the code it leaves behind. A refusal and an answer travel
+ * in the same shape, so the runner never decides for itself which of the
+ * two it is holding.
+ *
+ * @internal
+ */
+export interface CommandAnswer {
+    readonly text: string;
+    readonly code: number;
+}
+/**
+ * The three lines a refusal is written in here: what happened, why that
+ * stops this command, and what to do about it.
+ *
+ * @internal
+ */
+export declare const refusalOf: (happened: string, matters: string, todo: string) => string;
+/**
+ * Every command this runner answers, one line each, in the order a
+ * caller meets them.
+ *
+ * @internal
+ */
+export declare const USAGE: string;
+/**
+ * One run of the command, against the dictionary directory this package
+ * ships at `root`. It prints a file that already exists rather than
+ * building one, so it asks for no test runner, no compiler and no
+ * network — an agent gets the same answer from a node_modules directory
+ * as a reader gets from the repository.
+ *
+ * @internal
+ */
+export declare const runMachinery: (argv: readonly string[], root: string) => CommandAnswer;
+/**
+ * Whether a write failed because the reader on the other end of the pipe
+ * closed it. A caller who pipes an answer into `head` closes it on
+ * purpose, and a runner that dies with a stack trace over that reports a
+ * fault that never happened.
+ *
+ * @internal
+ */
+export declare const isBrokenPipe: (error: unknown) => boolean;

package/dist/bin/command.js

@@ -0,0 +1,113 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * The three lines a refusal is written in here: what happened, why that
+ * stops this command, and what to do about it.
+ *
+ * @internal
+ */
+export const refusalOf = (happened, matters, todo) => [
+    `what happened: ${happened}`,
+    `why this matters: ${matters}`,
+    `what to do: ${todo}`,
+].join('\n');
+/**
+ * Every command this runner answers, one line each, in the order a
+ * caller meets them.
+ *
+ * @internal
+ */
+export const USAGE = [
+    'satorio-machinery surface [mechanism] [--json|--toon]',
+    'satorio-machinery mechanisms [--json|--toon]',
+    'satorio-machinery reference [--uk]',
+].join('\n');
+const missingFileRefusal = (path) => refusalOf(`this install carries no ${path}, so there is nothing to print.`, 'the dictionary is what an agent reads instead of the source. An ' +
+    'empty answer reads like a package with nothing in it, which is a ' +
+    'worse lie than a refusal.', 'reinstall @satorio/machinery from a version that ships its ' +
+    'dictionary, or read the same thing in the repository with ' +
+    'bun run surface.');
+const unknownMechanismRefusal = (wanted, known) => refusalOf(`this package has no mechanism called "${wanted}", so there is no ` +
+    'card to hand you.', 'a card is what an agent reads before it writes a line against a ' +
+    'mechanism. A silent empty answer would read as a mechanism with ' +
+    'nothing in it.', `ask for one of ${known.join(', ')}, or run satorio-machinery ` +
+    'mechanisms to read the index first.');
+const unknownCommandRefusal = (wanted) => refusalOf(wanted === ''
+    ? 'this command was run with nothing to do.'
+    : `"${wanted}" is not a command this runner answers.`, 'a runner that guesses what you meant prints something you did not ' +
+    'ask for, and an agent believes it.', `run one of these instead:\n${USAGE}`);
+const twoFormsRefusal = () => refusalOf('both --json and --toon were asked for in one run.', 'the two forms say the same thing in different shapes, so a run that ' +
+    'takes both has to pick one behind your back.', 'ask for one of them, or neither: the tabular form is what you get ' +
+    'when you say nothing, because it is the cheaper one to read.');
+const fileText = (root, path) => {
+    try {
+        return readFileSync(join(root, path), 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+const mechanismNames = (root) => {
+    const text = fileText(root, 'index.json');
+    if (text === null)
+        return null;
+    const index = JSON.parse(text);
+    return (index.index ?? []).map((entry) => entry.mechanism);
+};
+const shippedFile = (root, path) => {
+    const text = fileText(root, path);
+    if (text === null)
+        return { text: missingFileRefusal(path), code: 1 };
+    return { text: text.replace(/\n$/, ''), code: 0 };
+};
+const surfaceAnswer = (root, wanted, extension) => {
+    if (wanted === undefined)
+        return shippedFile(root, `all.${extension}`);
+    const known = mechanismNames(root);
+    if (known === null)
+        return { text: missingFileRefusal('index.json'), code: 1 };
+    if (!known.includes(wanted)) {
+        return { text: unknownMechanismRefusal(wanted, known), code: 1 };
+    }
+    return shippedFile(root, `${wanted}.${extension}`);
+};
+/**
+ * One run of the command, against the dictionary directory this package
+ * ships at `root`. It prints a file that already exists rather than
+ * building one, so it asks for no test runner, no compiler and no
+ * network — an agent gets the same answer from a node_modules directory
+ * as a reader gets from the repository.
+ *
+ * @internal
+ */
+export const runMachinery = (argv, root) => {
+    const words = argv.filter((argument) => !argument.startsWith('--'));
+    const flags = argv.filter((argument) => argument.startsWith('--'));
+    if (flags.includes('--help') || words[0] === 'help') {
+        return { text: USAGE, code: 0 };
+    }
+    if (flags.includes('--json') && flags.includes('--toon')) {
+        return { text: twoFormsRefusal(), code: 1 };
+    }
+    const extension = flags.includes('--json') ? 'json' : 'toon';
+    if (words[0] === 'surface')
+        return surfaceAnswer(root, words[1], extension);
+    if (words[0] === 'mechanisms') {
+        return shippedFile(root, `index.${extension}`);
+    }
+    if (words[0] === 'reference') {
+        return shippedFile(root, flags.includes('--uk') ? 'reference/uk/api.mdx' : 'reference/api.mdx');
+    }
+    return { text: unknownCommandRefusal(words[0] ?? ''), code: 1 };
+};
+/**
+ * Whether a write failed because the reader on the other end of the pipe
+ * closed it. A caller who pipes an answer into `head` closes it on
+ * purpose, and a runner that dies with a stack trace over that reports a
+ * fault that never happened.
+ *
+ * @internal
+ */
+export const isBrokenPipe = (error) => typeof error === 'object' &&
+    error !== null &&
+    error.code === 'EPIPE';

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isBrokenPipe, runMachinery } from './bin/command.js';
+const dictionaryRoot = join(fileURLToPath(new URL('.', import.meta.url)), '..', 'dictionary');
+const answer = runMachinery(process.argv.slice(2), dictionaryRoot);
+process.stdout.on('error', (error) => {
+    process.exitCode = isBrokenPipe(error) ? answer.code : 1;
+});
+process.stdout.write(`${answer.text}\n`);
+process.exitCode = answer.code;

package/dist/core/bigint-json.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Use as the replacer argument to `JSON.stringify`. It turns bigint into a
+ * decimal string, so the exact integer survives instead of being silently
+ * rounded by a floating-point number.
+ */
+export declare const bigIntsAsDecimalStrings: (_key: string, value: unknown) => unknown;

package/dist/core/bigint-json.js

@@ -0,0 +1,6 @@
+/**
+ * Use as the replacer argument to `JSON.stringify`. It turns bigint into a
+ * decimal string, so the exact integer survives instead of being silently
+ * rounded by a floating-point number.
+ */
+export const bigIntsAsDecimalStrings = (_key, value) => (typeof value === 'bigint' ? value.toString(10) : value);

package/dist/core/closed-set.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Turns an array of string literals into a closed set: the values, a union
+ * type of their members, and an `is` guard, all from one source. The guard
+ * can never drift from the list it guards.
+ */
+export interface ClosedSet<T extends readonly string[]> {
+    readonly values: T;
+    readonly is: (value: string) => value is T[number];
+}
+/**
+ * Builds a closed set from an array of string literals, so the guard and the
+ * list it guards come from one source.
+ */
+export declare const closedSet: <const T extends readonly string[]>(values: T) => ClosedSet<T>;

package/dist/core/closed-set.js

@@ -0,0 +1,8 @@
+/**
+ * Builds a closed set from an array of string literals, so the guard and the
+ * list it guards come from one source.
+ */
+export const closedSet = (values) => ({
+    values,
+    is: (value) => values.includes(value),
+});

package/dist/core/domain-error.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Base class for domain errors. It sets `error.name` to the subclass's own
+ * class name via `new.target`, so a subclass never repeats
+ * `this.name = '...'`. Pass the message through `super(...)`.
+ */
+export declare class DomainError extends Error {
+    constructor(message: string);
+}

package/dist/core/domain-error.js

@@ -0,0 +1,11 @@
+/**
+ * Base class for domain errors. It sets `error.name` to the subclass's own
+ * class name via `new.target`, so a subclass never repeats
+ * `this.name = '...'`. Pass the message through `super(...)`.
+ */
+export class DomainError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}

package/dist/core/environment.d.ts

@@ -0,0 +1,124 @@
+import { Config, ConfigError, Option, Redacted } from 'effect';
+/**
+ * A refusal in the three parts a reader needs: what happened, why this
+ * mechanism cannot go on without it, and what to do next. All three
+ * fields are required, so a one-line refusal cannot be expressed here.
+ */
+export interface Refusal {
+    readonly what: string;
+    readonly why: string;
+    readonly whatToDo: string;
+}
+/**
+ * Sews a refusal into the one line an operator reads in a log or a
+ * startup failure.
+ */
+export declare const refusalText: (refusal: Refusal) => string;
+/**
+ * The one failure a refusing variable raises, with its three parts sewn into a
+ * single line.
+ *
+ * The failure a reader meets when one named variable refuses: the three parts,
+ * sewn into the one line, against the name of the variable that asked for
+ * them. A mechanism that chooses between two variables builds its own refusal
+ * from here rather than writing a second `ConfigError` of its own.
+ */
+export declare const refusalFor: (name: string, refusal: Refusal) => ConfigError.ConfigError;
+/**
+ * Reads a variable that a mechanism cannot work without, and refuses in
+ * three parts when it is missing or blank. The reading goes through
+ * `Config.option` on purpose: `Config.validate` fires only on a value
+ * that is present and invalid, so a variable nobody set comes back as
+ * `MissingData` with the runtime's own wording and the three parts
+ * written here never reach the newcomer who simply forgot to set it.
+ */
+export declare const requiredText: (name: string, refusal: Refusal) => Config.Config<string>;
+/**
+ * Reads a secret a mechanism cannot work without, and refuses in the same
+ * three parts when it is missing or blank. The value comes back redacted,
+ * so it never reaches a log line by accident.
+ */
+export declare const requiredSecret: (name: string, refusal: Refusal) => Config.Config<Redacted.Redacted>;
+/**
+ * Reads a whole number inside a range, and refuses in three parts when it is
+ * not one.
+ *
+ * Reads a whole number a mechanism cannot work without, and refuses in the
+ * same three parts when it is missing, blank, not a whole number, or outside
+ * the range the mechanism can act on. `lowest` and `highest` are both
+ * inclusive.
+ */
+export declare const wholeNumberWithin: (name: string, lowest: number, highest: number, refusal: Refusal) => Config.Config<number>;
+/**
+ * Reads a whole number a mechanism is happy to do without, and falls
+ * back to the value it names when nobody set the variable. A value that
+ * *is* set still has to be a whole number inside the range, and refuses
+ * in the same three parts when it is not: a fallback covers the operator
+ * who left the variable alone, never the one who typed something the
+ * mechanism cannot act on.
+ */
+export declare const wholeNumberFallingBackTo: (name: string, lowest: number, highest: number, fallback: number, refusal: Refusal) => Config.Config<number>;
+/**
+ * Reads a variable that is legitimately optional with no default,
+ * because somebody outside this process decides it. The answer is
+ * `Option.none` when the variable is unset or blank, so a caller reads
+ * one absence rather than two.
+ */
+export declare const optionalText: (name: string) => Config.Config<Option.Option<string>>;
+/**
+ * Reads a secret that is legitimately optional, and hands back
+ * `Option.none` when it is unset or blank. The value stays redacted the
+ * whole way, so a mechanism that chooses between two ways of proving who
+ * it is can ask whether the secret is there without ever holding it in
+ * the clear.
+ */
+export declare const optionalSecret: (name: string) => Config.Config<Option.Option<Redacted.Redacted>>;
+/**
+ * Which of three states a variable stands in. There is no fourth state
+ * and no silence: a variable either has a safe fallback, refuses without
+ * one, or is handed on to somebody outside this process.
+ */
+export type EnvironmentState = {
+    readonly state: 'fallsBackTo';
+    readonly value: string;
+} | {
+    readonly state: 'refuses';
+    readonly refusal: Refusal;
+} | {
+    readonly state: 'handedOn';
+    readonly consequence: string;
+};
+/**
+ * The variable is safe to omit, and this is what happens instead.
+ */
+export declare const fallsBackTo: (value: string) => EnvironmentState;
+/**
+ * The mechanism cannot work without the variable, and this is the
+ * three-part text a reader meets when it is missing.
+ */
+export declare const refuses: (refusal: Refusal) => EnvironmentState;
+/**
+ * The variable is legitimately optional with no default, because
+ * somebody else decides it, and this is what follows from leaving it
+ * unset.
+ */
+export declare const handedOn: (consequence: string) => EnvironmentState;
+/**
+ * One variable a mechanism reads, and the one state it stands in.
+ *
+ * One variable a mechanism reads: its name — whole, or the suffix an
+ * application prefixes at mount time — what it is for, and the one state it
+ * stands in. A mechanism's `ENVIRONMENT` is the list of these, and it is the
+ * only place a variable name is written.
+ */
+export interface EnvironmentEntry {
+    readonly name: string;
+    readonly prefixed?: boolean;
+    readonly what: string;
+    readonly state: EnvironmentState;
+}
+/**
+ * The name an operator sets, with `<PREFIX>` standing in front of a
+ * suffix the application chooses at mount time.
+ */
+export declare const variableNameOf: (entry: EnvironmentEntry) => string;

package/dist/core/environment.js

@@ -0,0 +1,115 @@
+import { Config, ConfigError, Either, Option, Redacted } from 'effect';
+/**
+ * Sews a refusal into the one line an operator reads in a log or a
+ * startup failure.
+ */
+export const refusalText = (refusal) => `${refusal.what} ${refusal.why} ${refusal.whatToDo}`;
+/**
+ * The one failure a refusing variable raises, with its three parts sewn into a
+ * single line.
+ *
+ * The failure a reader meets when one named variable refuses: the three parts,
+ * sewn into the one line, against the name of the variable that asked for
+ * them. A mechanism that chooses between two variables builds its own refusal
+ * from here rather than writing a second `ConfigError` of its own.
+ */
+export const refusalFor = (name, refusal) => ConfigError.InvalidData([name], refusalText(refusal));
+const invalid = (name, refusal) => Either.left(refusalFor(name, refusal));
+const blank = (value) => value.trim().length === 0;
+/**
+ * Reads a variable that a mechanism cannot work without, and refuses in
+ * three parts when it is missing or blank. The reading goes through
+ * `Config.option` on purpose: `Config.validate` fires only on a value
+ * that is present and invalid, so a variable nobody set comes back as
+ * `MissingData` with the runtime's own wording and the three parts
+ * written here never reach the newcomer who simply forgot to set it.
+ */
+export const requiredText = (name, refusal) => Config.option(Config.string(name)).pipe(Config.mapOrFail((held) => Option.match(held, {
+    onNone: () => invalid(name, refusal),
+    onSome: (value) => blank(value) ? invalid(name, refusal) : Either.right(value.trim()),
+})));
+/**
+ * Reads a secret a mechanism cannot work without, and refuses in the same
+ * three parts when it is missing or blank. The value comes back redacted,
+ * so it never reaches a log line by accident.
+ */
+export const requiredSecret = (name, refusal) => Config.option(Config.redacted(name)).pipe(Config.mapOrFail((held) => Option.match(held, {
+    onNone: () => invalid(name, refusal),
+    onSome: (secret) => blank(Redacted.value(secret))
+        ? invalid(name, refusal)
+        : Either.right(secret),
+})));
+const wholeNumberIn = (name, text, lowest, highest, refusal) => {
+    const value = Number(text);
+    return Number.isInteger(value) && value >= lowest && value <= highest
+        ? Either.right(value)
+        : invalid(name, refusal);
+};
+/**
+ * Reads a whole number inside a range, and refuses in three parts when it is
+ * not one.
+ *
+ * Reads a whole number a mechanism cannot work without, and refuses in the
+ * same three parts when it is missing, blank, not a whole number, or outside
+ * the range the mechanism can act on. `lowest` and `highest` are both
+ * inclusive.
+ */
+export const wholeNumberWithin = (name, lowest, highest, refusal) => requiredText(name, refusal).pipe(Config.mapOrFail((text) => wholeNumberIn(name, text, lowest, highest, refusal)));
+/**
+ * Reads a whole number a mechanism is happy to do without, and falls
+ * back to the value it names when nobody set the variable. A value that
+ * *is* set still has to be a whole number inside the range, and refuses
+ * in the same three parts when it is not: a fallback covers the operator
+ * who left the variable alone, never the one who typed something the
+ * mechanism cannot act on.
+ */
+export const wholeNumberFallingBackTo = (name, lowest, highest, fallback, refusal) => Config.option(Config.string(name)).pipe(Config.mapOrFail((held) => Option.match(held, {
+    onNone: () => Either.right(fallback),
+    onSome: (text) => blank(text)
+        ? Either.right(fallback)
+        : wholeNumberIn(name, text.trim(), lowest, highest, refusal),
+})));
+/**
+ * Reads a variable that is legitimately optional with no default,
+ * because somebody outside this process decides it. The answer is
+ * `Option.none` when the variable is unset or blank, so a caller reads
+ * one absence rather than two.
+ */
+export const optionalText = (name) => Config.option(Config.string(name)).pipe(Config.map(Option.flatMap((value) => blank(value) ? Option.none() : Option.some(value.trim()))));
+/**
+ * Reads a secret that is legitimately optional, and hands back
+ * `Option.none` when it is unset or blank. The value stays redacted the
+ * whole way, so a mechanism that chooses between two ways of proving who
+ * it is can ask whether the secret is there without ever holding it in
+ * the clear.
+ */
+export const optionalSecret = (name) => Config.option(Config.redacted(name)).pipe(Config.map(Option.flatMap((secret) => blank(Redacted.value(secret)) ? Option.none() : Option.some(secret))));
+/**
+ * The variable is safe to omit, and this is what happens instead.
+ */
+export const fallsBackTo = (value) => ({
+    state: 'fallsBackTo',
+    value,
+});
+/**
+ * The mechanism cannot work without the variable, and this is the
+ * three-part text a reader meets when it is missing.
+ */
+export const refuses = (refusal) => ({
+    state: 'refuses',
+    refusal,
+});
+/**
+ * The variable is legitimately optional with no default, because
+ * somebody else decides it, and this is what follows from leaving it
+ * unset.
+ */
+export const handedOn = (consequence) => ({
+    state: 'handedOn',
+    consequence,
+});
+/**
+ * The name an operator sets, with `<PREFIX>` standing in front of a
+ * suffix the application chooses at mount time.
+ */
+export const variableNameOf = (entry) => entry.prefixed === true ? `<PREFIX>${entry.name}` : entry.name;

package/dist/core/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Public entry to the core mechanism: the few pieces every other mechanism
+ * leans on, and which lean on nothing themselves. It gives you the pieces
+ * every other mechanism leans on and which lean on nothing themselves — a safe
+ * unique id, a closed set of allowed values, exact bigints on the wire, the
+ * base domain error, and the three-part refusal an adapter uses to say what a
+ * variable is for and what to do when it is missing.
+ */
+export { bigIntsAsDecimalStrings } from './bigint-json.js';
+export { type ClosedSet, closedSet } from './closed-set.js';
+export { DomainError } from './domain-error.js';
+export { type EnvironmentEntry, type EnvironmentState, fallsBackTo, handedOn, optionalSecret, optionalText, type Refusal, refusalFor, refusalText, refuses, requiredSecret, requiredText, variableNameOf, wholeNumberFallingBackTo, wholeNumberWithin, } from './environment.js';
+export { isUlid, NotAUlidError, type Ulid, ulid } from './ulid.js';

package/dist/core/index.js

@@ -0,0 +1,13 @@
+/**
+ * Public entry to the core mechanism: the few pieces every other mechanism
+ * leans on, and which lean on nothing themselves. It gives you the pieces
+ * every other mechanism leans on and which lean on nothing themselves — a safe
+ * unique id, a closed set of allowed values, exact bigints on the wire, the
+ * base domain error, and the three-part refusal an adapter uses to say what a
+ * variable is for and what to do when it is missing.
+ */
+export { bigIntsAsDecimalStrings } from './bigint-json.js';
+export { closedSet } from './closed-set.js';
+export { DomainError } from './domain-error.js';
+export { fallsBackTo, handedOn, optionalSecret, optionalText, refusalFor, refusalText, refuses, requiredSecret, requiredText, variableNameOf, wholeNumberFallingBackTo, wholeNumberWithin, } from './environment.js';
+export { isUlid, NotAUlidError, ulid } from './ulid.js';

package/dist/core/ulid.d.ts

@@ -0,0 +1,27 @@
+import { DomainError } from './domain-error.js';
+declare const ulidBrand: unique symbol;
+/**
+ * A ULID: the identifier a machine mints for a record, sortable by the moment
+ * it was minted, and a plain string everywhere it travels.
+ */
+export type Ulid = string & {
+    readonly [ulidBrand]: 'Ulid';
+};
+/**
+ * Whether a string is a ULID, as a type guard, so a caller narrows the type
+ * without raising anything.
+ */
+export declare const isUlid: (value: string) => value is Ulid;
+/**
+ * What a caller meets when a string that is not a ULID reaches `ulid`; the
+ * message quotes the exact value received.
+ */
+export declare class NotAUlidError extends DomainError {
+    constructor(value: string);
+}
+/**
+ * Reads a string as a ULID and throws `NotAUlidError` when it is not one, so a
+ * raw string comes through one door.
+ */
+export declare const ulid: (raw: string) => Ulid;
+export {};

package/dist/core/ulid.js

@@ -0,0 +1,27 @@
+import { DomainError } from './domain-error.js';
+const TWENTY_SIX_UPPERCASE_CROCKFORD_SYMBOLS_STARTING_BELOW_EIGHT = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+/**
+ * Whether a string is a ULID, as a type guard, so a caller narrows the type
+ * without raising anything.
+ */
+export const isUlid = (value) => TWENTY_SIX_UPPERCASE_CROCKFORD_SYMBOLS_STARTING_BELOW_EIGHT.test(value);
+/**
+ * What a caller meets when a string that is not a ULID reaches `ulid`; the
+ * message quotes the exact value received.
+ */
+export class NotAUlidError extends DomainError {
+    constructor(value) {
+        super(`A ULID is 26 Crockford Base32 characters in upper case: the first ` +
+            `character is 0-7, and the rest exclude I, L, O, and U. ` +
+            `Received ${JSON.stringify(value)}.`);
+    }
+}
+/**
+ * Reads a string as a ULID and throws `NotAUlidError` when it is not one, so a
+ * raw string comes through one door.
+ */
+export const ulid = (raw) => {
+    if (!isUlid(raw))
+        throw new NotAUlidError(raw);
+    return raw;
+};

package/dist/graphql/builder.d.ts

@@ -0,0 +1,36 @@
+import '@pothos/plugin-directives';
+import '@pothos/plugin-sub-graph';
+import { hasResolvableKey } from '@pothos/plugin-federation';
+/**
+ * The two variations of one schema: `Public` (external) and `Internal`
+ * (admin and service operations). Federation (`@key` + `resolveReference`)
+ * turns each variation into a subgraph for the gateway.
+ *
+ * @internal
+ */
+export declare const SUB_GRAPH_NAMES: readonly ["Public", "Internal"];
+/**
+ * @internal
+ */
+export type SubGraphName = (typeof SUB_GRAPH_NAMES)[number];
+/**
+ * The federation and subgraph settings every schema in this package
+ * shares, fixed here so two services cannot drift apart.
+ *
+ * @internal
+ */
+export declare const subGraphOptions: {
+    defaultForTypes: ("Public" | "Internal")[];
+    fieldsInheritFromTypes: boolean;
+    explicitlyIncludeType: (type: Parameters<typeof hasResolvableKey>[0]) => boolean;
+};
+/**
+ * Returns a builder factory carrying the resolver context type. The context
+ * itself belongs to your service, so this returns a factory, not a ready
+ * instance. Every service shares the same plugins and subgraph settings,
+ * fixed here.
+ */
+export declare const makeSubGraphSchemaBuilder: <Context extends object>() => PothosSchemaTypes.SchemaBuilder<PothosSchemaTypes.ExtendDefaultTypes<{
+    Context: Context;
+    SubGraphs: SubGraphName;
+}>>;