@bett3r-dev/pv3 1.0.0 → 1.1.7

package/build/libraries/eventsourcing/commandHandlers/index.js

@@ -0,0 +1,1065 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCommandHandlers = exports.handleCommand = exports.defaultEventsourcingLoad = exports.validateInvariants = exports.formatEventSourcedCommandResponse = exports.formatDomainModelCommandResponse = exports.reduceEventsIntoState = exports.defaultCommit = exports.defaultHandler = exports.domainModelCommit = exports.domainModelLoad = exports.loadAggregateState = exports.getNonNoopEventNames = exports.loadStream = exports.getStreamReducer = exports.commitEvents = exports.appendEventsToOwnStreams = exports.prepareEventsToCommit = exports.addMetadata = exports.appendEventsToStream = exports.getEventReducers = exports.formatAggregateGetQueryParams = void 0;
+const bett3r_utils_1 = require("@bett3r-dev/bett3r-utils");
+const jsonschema_definer_1 = __importDefault(require("@bett3r-dev/jsonschema-definer"));
+const pv3_types_1 = require("@bett3r-dev/pv3-types");
+const change_case_1 = require("change-case");
+const ramda_1 = require("ramda");
+const uuidv7_1 = require("uuidv7");
+const reducersByAggregateMap = new Map();
+let getActiveTraceId = () => undefined;
+// Capture the metrics FACADE (not a meter/counter) at module load — that is safe. Resolving a
+// concrete counter here (`metrics.getMeter(...).createCounter(...)`) would bind to the no-op
+// MeterProvider before the host registers its real one and stay a permanent no-op (the OTel
+// dual-api module-load hazard); the counter is instead resolved lazily on first skip below.
+let otelMetrics;
+try {
+    const { trace, metrics } = require('@opentelemetry/api');
+    getActiveTraceId = () => {
+        const span = trace.getActiveSpan();
+        const traceId = span?.spanContext().traceId;
+        return traceId && traceId !== '00000000000000000000000000000000' ? traceId : undefined;
+    };
+    otelMetrics = metrics;
+}
+catch {
+    // @opentelemetry/api not available
+}
+// Lazily-resolved, memoized counter for declarative-idempotency dedup skips. Every time a
+// `withIdempotencyCheck(...)` short-circuits the command pipeline (the skip branch below), this
+// increments so the otherwise-invisible dedup activity is countable. Resolved on FIRST use —
+// after the host has registered its MeterProvider — never at module load (see note above).
+let idempotencySkipCounter;
+const getIdempotencySkipCounter = () => {
+    if (idempotencySkipCounter || !otelMetrics)
+        return idempotencySkipCounter;
+    idempotencySkipCounter = otelMetrics.getMeter('pv3').createCounter('pv3.command.idempotency_skip', {
+        description: 'Declarative withIdempotencyCheck dedup short-circuits: a duplicate command matched an idempotency check and skipped the handler + commit before any application code ran. Labelled by { command, aggregate }.'
+    });
+    return idempotencySkipCounter;
+};
+/* ─── Optimistic-concurrency retry observability + backoff ──────────────────────────────
+ *
+ * `executeCommand` has always retried a `ConcurrencyError` up to ten times, IMMEDIATELY and
+ * SILENTLY: nothing counted the retries, nothing named the stream that lost, and giving up
+ * produced one `logger.error` indistinguishable from any other failed command. That is the
+ * wrong shape for a multi-stream command whose fan-out width is a property of the CATALOG —
+ * a Composite Item ("Kit") whose component sits in fifty kits re-runs a fifty-one-stream
+ * command on every conflict, so contention is the thing that decides whether the design
+ * holds, and it was invisible.
+ *
+ * Three instruments, all `{ command, aggregate }`-labelled and therefore BOUNDED. The
+ * contended STREAM is deliberately NOT a label: a stream name is per-entity, so labelling by
+ * it makes the series cardinality equal to the catalog. It goes in the log line instead,
+ * which is where the "WHICH hot item" question is actually answered.
+ *
+ *   pv3.command.occ_retry            one per re-execution — the leading contention indicator.
+ *   pv3.command.occ_retry_backoff    ms actually waited, so backoff can be told apart from
+ *                                    latency spent doing work.
+ *   pv3.command.occ_retry_exhausted  PAGE ON THIS. The command failed after the whole budget;
+ *                                    for a stock decrement that means an order's stock was
+ *                                    never decremented.
+ */
+let occInstruments;
+const getOccInstruments = () => {
+    if (occInstruments || !otelMetrics)
+        return occInstruments;
+    const meter = otelMetrics.getMeter('pv3');
+    occInstruments = {
+        retry: meter.createCounter('pv3.command.occ_retry', {
+            description: 'A command re-executed from the top because its commit lost an optimistic-concurrency check. The leading indicator of write contention on a stream. Labelled by { command, aggregate } — the contended stream is in the accompanying debug log, never a label (per-entity cardinality).'
+        }),
+        backoff: meter.createHistogram('pv3.command.occ_retry_backoff', {
+            description: 'Milliseconds waited before an optimistic-concurrency re-execution (full-jitter, capped). Separates time spent BACKING OFF from time spent working, so a contention problem is not read as a slow command. Labelled by { command, aggregate }.',
+            unit: 'ms'
+        }),
+        exhausted: meter.createCounter('pv3.command.occ_retry_exhausted', {
+            description: 'A command that exhausted its optimistic-concurrency retry budget and FAILED — nothing was committed. PAGE ON THIS: for a stock decrement it means an order never decremented its stock. Labelled by { command, aggregate }.'
+        })
+    };
+    return occInstruments;
+};
+/** The retry budget. Deliberately NOT raised to absorb contention: under sustained
+ * contention more attempts mostly add load — the lever is the WAIT below, not the count. */
+const OCC_RETRY_CEILING = 10;
+const OCC_BACKOFF_BASE_MS = 5;
+const OCC_BACKOFF_CAP_MS = 250;
+/**
+ * FULL JITTER over an exponentially-growing window, plus a small floor.
+ *
+ * Immediate retry is what turns one hot stream into a thundering herd: every loser re-reads,
+ * re-computes and re-appends in lockstep, so they collide again on the same tick and the
+ * conflict rate is preserved rather than drained. Spreading the attempts over a random
+ * interval de-synchronizes them, which is what actually lets one of them win. The floor
+ * guarantees a non-zero wait even on the first retry (a zero-length "backoff" is not one),
+ * and the cap keeps a pathological stream from turning a retry budget into a stall.
+ *
+ * Budget across all 10 retries (attempts 0..9): floor 10×5ms plus a jitter window of
+ * 5+10+20+40+80+160+250+250+250+250 = 1315ms ⇒ **1365ms worst case, ~707ms mean**. Applies
+ * to the pooled path only (see the call site).
+ */
+const occBackoffMs = (attempt) => OCC_BACKOFF_BASE_MS + Math.floor(Math.random() * Math.min(2 ** attempt * OCC_BACKOFF_BASE_MS, OCC_BACKOFF_CAP_MS));
+const canSavepoint = (transaction) => typeof transaction.savepoint === 'function'
+    && typeof transaction.rollbackToSavepoint === 'function'
+    && typeof transaction.releaseSavepoint === 'function';
+/**
+ * The concurrency mode a command actually runs under — resolved here and never read raw, so the
+ * default and the one illegal combination are decided in ONE place.
+ *
+ * `optimistic` is the default (see `CommandConcurrencyMode` for what each mode costs).
+ *
+ * A NON-AGGREGATE External System is `unversioned` BY CONSTRUCTION, whatever it declares: its
+ * load hands the commit `expectedVersion: null` (below), so every event it writes is stored
+ * version-free. Saying so here rather than letting it default to `optimistic` keeps the mode a
+ * true description of what reaches the append — which is what the savepoint gate keys on.
+ * ONE EXCEPTION, and it is not resolvable here: an aggregate command with a CUSTOM `load`
+ * (`multiStream`, `snapshot`'s delegating load aside) bypasses the derivation entirely and keeps
+ * whatever expectation its own load built, so its resolved mode describes the savepoint decision
+ * rather than the append. See the gate in `executeCommand` for what that costs.
+ *
+ * And that is exactly why an AGGREGATE may not declare `unversioned`: it would be asking to
+ * behave like a non-aggregate. An aggregate reduces its stream to state, and a stream whose
+ * events carry no version has no deterministic order to reduce in, so the same events could fold
+ * to a different state on every load. Refused LOUDLY — a silent fallback would produce precisely
+ * the unorderable stream, and it would be found much later, in the reduced state, by someone with
+ * no reason to suspect the declaration.
+ */
+const resolveConcurrencyMode = (commandHandler, command) => {
+    if (command?.concurrency === 'unversioned' && commandHandler?.isAggregate)
+        throw new pv3_types_1.InternalServerError(`Command '${command.name}' on aggregate '${commandHandler.name}' declares concurrency: 'unversioned', which writes every event with version NULL. An aggregate REDUCES its stream to state, and a version-free stream has no deterministic order to reduce in, so the same events could fold to a different state on every load. Version-free streams belong to non-aggregate External Systems, which reduce nothing. Use 'optimistic' (the default), or 'rebase' if — and only if — this aggregate's events are provably commutative.`, 'UNVERSIONED_CONCURRENCY_ON_AGGREGATE', { aggregate: commandHandler.name, command: command.name });
+    return commandHandler?.isAggregate ? (command?.concurrency || 'optimistic') : 'unversioned';
+};
+const validation_1 = require("../../../libraries/validation");
+const utils_1 = require("../../../utils");
+const utils_2 = require("../utils");
+const executionContext_1 = require("../executionContext");
+const formatAggregateGetQueryParams = (params) => ({
+    stream: params.stream,
+    events: params.names,
+    direction: params.backward ? 'backwards' : 'forwards',
+    from: params.from,
+    limit: params.limit,
+    after: params.after,
+    before: params.before
+});
+exports.formatAggregateGetQueryParams = formatAggregateGetQueryParams;
+const getEventReducers = (aggregate) => (reducedState /* = { state: aggregate.initialValue() } */, event) => {
+    const reducer = aggregate.eventReducers[event.name];
+    if (!reducer || reducer === pv3_types_1.ReducerNOOP)
+        return reducedState;
+    return {
+        ...reducedState,
+        state: reducer(reducedState.state, event.data, event.metadata)
+    };
+};
+exports.getEventReducers = getEventReducers;
+const appendEventsToStream = (logger, eventstore, expectedVersion, transaction, retryAttempts = 0) => (events) => {
+    const stream = events[0].stream;
+    return events.length
+        ? eventstore.appendToStream(stream, events, expectedVersion, transaction)
+            .catch((err) => {
+            if (err.type === 'ConcurrencyError' && expectedVersion === null) {
+                if (retryAttempts >= 10) {
+                    logger.error('Event', events[0].name, 'failed after 10 retries', err);
+                    throw err;
+                }
+                logger.debug('Retrying event', events[0].name, 'due to ConcurrencyError', transaction ? 'with transaction' : 'without transaction');
+                return (0, exports.appendEventsToStream)(logger, eventstore, null, transaction, retryAttempts + 1)(events);
+            }
+            throw err;
+        })
+        : Promise.resolve([]);
+};
+exports.appendEventsToStream = appendEventsToStream;
+const addMetadata = ({ metadata, context, stream }) => (event) => {
+    (0, ramda_1.mergeRight)(metadata || {}, event.metadata || {}); //?
+    return {
+        stream,
+        ...event,
+        metadata: {
+            ...(context?.user ? { userId: context.user.id } : {}),
+            ...(0, ramda_1.mergeRight)(metadata || {}, event.metadata || {})
+        }
+    };
+};
+exports.addMetadata = addMetadata;
+const prepareEventsToCommit = (handlerState) => {
+    return Promise.resolve(handlerState.events)
+        .then(bett3r_utils_1.ensureArray)
+        .then((0, bett3r_utils_1.map)((eventFactory) => {
+        return { ...eventFactory() };
+    }))
+        .then((0, bett3r_utils_1.map)((0, exports.addMetadata)(handlerState)));
+};
+exports.prepareEventsToCommit = prepareEventsToCommit;
+/**
+ * `expectedVersion` narrowed to the shape the SINGLE-stream append takes.
+ *
+ * It carries two shapes (see `CommandHandlerState.expectedVersion`): the scalar this
+ * path wants, and the per-stream MAP that `multiStream.commit` consumes. A map reaching
+ * here means a command paired a multi-stream `load` with the single-stream `commit` —
+ * mis-wired, and the one thing we must NOT do about it is coerce it to `undefined`:
+ * that would append with no version expectation at all, silently discarding the
+ * optimistic-concurrency control the load went to the trouble of computing. Fail loudly.
+ *
+ * Still exactly this guard now that the default commit can fan out to several streams
+ * (`appendEventsToOwnStreams` below): what it produces there is a SCALAR expectation routed to
+ * the one stream the load read, never a caller-built per-stream map. A map arriving here is the
+ * same mis-wiring it always was.
+ */
+const singleStreamExpectedVersion = (expectedVersion, commandName) => {
+    if (expectedVersion !== null && typeof expectedVersion === 'object') {
+        throw new pv3_types_1.InternalServerError('A per-stream expectedVersion map reached the single-stream commit. The command\'s load produced a multi-stream expectation but its commit is not the multiStream template.', 'EXPECTED_VERSION_SHAPE_MISMATCH', { command: commandName, streams: Object.keys(expectedVersion) });
+    }
+    return expectedVersion;
+};
+/**
+ * The prepared events keyed by the stream each one actually TARGETS, in first-appearance order.
+ *
+ * A handler may emit onto a stream other than its aggregate's — `createEvent( name, data,
+ * { stream } )` puts a stream on the event and `addMetadata` spreads `stream` BEFORE `...event`,
+ * so the event's own stream wins. `Object.keys` preserves insertion order for non-numeric keys,
+ * so the aggregate's own stream keeps whatever position the handler gave it.
+ */
+const groupEventsByStream = (events) => events.reduce((groups, event) => {
+    (groups[event.stream] ||= []).push(event);
+    return groups;
+}, {});
+/**
+ * The committed events back in the order the HANDLER emitted them.
+ *
+ * A multi-stream append returns its rows GROUPED BY STREAM, but the response is not a set:
+ * `formatEventSourcedCommandResponse` reduces `committedEvents` in array order into the state it
+ * returns, and hosts assert on `events[0].name`. So an interleaved emit (`companion, own,
+ * companion` — teselly's composite-release shape) must not come back regrouped.
+ *
+ * Each stream's rows keep their own relative order through the adapters (both build and insert a
+ * stream's events in the order given, and `RETURNING` follows the VALUES list), so re-threading
+ * the groups against the prepared events restores the emit order exactly. If the two ever fail to
+ * line up — which the adapters make impossible, since both prove nothing was dropped before
+ * returning — the adapter's own array is handed back untouched rather than silently short.
+ */
+const inEmitOrder = (prepared, committed) => {
+    const queues = committed.reduce((grouped, event) => {
+        (grouped[event.stream] ||= []).push(event);
+        return grouped;
+    }, {});
+    const ordered = prepared.map((event) => queues[event.stream]?.shift());
+    return ordered.length === committed.length && ordered.every(Boolean)
+        ? ordered
+        : committed;
+};
+/**
+ * Append each prepared event to THE STREAM IT NAMES, asserting the expectation on THE STREAM THE
+ * LOAD READ and on no other.
+ *
+ * `defaultEventsourcingLoad` takes the head of `handlerState.stream` and records it as the
+ * command's expectation. A single `appendToStream` then targeted `events[0].stream` while
+ * carrying that number, so a handler emitting onto any other stream had its aggregate's head
+ * asserted against a stream nothing had ever compared it to — two streams, one number. It also
+ * numbered EVERY event off `events[0].stream`'s head + index, so a cross-stream command wrote
+ * per-stream version GAPS (which the outbox's per-stream watermark reads as missing events).
+ * Both close here.
+ */
+const appendEventsToOwnStreams = (logger, eventstore, loadedStream, expectedVersion, transaction) => async (events) => {
+    if (!events.length)
+        return [];
+    /* `null` IS NOT AN ASSERTION ABOUT A HEAD — it declares the whole command version-FREE, so
+     * every event it writes is stored with `version = NULL` whatever stream it lands on. There is
+     * nothing per-stream to get right: no numbering happens, so no gaps can open, and nothing is
+     * compared, so no stream can be asserted wrongly. The single append is already exactly
+     * correct for it.
+     *
+     * Keeping it here is also what keeps `appendEventsToStream`'s `expectedVersion === null`
+     * RETRY LOOP on the only path that can ever reach it — the loop is not dropped, it is proven
+     * unreachable from the multi-stream route below, which never sees a null expectation.
+     *
+     * And routing it through `appendToMultipleStreams` would not be equivalent:
+     * `DatabaseEventstore`'s takes every stream's head unconditionally and would VERSION events
+     * that are version-free today, silently changing the class the outbox dedups them by. */
+    if (expectedVersion === null)
+        return (0, exports.appendEventsToStream)(logger, eventstore, null, transaction)(events);
+    const eventsByStream = groupEventsByStream(events);
+    const streams = Object.keys(eventsByStream);
+    // The expectation was computed from ONE stream's head — the stream the load reduced. Every
+    // other stream gets `undefined`: the append reads that stream's own head and numbers from it,
+    // asserting nothing. Never assert a head this command never read; on a stream whose head
+    // moves independently the two can never converge, so the "conflict" is unbreakable and burns
+    // the whole retry budget on a stream the command has no opinion about.
+    const expectationFor = (stream) => stream === loadedStream ? expectedVersion : undefined;
+    if (streams.length === 1)
+        return (0, exports.appendEventsToStream)(logger, eventstore, expectationFor(streams[0]), transaction)(events);
+    if (!eventstore.appendToMultipleStreams)
+        throw new pv3_types_1.InternalServerError('A command emitted events onto several streams but the Eventstore in use does not support multiple streams. Appending them as one stream would number every event off the first stream\'s head, leaving per-stream version gaps.', 'MULTI_STREAM_COMMANDS_NOT_SUPPORTED', { stream: loadedStream, streams });
+    const committed = await eventstore.appendToMultipleStreams(streams.reduce((perStream, stream) => {
+        perStream[stream] = { events: eventsByStream[stream], expectedVersion: expectationFor(stream) };
+        return perStream;
+    }, {}), transaction);
+    return inEmitOrder(events, committed);
+};
+exports.appendEventsToOwnStreams = appendEventsToOwnStreams;
+const commitEvents = (logger, eventstore) => (handlerState, transaction) => {
+    if (!handlerState.events.length)
+        return Promise.resolve(handlerState);
+    const expectedVersion = singleStreamExpectedVersion(handlerState.expectedVersion, handlerState.command?.name);
+    return (0, exports.prepareEventsToCommit)(handlerState)
+        .then((0, exports.appendEventsToOwnStreams)(logger, eventstore, handlerState.stream, expectedVersion, transaction))
+        .then((0, ramda_1.objOf)('committedEvents'))
+        .then((0, ramda_1.mergeRight)(handlerState));
+};
+exports.commitEvents = commitEvents;
+const getStreamReducer = (state, event) => {
+    state[event.stream] ||= { events: [], state: null };
+    state[event.stream].events?.push(event);
+    return state;
+};
+exports.getStreamReducer = getStreamReducer;
+const loadStream = (eventstore) => (stream, options) => {
+    return eventstore.reduceStream({ ...options, stream }, exports.getStreamReducer, {})
+        .then((state) => !Object.keys(state).length
+        ? undefined
+        : state[stream].events);
+};
+exports.loadStream = loadStream;
+const getNonNoopEventNames = (aggregate) => {
+    if (reducersByAggregateMap.has(aggregate.name)) {
+        return reducersByAggregateMap.get(aggregate.name) || [];
+    }
+    const nonNoopEvents = Object.entries(aggregate.eventReducers)
+        .filter(([, reducer]) => reducer !== pv3_types_1.ReducerNOOP)
+        .map(([name]) => name);
+    reducersByAggregateMap.set(aggregate.name, nonNoopEvents);
+    return nonNoopEvents;
+};
+exports.getNonNoopEventNames = getNonNoopEventNames;
+const loadAggregateState = (eventstore) => (aggregate, stream, options, state = aggregate.initialValue()) => {
+    const nonNoopEvents = (0, exports.getNonNoopEventNames)(aggregate);
+    const eventFilter = options?.events
+        ? options.events.filter((name) => nonNoopEvents.includes(name))
+        : nonNoopEvents;
+    return !stream || !aggregate.isAggregate
+        ? Promise.resolve(null)
+        : eventstore.reduceStream({ ...options, stream, events: eventFilter }, (0, exports.getEventReducers)(aggregate), { state })
+            .then((_state) => {
+            return _state || { state };
+        });
+};
+exports.loadAggregateState = loadAggregateState;
+const domainModelLoad = (database, collection, transaction) => (handlerState) => {
+    const innerTransactionOperation = (innerTransaction) => {
+        return innerTransaction
+            .getCollection(collection)
+            .readById(handlerState.params.id)
+            .then((state) => {
+            return (0, ramda_1.assoc)('state', state
+                ? (0, ramda_1.omit)(['id'], state)
+                : handlerState.commandHandler.initialValue(), handlerState);
+        });
+    };
+    return (transaction || handlerState.transaction) ? innerTransactionOperation(transaction || handlerState.transaction) : database.initTransaction(innerTransactionOperation);
+};
+exports.domainModelLoad = domainModelLoad;
+exports.domainModelCommit = (0, ramda_1.curry)((logger, eventstore, database, collection, transaction) => async (handlerState) => {
+    const innerTransactionOperation = async (innerTransaction) => {
+        const { params, expectedVersion } = handlerState;
+        const initialValue = handlerState.commandHandler.initialValue();
+        const eventsToCommit = await (0, exports.prepareEventsToCommit)(handlerState);
+        if (eventsToCommit.length === 0) {
+            return handlerState;
+        }
+        // Snapshot-consistency fix: reduce the committed events onto the CURRENT persisted snapshot,
+        // re-read FOR UPDATE inside THIS transaction — NOT handlerState.state (the state loaded, unlocked,
+        // at the START of the command). The row lock is held until this transaction commits, so concurrent
+        // committers on the same aggregate serialize here; a late delta event (e.g. StructureAcked, whose
+        // reducer carries the whole prior state forward) then reduces onto the LATEST committed state and
+        // can never resurrect a nested key (a removed broker) that a concurrent commit dropped. This keeps
+        // the notEventsourced snapshot a faithful, serialized projection of the event log == a full replay.
+        const currentRow = await innerTransaction.getCollection(collection).readById(params.id, { forUpdate: true });
+        const currentState = currentRow ? (0, ramda_1.omit)(['id', 'version'], currentRow) : initialValue;
+        const { state, events } = (0, exports.reduceEventsIntoState)(currentState, handlerState.commandHandler, eventsToCommit);
+        let lastCommittedVersion = 0;
+        if (eventstore._adapter()._adapter().connectionId === database._adapter().connectionId) {
+            const state = await (0, exports.commitEvents)(logger, eventstore)(handlerState, innerTransaction);
+            lastCommittedVersion = state.committedEvents?.at(-1)?.version || 1;
+        }
+        else {
+            /* THE OUTBOX BRANCH HAS ITS OWN AUDIT LOG, AND ITS OWN WAY TO NUMBER IT.
+             *
+             * Nothing is appended to the eventstore here — the events land in `<collection>_outbox`
+             * — so there are no `committedEvents` to read a version off. The version is DERIVED
+             * instead, and it is derived from the one place that keeps it truthful: `currentRow`,
+             * the snapshot re-read FOR UPDATE a few lines above. That read is what the
+             * snapshot-consistency fix documented above rests on, and this reuses it rather than
+             * taking a second, unlocked one. The row lock is held until this transaction commits,
+             * so concurrent committers on the same aggregate serialize HERE, each one reading the
+             * version the previous one wrote and numbering from it. No gaps, no reuse.
+             *
+             * Why `+ events.length` is the same numbering the eventstore would have produced: the
+             * eventstore numbers an append from the stream head, head N -> N+1 … N+k, and the
+             * snapshot is by construction a faithful, serialized projection of that log — version N
+             * means N events precede this commit. Writing k more therefore puts the head at N + k,
+             * which is a POSITION in the audit log and not a counter that merely increases.
+             */
+            const currentVersion = Number(currentRow?.version ?? 0);
+            lastCommittedVersion = currentVersion + events.length;
+            await innerTransaction
+                .getCollection(`${collection}_outbox`)
+                .createMany(events.map((e) => (0, ramda_1.assoc)('id', (0, uuidv7_1.uuidv7)(), e)));
+        }
+        // REPLACE (not merge) the snapshot with the fully-reduced state: it is the COMPLETE aggregate
+        // state, so a merge could only accumulate stale nested keys a reducer dropped (e.g. a removed
+        // broker never leaving `brokers`) — the eventstore_cluster ↔ cluster_infrastructure divergence.
+        if (expectedVersion) {
+            const updated = await innerTransaction.getCollection(collection).updateMany([
+                { field: 'id', op: 'eq', value: params.id },
+                { field: 'version', op: 'eq', value: expectedVersion }
+            ], { ...state, version: lastCommittedVersion }, { replace: true });
+            /* A COMPARE-AND-SET THAT MATCHED NOTHING IS A LOST COMMAND, NOT A SUCCESS.
+             *
+             * `updateMany` reports the rows it wrote, and this write is a CAS —
+             * `WHERE id = … AND version = expectedVersion`. Discarding that result made a failed
+             * assertion indistinguishable from a satisfied one: the caller was told it won, the
+             * audit row had already been written, and the snapshot never moved. Raising here is
+             * what makes the assertion mean something, and it rolls the audit row back with it.
+             *
+             * `ConcurrencyError` specifically, because that is the type the command pipeline knows:
+             * a command that asserted its OWN expectation (`?expectedVersion=`) gets the 409, while
+             * one whose expectation the library derived is re-run against fresh state.
+             */
+            if (!updated.length)
+                throw new pv3_types_1.ConcurrencyError(`Concurrency Error: the ${collection} snapshot for '${params.id}' is no longer at the expected version ${expectedVersion}`, 'SNAPSHOT_EXPECTED_VERSION_MISMATCH');
+        }
+        else {
+            if (state !== null) {
+                await innerTransaction
+                    .getCollection(collection)
+                    .upsert(handlerState.params.id, {
+                    ...state,
+                    version: lastCommittedVersion
+                }, { replace: true });
+            }
+            else {
+                await innerTransaction
+                    .getCollection(collection)
+                    .destroyById(handlerState.params.id);
+            }
+        }
+        return {
+            ...handlerState,
+            state
+        };
+    };
+    return (transaction || handlerState.transaction) ? innerTransactionOperation(transaction || handlerState.transaction) : database.initTransaction(innerTransactionOperation);
+});
+const defaultHandler = (eventsProducedByCommand) => (_1, _2, data) => {
+    return Promise.all((eventsProducedByCommand || []).map((e) => () => ({
+        name: e,
+        data
+    })));
+};
+exports.defaultHandler = defaultHandler;
+const defaultCommit = (logger, eventstore) => (state) => {
+    if (!state.transaction || (state.transaction && eventstore.getConnectionId() === state.transaction?.connectionId)) {
+        return (0, exports.commitEvents)(logger, eventstore)(state, state.transaction);
+    }
+    else {
+        logger.error('Attempting to Transactionally commit events with a transaction belonging to a different database. Dying now');
+        logger.info(state);
+        process.exit(1);
+    }
+};
+exports.defaultCommit = defaultCommit;
+const reduceEventsIntoState = (initialState, commandHandler, events) => {
+    const _state = events.reduce((0, exports.getEventReducers)(commandHandler), { state: initialState });
+    return { events, state: _state.state };
+};
+exports.reduceEventsIntoState = reduceEventsIntoState;
+const formatDomainModelCommandResponse = (handlerState) => {
+    return Promise.resolve({
+        state: handlerState.state
+    });
+};
+exports.formatDomainModelCommandResponse = formatDomainModelCommandResponse;
+const formatEventSourcedCommandResponse = async (handlerState) => {
+    const { commandHandler, state } = handlerState;
+    // Default to [] (not undefined) so an empty-event command still returns an
+    // `events: []` response. Mirrors the snapshot command-template's `format`
+    // (`committedEvents || []`); without this the response shape diverges between
+    // snapshotted and non-snapshotted aggregates (a no-event command returns
+    // `{ state }` with no `events` key here, but `{ events: [], state }` there).
+    const committedEvents = handlerState.committedEvents || [];
+    if (!commandHandler.isAggregate) {
+        return Promise.resolve({ events: committedEvents });
+    }
+    return (0, exports.reduceEventsIntoState)(state, commandHandler, committedEvents);
+};
+exports.formatEventSourcedCommandResponse = formatEventSourcedCommandResponse;
+const validateInvariants = (invariants) => (state) => {
+    return invariants.reduce((success, invariant) => {
+        return success
+            .then((state) => invariant.check(state))
+            .then((resultState) => resultState || state);
+    }, Promise.resolve(state));
+};
+exports.validateInvariants = validateInvariants;
+const checkIdempotency = (idempotencyChecks) => (state) => {
+    return idempotencyChecks.reduce((success, idempotencyCheck) => {
+        return success
+            .then((state) => idempotencyCheck.check(state))
+            .then((resultState) => resultState || state);
+    }, Promise.resolve(state));
+};
+const defaultEventsourcingLoad = (eventstore) => async (handlerState, options, state) => {
+    /* ⚠ THE HEAD READ IS STRICTLY BEFORE THE REDUCE. Do not swap these two statements.
+     *
+     * The command runs inside `initTransaction` (see `executeCommand` below) at READ COMMITTED,
+     * so EVERY STATEMENT GETS ITS OWN SNAPSHOT and a concurrent commit can land between two of
+     * them. Which of the two runs first is therefore the whole correctness of this change:
+     *
+     *   head -> reduce (this order) — head <= what we reduced. An interleaving writer means we
+     *     reduced MORE than the version we assert, the commit's assertion FAILS CLOSED, and the
+     *     command retries against the winner's state. Costs at worst a spurious retry.
+     *     (`head <= reduced` holds while both reads are POOL-EQUIVALENT. The head read below is
+     *     never pool-SCOPED — it passes the transaction on purpose, see the last paragraph — but
+     *     on the default path that transaction is the one `executeCommand` opened for this command
+     *     and it has not written this stream yet, so it answers exactly what a pool read would.
+     *     It does NOT hold inside a caller-owned transaction that has ALREADY appended to THIS
+     *     stream: there the head sees those uncommitted rows and `loadAggregateState`, which
+     *     reduces through the pool, does not. That exposure predates this read — the reduce was
+     *     already pool-scoped and there was no assertion at all — and it cannot produce a conflict,
+     *     since both the head here and the head the append numbers from come from the same
+     *     per-transaction cache. Fixing it means giving the reduce the transaction, its own change.)
+     *   reduce -> head (reversed)   — head >= what we reduced. We would assert version 7 having
+     *     only reduced 1-5, the assertion PASSES, and a decision computed on stale state gets
+     *     committed. That is precisely the lost update this change exists to remove.
+     *
+     * Reversing them produces NO type error and NO other test failure — the tripwire is the
+     * ordering case in `occLoadTimeExpectation.deps.test.ts`.
+     *
+     * The expectation comes from the HEAD, never from the reduce: the reduce is filtered by
+     * event name at the SQL level (`getNonNoopEventNames`) and yields only `{ state }`, so the
+     * greatest version among the events it saw sits permanently behind the head on any stream
+     * carrying a `ReducerNOOP` event or another writer's event. Sourcing it there would make
+     * every command on such a stream conflict, burn its whole retry budget and fail forever.
+     *
+     * And the transaction is passed on purpose: inside a caller-owned transaction that has
+     * already appended to this stream, a pool read would miss those uncommitted appends, assert
+     * a head the commit can never agree with, and retry to exhaustion.
+     */
+    /* The command's declared mode, spelled out as the three things the append can be told. This is
+     * the whole of the dispatch — the adapters already branch on exactly these values:
+     *
+     *   optimistic  — the head read below: assert it, and conflict when it moved.
+     *   rebase      — `undefined`: the append reads the head itself and numbers from it, asserting
+     *                 NOTHING. Per-stream order survives; conflict DETECTION does not. The head read
+     *                 is skipped rather than taken and discarded, so a mode that asserts nothing
+     *                 also costs nothing.
+     *   unversioned — `null`: every event is written version-free. Unreachable for an aggregate
+     *                 (`resolveConcurrencyMode` refuses it) and reachable here only for a
+     *                 non-aggregate that borrowed this load through a custom template, which is
+     *                 already what the non-aggregate load gives it.
+     */
+    const concurrency = resolveConcurrencyMode(handlerState.commandHandler, handlerState.command);
+    const expectedVersion = handlerState.expectedVersion !== undefined
+        // An expectation SUPPLIED by the caller is never overwritten — the test is "was one
+        // supplied at all", not "was it exactly null". `null` means "version-free stream", and a
+        // custom load may have built a per-stream map; a null-only carve-out would clobber both.
+        ? handlerState.expectedVersion
+        : concurrency === 'rebase'
+            ? undefined
+            : concurrency === 'unversioned'
+                ? null
+                : await eventstore.getStreamVersion(handlerState.stream, handlerState.transaction);
+    const reducedState = await (0, exports.loadAggregateState)(eventstore)(handlerState.commandHandler, handlerState.stream, options, state ||
+        handlerState.state ||
+        handlerState.commandHandler.initialValue());
+    return {
+        ...handlerState,
+        expectedVersion,
+        state: reducedState?.state
+    };
+};
+exports.defaultEventsourcingLoad = defaultEventsourcingLoad;
+const handleCommand = (handler) => async (handlerState) => {
+    const { state, data } = handlerState;
+    handlerState.events = await Promise.resolve()
+        .then(() => handler((0, utils_1.createEvent)(handlerState.commandHandler), state ? (0, ramda_1.clone)(state) : null, (0, ramda_1.clone)(data), handlerState))
+        .then((events) => {
+        return [...handlerState.events, ...events];
+    });
+    return handlerState;
+};
+exports.handleCommand = handleCommand;
+const createCommandHandlers = (logger, endpoint, eventstore, metadataSchema, formatMetadataFromContext = () => ({}), instrumentCommandExecution) => {
+    const internalExecuteCommand = (commandHandler, commandName, transaction) => async (actionParams) => {
+        const command = commandHandler.commands[commandName]
+            .build
+            ? commandHandler.commands[commandName].build()
+            : commandHandler.commands[commandName];
+        command.name = commandName;
+        const start = Date.now();
+        logger.log('Processing Command', commandName, 'in', commandHandler.isAggregate ? 'Aggregate' : 'External System', commandHandler.name);
+        const alsContext = (0, executionContext_1.getExecutionContext)();
+        const { body, params, query, context: explicitContext } = actionParams;
+        // Merge: explicit params > ALS > defaults
+        const context = (explicitContext?.user
+            ? explicitContext
+            : alsContext
+                ? { ...explicitContext, user: { id: alsContext.userId, accountId: alsContext.accountId, impersonatedBy: alsContext.impersonatedBy } }
+                : explicitContext);
+        const id = command.dataPropertyId
+            ? (0, utils_2.existsPath)(command.dataPropertyId.split('.'), body)
+            : params?.id;
+        if ((commandHandler.isStreamable || commandHandler.isAggregate) && !id) {
+            throw Error(`Command requires an id to be executed for commandHandler ${commandHandler.name} and command ${command.name}`);
+        }
+        // Non-streamable, non-aggregate systems with no supplied id emit null-version,
+        // order-free events. Fan them out by varying the stream id with a random bounded
+        // token (affects ONLY `stream`; `id` stays untouched for downstream use).
+        const streamId = (!id && !command.dataPropertyId && !commandHandler.isAggregate && !commandHandler.isStreamable)
+            ? (0, utils_2.randomStreamSuffix)()
+            : id;
+        const stream = (0, utils_2.formatStream)(commandHandler.name, streamId);
+        const mergedQuery = query || {};
+        const correlationId = mergedQuery.correlationId || alsContext?.correlationId;
+        const causationId = mergedQuery.causationId || alsContext?.causationId;
+        const handlerState = {
+            command,
+            data: body,
+            query,
+            params,
+            context,
+            stream,
+            events: [],
+            commandHandler,
+            expectedVersion: query?.expectedVersion,
+            state: undefined,
+            metadata: {
+                // Ambient execution TAGS ride NESTED under `metadata.tags`, never spread, so a
+                // tag can never collide with (or forge) a reserved metadata key. Written FIRST
+                // so the reserved keys below always win even if a host's
+                // `formatMetadataFromContext` were to emit its own `tags`.
+                ...(alsContext?.tags ? { tags: alsContext.tags } : {}),
+                correlationId: correlationId || getActiveTraceId() || (0, uuidv7_1.uuidv7)(),
+                causationId,
+                ...formatMetadataFromContext(context || {})
+            },
+            transaction
+        };
+        const loadFunction = command.load ||
+            (!commandHandler.isAggregate
+                ? (state) => ({ ...state, expectedVersion: null })
+                : commandHandler.isEventsourced
+                    ? (0, exports.defaultEventsourcingLoad)(eventstore)
+                    : (0, exports.domainModelLoad)(commandHandler.outboxDatabase, commandHandler.outboxCollection));
+        const commitFunction = command.commit ||
+            (commandHandler.isEventsourced
+                ? (0, exports.defaultCommit)(logger, eventstore)
+                : (0, exports.domainModelCommit)(logger, eventstore, commandHandler.outboxDatabase, commandHandler.outboxCollection, undefined));
+        const formatFunction = command.format ||
+            (commandHandler.isEventsourced
+                ? exports.formatEventSourcedCommandResponse
+                : exports.formatDomainModelCommandResponse);
+        const executePreProcessing = (state) => {
+            if (!command.preProcessing) {
+                return Promise.resolve(state);
+            }
+            return Promise.resolve(command.preProcessing(state))
+                .then((newData) => ({
+                ...state,
+                data: newData
+            }));
+        };
+        const executePipeline = () => Promise.resolve(handlerState)
+            .then(loadFunction)
+            .then(executePreProcessing)
+            .then(checkIdempotency(command.idempotencyChecks || []))
+            .then((0, exports.validateInvariants)(command.invariants || []))
+            .then((0, exports.handleCommand)(command.handler || (0, exports.defaultHandler)(command.events)))
+            .then(commitFunction)
+            .catch((err) => {
+            if (err.ignore === '--IdempotencyCheck--') {
+                // Pure side effect at the skip site — `add` is no-throw; control flow is
+                // unchanged (still resolve with `err.handlerState`). Low-cardinality labels:
+                // command + aggregate names only (never ids).
+                getIdempotencySkipCounter()?.add(1, { command: commandName, aggregate: commandHandler.name });
+                return err.handlerState;
+            }
+            return Promise.reject(err);
+        })
+            .then(formatFunction)
+            .then((result) => {
+            logger.log('Command', commandName, ' Processed in', ((Date.now() - start) / 1000).toFixed(2), 's');
+            return result;
+        });
+        return instrumentCommandExecution
+            ? instrumentCommandExecution({
+                commandName: commandName,
+                aggregateName: commandHandler.name,
+                stream,
+                isAggregate: !!commandHandler.isAggregate,
+                correlationId: handlerState.metadata?.correlationId,
+                causationId: handlerState.metadata?.causationId,
+                payload: handlerState.data
+            }, executePipeline)
+            : executePipeline();
+    };
+    const executeCommand = (commandHandler, commandName, transaction, schemas, retryAttempts = 0, occSavepoint) => async (actionParams) => {
+        const command = commandHandler.commands[commandName]
+            .build
+            ? commandHandler.commands[commandName].build()
+            : commandHandler.commands[commandName];
+        schemas = schemas || getCommandSchemas(commandHandler, command);
+        command.name = commandName;
+        // Resolved BEFORE anything is opened or executed, so a command declaring the one illegal
+        // combination (`unversioned` on an aggregate) fails at the door instead of half-way
+        // through a transaction it already wrote to.
+        const concurrency = resolveConcurrencyMode(commandHandler, command);
+        const innerTransactionOperation = async (transaction) => {
+            return Promise.resolve(actionParams)
+                .then((0, validation_1.validateEndpoint)(validation_1.validateSchema, schemas, true))
+                .then(internalExecuteCommand(commandHandler, commandName, transaction));
+        };
+        /* ── THE REWIND POINT, TAKEN ONCE, BEFORE THE FIRST ATTEMPT ──────────────────────────
+         *
+         * Only for a transaction the CALLER owns. When we open the transaction ourselves (below)
+         * a failed attempt is discarded wholesale by `initTransaction`'s rollback, and the retry
+         * starts a brand-new one — there is nothing to rewind.
+         *
+         * ESTABLISHED EXACTLY ONCE, AT `retryAttempts === 0`, and carried through the retries.
+         * `occSavepoint` is that carried token; it is set only by the recursive call, which is
+         * why it doubles as "an attempt already took one".
+         *
+         * The reason is ECONOMY, not correctness — be precise about this, because the obvious
+         * story is wrong. A per-attempt savepoint would NOT rewind less: the rollback below runs
+         * strictly BEFORE the recursive call, so each new savepoint would be taken against an
+         * already-clean state and would behave identically on the data. What it would cost is one
+         * extra round trip AND one extra Postgres SUBTRANSACTION per attempt. Subtransactions are
+         * the scarce thing: a top-level transaction keeps every subtransaction XID it ever
+         * assigned in its `PGPROC` list for its whole life — `RELEASE SAVEPOINT` ends the nesting
+         * but does NOT give the XID back — and past `PGPROC_MAX_CACHED_SUBXIDS` (64) its snapshot
+         * goes suboverflowed, pushing every other backend's visibility checks into the
+         * `pg_subtrans` SLRU. One caller-owned transaction that runs many commands (item merge's
+         * nested loops) is already close to that ceiling at one savepoint per COMMAND; one per
+         * ATTEMPT would multiply it by the retry budget exactly when contention is highest.
+         *
+         * AND ONLY FOR AN `optimistic` COMMAND. That is the only mode that can lose a conflict it
+         * did not cause — it asserts a head it read, so another writer's commit invalidates it and
+         * the retry needs a clean state to resume from. `rebase` asserts nothing and `unversioned`
+         * writes version-free rows the unique index cannot catch, so neither has a conflict a
+         * rewind would help with; a subtransaction spent on them buys nothing. The consequence is
+         * deliberate and is the same rule slice 3 set: no rewind means NO RETRY inside a
+         * caller-owned transaction, so a `rebase` command that does hit a genuine INSERT collision
+         * there propagates to the transaction's owner instead of re-executing on top of its own
+         * unrewound rows. On the pooled path — where `rebase`'s retry actually lives — nothing
+         * changes.
+         *
+         * WHAT THIS GATE DOES NOT DO, since `optimistic` is the DEFAULT: it excludes only commands
+         * that explicitly declare `rebase`/`unversioned` and non-aggregate External Systems. It
+         * does NOT bound the subtransaction accumulation described above for a caller-owned
+         * transaction that issues many DEFAULT commands (teselly's `itemMerge.endpoints.ts` opens
+         * one transaction and runs commands inside five data-driven nested loops) — that
+         * transaction still passes `PGPROC_MAX_CACHED_SUBXIDS` and still goes suboverflowed. That
+         * remains a carried risk of running many commands on one transaction, not something this
+         * narrowing solves.
+         *
+         * Nor does it exclude an aggregate command with a CUSTOM `load` — `multiStream` above all.
+         * Such a command never runs `defaultEventsourcingLoad`, so it derives no expectation from
+         * the mode, yet it declares nothing and therefore resolves to `optimistic` and spends a
+         * savepoint here. That is the one population where the resolved mode is not a literal
+         * description of what its append asserts, and it is not a rounding error: every
+         * `multiStream(…)` command in the known host is in it, and they are precisely the commands
+         * run inside caller-owned transactions. Left as-is deliberately — their per-stream
+         * expectation map DOES carry real expectations, so a rewind is not obviously wasted, and
+         * narrowing this further is a behavior change with no oracle behind it.
+         */
+        const rewindable = transaction && concurrency === 'optimistic' && canSavepoint(transaction) ? transaction : undefined;
+        const savepoint = occSavepoint ?? (rewindable ? await rewindable.savepoint() : undefined);
+        const establishedHere = !!savepoint && !occSavepoint;
+        const executionPromise = transaction ? innerTransactionOperation(transaction) : eventstore._adapter().initTransaction?.(innerTransactionOperation) || innerTransactionOperation();
+        const attempt = executionPromise.catch(async (err) => {
+            if (err instanceof pv3_types_1.ValidationError) {
+                logger.error('Validation Error executing command', commandName, 'in', commandHandler.name, err);
+            }
+            /* ── ONLY THE LIBRARY'S OWN EXPECTATION IS THE LIBRARY'S TO RETRY ───────────────────
+             *
+             * `!= null` — a NULL/UNDEFINED comparison, deliberately not a falsy one. `0` is a real
+             * expectation ("this stream must be EMPTY"), and a falsy test read it as "the caller
+             * supplied nothing", so a caller pinning 0 was retried into a stream that already had
+             * events in it — against an expectation that, unlike a derived one, can never become
+             * true on a later attempt. It burned the whole budget and then failed anyway.
+             *
+             * And it keys on the CALLER-SUPPLIED `query`, never on `handlerState.expectedVersion`,
+             * which slice 2 now fills in for every optimistic command — keying on the derived one
+             * would make retry unreachable for the entire default path. The split is the semantics:
+             * an expectation the library DERIVED from the head it just read is a race it can
+             * resolve by re-reading, so it retries; an expectation the caller PINNED encodes a
+             * decision the caller made about a specific version, so re-running the handler against
+             * a different version would answer a question nobody asked. That one propagates. */
+            const isOccRetryable = err.type === 'ConcurrencyError' && actionParams.query?.expectedVersion == null;
+            // The generic "gave up" line, kept for the tail case it still covers: `retryAttempts`
+            // only ever advances on a ConcurrencyError, so reaching the ceiling with some OTHER
+            // error means the final attempt failed for a different reason. When it IS an OCC
+            // exhaustion the dedicated line below says strictly more, so this one stands down —
+            // one failure, one error log.
+            if (retryAttempts >= OCC_RETRY_CEILING && !isOccRetryable) {
+                logger.error('Command', commandName, 'in', commandHandler.name, `failed after ${OCC_RETRY_CEILING} retries`, err);
+            }
+            if (isOccRetryable) {
+                // Bounded labels — see the instrument block at the top of this file for why the
+                // contended stream is logged rather than labelled.
+                const occLabels = { command: commandName, aggregate: commandHandler.name };
+                if (retryAttempts < OCC_RETRY_CEILING && transaction && !rewindable) {
+                    /* ── A TRANSACTION WE CANNOT REWIND IS NOT RETRIED ─────────────────────────
+                     *
+                     * The transaction is the CALLER's and it is still open, holding whatever this
+                     * attempt already wrote through it (the append that lost is not necessarily the
+                     * only thing the command did). Re-executing here would run the whole command a
+                     * second time ON TOP OF those uncommitted rows: the load would read them back as
+                     * if they were somebody's committed history, and the append would number itself
+                     * from work that the caller may be about to roll away.
+                     *
+                     * So the conflict goes to the caller, who OWNS the transaction and is the only
+                     * party that can end it. Deliberately BEFORE the instruments below: this is not a
+                     * retry and must not be counted as one. The absence of the capability can never
+                     * silently become an unsafe retry — that is the whole point of detecting it.
+                     *
+                     * TWO ways to land here, and the log says which: the transaction cannot savepoint at
+                     * all (MemoryDb, Mongo), or no rewind point was taken because this command is not
+                     * `optimistic` (the gate above). Same refusal, same reason — nothing can rewind this
+                     * attempt's partial rows — but they are diagnosed differently, so they are named.
+                     *
+                     * "RESOLVES TO", not "declares": the mode may be the command's own declaration or the
+                     * one `resolveConcurrencyMode` assigns it, and a non-aggregate External System reads
+                     * as `unversioned` having declared nothing at all. Saying "declares" would send the
+                     * reader looking for a declaration that is not in the source. */
+                    const noRewindReason = canSavepoint(transaction)
+                        ? `the command resolves to concurrency: '${concurrency}', so no rewind point was taken`
+                        : 'the caller-supplied transaction cannot SAVEPOINT';
+                    logger.error('Command', commandName, 'in', commandHandler.name, 'lost an optimistic-concurrency check on stream', err.details?.stream, `— NOT retried: ${noRewindReason}, so a retry would re-execute on top of this attempt's own uncommitted rows. Propagating to the transaction's owner`, err);
+                }
+                else if (retryAttempts < OCC_RETRY_CEILING) {
+                    /* ── BACKOFF ONLY WHEN WE OWN THE TRANSACTION ──────────────────────────────
+                     *
+                     * A caller-supplied `transaction` is still OPEN here: the rejection came from
+                     * `innerTransactionOperation( transaction )` above, which — unlike the pooled
+                     * path — does not commit-or-rollback-and-release before rejecting. The
+                     * transaction is the caller's to end, so its BEGIN is live, and under PgBouncer
+                     * TRANSACTION POOLING an open transaction PINS one server backend out of a
+                     * small pool (`default_pool_size`). Sleeping there would pin a scarce backend
+                     * while doing nothing at all, and the callers that take this path are exactly
+                     * the fan-out ones — bulk item/stock writes, item merge, publication batch
+                     * editing — where several such commands run concurrently. That converts a
+                     * herd-breaking measure into a pool-exhaustion one.
+                     *
+                     * Nothing is lost by not sleeping: the caller-owned path now REWINDS below, so it
+                     * re-executes from the state its first attempt began with rather than on top of
+                     * its own partial rows.
+                     *
+                     * Recorded as `0` rather than skipped, so "how much of this command's latency
+                     * was backoff" stays answerable — and so the two paths are distinguishable in
+                     * the histogram instead of one of them silently vanishing from it. */
+                    const backoffMs = transaction ? 0 : occBackoffMs(retryAttempts);
+                    // Pure side effects — both instruments are no-throw, so control flow below is
+                    // exactly what it was before.
+                    getOccInstruments()?.retry.add(1, occLabels);
+                    getOccInstruments()?.backoff.record(backoffMs, occLabels);
+                    logger.debug('Retrying command', commandName, 'in', commandHandler.name, 'due to ConcurrencyError on stream', err.details?.stream, `— attempt ${retryAttempts + 1}/${OCC_RETRY_CEILING} after ${backoffMs}ms`, transaction ? 'with transaction' : 'without transaction');
+                    // De-synchronize the losers before they collide again on the same tick.
+                    if (backoffMs)
+                        await new Promise((resolve) => setTimeout(resolve, backoffMs));
+                    if (rewindable && savepoint) {
+                        // Discard everything this attempt wrote through the caller's transaction, back to
+                        // the point the FIRST attempt started from. The transaction survives it: the
+                        // conflict was raised by us, not by Postgres — the statement completed (that is
+                        // what `ON CONFLICT` buys) — so this is a healthy transaction, not an aborted one.
+                        await rewindable.rollbackToSavepoint(savepoint);
+                        // IMMEDIATELY after the rollback, and the ordering is the point: an eventstore may
+                        // cache per-transaction state that was only true while those rows existed
+                        // (`PostgresEventstore` caches the head version of every stream the transaction
+                        // appended to). Left in place it would go on claiming rows the rollback deleted,
+                        // and the next append would number itself from a version that no longer exists —
+                        // a permanent gap, silently, on a run that otherwise looks green.
+                        eventstore.forgetTransactionState?.(rewindable);
+                    }
+                    return executeCommand(commandHandler, commandName, transaction, schemas, retryAttempts + 1, savepoint)(actionParams);
+                }
+                else {
+                    // The budget is spent and NOTHING was committed. This is the alertable event: the
+                    // caller's intent — an order's stock decrement, a ledger posting — did not happen.
+                    getOccInstruments()?.exhausted.add(1, occLabels);
+                    logger.error('Command', commandName, 'in', commandHandler.name, `EXHAUSTED ${OCC_RETRY_CEILING} optimistic-concurrency retries on stream`, err.details?.stream, '— nothing was committed', err);
+                }
+            }
+            if (command.onErrorHandler)
+                return command.onErrorHandler(err, actionParams.body);
+            return Promise.reject(err);
+        });
+        if (!establishedHere || !rewindable || !savepoint)
+            return attempt;
+        const result = await attempt;
+        /* Release only the savepoint this call ESTABLISHED, and only once the whole retry chain
+         * has SUCCEEDED. Releasing merges the subtransaction into its parent and frees its
+         * resource owner — it undoes nothing, and it keeps the nesting flat so a later
+         * `ROLLBACK TO` cannot land on a stale inner point.
+         *
+         * It does NOT stop subtransactions from accumulating, and must not be read as if it did:
+         * the released subtransaction's XID stays in the top-level transaction's `PGPROC` subxid
+         * list until that transaction ends, so a caller-owned transaction issuing more than
+         * `PGPROC_MAX_CACHED_SUBXIDS` (64) commands still goes suboverflowed. That is a CARRIED
+         * RISK of running many commands on one transaction (`itemMerge.endpoints.ts`), recorded
+         * as such — releasing is hygiene, not a cure.
+         *
+         * Not released on the failure path on purpose: the transaction may be aborted by then, and
+         * `RELEASE SAVEPOINT` would throw and MASK the caller's real error. Postgres discards every
+         * savepoint when the transaction ends, so the only cost of skipping it is the memory of a
+         * transaction that is about to end anyway.
+         *
+         * A failure to release does NOT fail a command that already committed its events: the
+         * caller would see an error for work that actually happened and could reasonably re-issue
+         * it, duplicating the events. One leaked savepoint on a transaction its owner is about to
+         * end is the cheaper of the two. */
+        try {
+            await rewindable.releaseSavepoint(savepoint);
+        }
+        catch (releaseError) {
+            logger.warn('Command', commandName, 'in', commandHandler.name, 'could not release its optimistic-concurrency savepoint; the command itself succeeded', releaseError);
+        }
+        return result;
+    };
+    const getCommandSchemas = (commandHandler, command, name) => {
+        const eventsSchemas = command.events?.reduce((schemas, eventName) => {
+            if (!!commandHandler.events[eventName])
+                schemas[eventName] = commandHandler.events[eventName]().schema || jsonschema_definer_1.default.null();
+            if (schemas[eventName])
+                schemas[eventName] = schemas[eventName].id(eventName);
+            return schemas;
+        }, {});
+        const responses = !eventsSchemas || Object.keys(eventsSchemas).length === 0
+            ? {
+                200: [{
+                        schema: jsonschema_definer_1.default.shape({
+                            state: commandHandler.schema.id(`${commandHandler.name}State`)
+                        }),
+                        name: 'OK'
+                    }]
+            }
+            : {
+                200: [{
+                        schema: commandHandler.isAggregate
+                            ? jsonschema_definer_1.default.shape({
+                                state: commandHandler.schema.id(`${commandHandler.name}State`),
+                                events: (0, pv3_types_1.CommittedEventSchema)(jsonschema_definer_1.default.anyOf(...Object.values(eventsSchemas)), Object.keys(eventsSchemas))
+                            })
+                            : jsonschema_definer_1.default.shape({
+                                events: (0, pv3_types_1.CommittedEventSchema)(jsonschema_definer_1.default.anyOf(...Object.values(eventsSchemas)), Object.keys(eventsSchemas))
+                            }),
+                        name: 'OK'
+                    }]
+            };
+        command.schema.id(command.name || name);
+        const query = pv3_types_1.CommandEndpointQuerySchema;
+        return {
+            query,
+            body: command.schema,
+            responses,
+            // If it has dataPropertyId, it is a multiStream command, so it does not need params
+            ...(commandHandler.isStreamable && !command.dataPropertyId
+                ? { params: pv3_types_1.SystemEndpointParamsSchema }
+                : {})
+        };
+    };
+    const registerCommandHandlerGetEndpoints = (commandHandler, name = commandHandler.name) => {
+        const isStreamable = !!commandHandler.eventReducers ||
+            commandHandler.isStreamable;
+        const [streamRoute, idRoute] = (0, utils_1.getCommandHandlerGetRoutes)(isStreamable ? 'aggregate' : 'system', commandHandler);
+        if (!commandHandler.isEventsourced && !commandHandler.outboxDatabase)
+            throw Error('Aggregate declared as Not Eventsourced without Outbox database.');
+        isStreamable &&
+            endpoint.registerEndpoint({
+                name: `Get ${name} state by Id`,
+                description: `Get current reduced ${name} state by Id`,
+                method: 'GET',
+                loggingModule: (0, change_case_1.paramCase)(name),
+                subdomain: commandHandler.subdomain,
+                artifact: {
+                    type: commandHandler.isAggregate ? 'aggregate' : 'externalSystem',
+                    name: commandHandler.name
+                },
+                route: idRoute,
+                tags: [],
+                schemas: {
+                    params: pv3_types_1.SystemEndpointParamsSchema,
+                    query: pv3_types_1.SystemGetQuerySchema
+                },
+                action: ({ params, query }) => (0, exports.loadAggregateState)(eventstore)(commandHandler, (0, utils_2.formatStream)(commandHandler.name, params?.id), (0, exports.formatAggregateGetQueryParams)(query)).then((response) => response && Object.values(response)[0])
+            });
+        endpoint.registerEndpoint({
+            name: (0, utils_1.formatRouteForCommandHandler)(name, change_case_1.pascalCase),
+            description: `Get the stream of events for ${name} by Id`,
+            method: 'GET',
+            loggingModule: (0, change_case_1.paramCase)(name),
+            subdomain: commandHandler.subdomain,
+            artifact: {
+                type: commandHandler.isAggregate ? 'aggregate' : 'externalSystem',
+                name: commandHandler.name
+            },
+            tags: commandHandler.isAggregate ? ['aggregate'] : ['system'],
+            route: streamRoute,
+            schemas: {
+                params: isStreamable ? pv3_types_1.SystemEndpointParamsSchema : undefined,
+                query: pv3_types_1.SystemGetQuerySchema
+            },
+            action: ({ params, query }) => (isStreamable
+                ? (0, exports.loadStream)(eventstore)((0, utils_2.formatStream)(commandHandler.name, params?.id), query)
+                : (0, exports.loadStream)(eventstore)(name, (0, exports.formatAggregateGetQueryParams)(query))).then((response) => (Array.isArray(response) ? response : []))
+        });
+        return [idRoute, streamRoute];
+    };
+    const registerCommandHandlerPostEndpoints = (commandHandler) => {
+        const commandHandlerName = commandHandler.name;
+        return !commandHandler.commands
+            ? {}
+            : (0, bett3r_utils_1.reduce)((result, name) => {
+                const command = commandHandler.commands[name]?.build
+                    ? commandHandler.commands[name]?.build()
+                    : commandHandler.commands[name];
+                const isStreamable = commandHandler.isStreamable && !command.dataPropertyId;
+                const route = (0, utils_1.getCommandPostRoute)(isStreamable ? 'aggregate' : 'system', commandHandler, name);
+                const schemas = getCommandSchemas(commandHandler, command, name);
+                endpoint.registerEndpoint({
+                    loggingModule: (0, change_case_1.paramCase)(commandHandlerName),
+                    subdomain: commandHandler.subdomain,
+                    artifact: {
+                        type: commandHandler.isAggregate ? 'aggregate' : 'externalSystem',
+                        name: commandHandler.name
+                    },
+                    name: (0, utils_1.formatRouteForCommandHandler)(name, change_case_1.pascalCase),
+                    description: command.description,
+                    route,
+                    tags: [],
+                    schemas,
+                    ...(command.visibility ? { visibility: command.visibility } : {}),
+                    // It is not validated because the command handler will validate it as part of the command handling process. That way the error can be handled by the command handler.
+                    shouldValidate: false,
+                    method: 'POST',
+                    action: executeCommand(commandHandler, name, undefined, schemas)
+                });
+                result[name] = route;
+                return result;
+            }, {}, Object.keys(commandHandler.commands));
+    };
+    return {
+        loadStream: (0, exports.loadStream)(eventstore),
+        loadAggregateState: (0, exports.loadAggregateState)(eventstore),
+        executeCommand,
+        registerCommandHandlerGetEndpoints,
+        registerCommandHandlerPostEndpoints
+    };
+};
+exports.createCommandHandlers = createCommandHandlers;
+//# sourceMappingURL=index.js.map