@crowdsource.you/core 1.2.0

package/dist/outbox/intake.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuplicateReportError = void 0;
+exports.createIntake = createIntake;
+const service_js_1 = require("./outbox/service.js");
+/**
+ * Storing a report and, when there is somewhere to send it, the promise to
+ * deliver it — in one operation.
+ *
+ * This is the only thing in the integration that a user waits for. A 201 from an
+ * application's report route means the report row and its outbox event committed
+ * together. It does NOT mean CrowdSource accepted anything — CrowdSource may be
+ * unreachable, mid-deploy or not yet configured, and the reporter is told their
+ * report was received either way, because it was.
+ *
+ * The transaction is the whole mechanism. Two writes outside one would give two
+ * failure modes that are both silent: a report with no delivery event (the
+ * report exists, nothing will ever send it, and nobody finds out until somebody
+ * asks why a case never opened) or a delivery event with no report (a delivery
+ * worker looking up an id that was rolled back). Neither surfaces as an error at
+ * the moment it happens, which is exactly why this has to be atomic rather than
+ * carefully ordered.
+ *
+ * The one report with NO delivery event is the one whose type has no subject
+ * provider, and that is a different claim entirely: not "delivery failed" but
+ * "there was never a route out of this application for this kind of object".
+ * Those two must not be conflated, which is why they are different `localStatus`
+ * values and why the absent route is written down as a reason rather than
+ * inferred from a missing row.
+ */
+class DuplicateReportError extends Error {
+    constructor(existing) {
+        super('This item has already been reported by this reporter.');
+        this.name = 'DuplicateReportError';
+        this.existing = existing;
+    }
+}
+exports.DuplicateReportError = DuplicateReportError;
+/**
+ * Refuses an identifier that is not a string, before it reaches the store.
+ *
+ * The input type says these are strings, but a type is erased at runtime and a
+ * truthiness check passes anything non-empty — including an object. What that
+ * costs depends on the backend, and the difference is worth stating rather than
+ * flattening: on Mongo a `{ $ne: null }` becomes a query OPERATOR, so the
+ * duplicate lookup matches an UNRELATED report and answers "you already reported
+ * this" about somebody else's row; on Postgres a bound parameter cannot become
+ * an operator, so that particular failure class does not exist there.
+ *
+ * The guard is not Mongo's, though. A non-string still reaches the insert and
+ * stores something that is not an id where an id belongs, on any backend — and
+ * the check lives here rather than at an application's route because this
+ * function is exported: a queue worker, a reconciliation script or a future
+ * admin path is under no obligation to have passed a route's validation, and a
+ * guard that only exists at one caller is a guard that holds until the second
+ * one arrives.
+ */
+function requireIdentifier(value, field) {
+    /**
+     * `trim()` and not `length === 0`, because `'   '` is not an identifier.
+     *
+     * A whitespace-only reporter or reported id is not a string somebody meant:
+     * it comes from a form field, a trimmed-elsewhere value, or a client that
+     * sends `' '` for absent. Stored, it is an id that matches nothing and reads
+     * as present — the duplicate check finds no earlier report, the delivery
+     * carries it as `externalReportId`, and nothing fails until a human asks why
+     * a case names nobody.
+     */
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new TypeError(`createReport: ${field} must be a non-empty string.`);
+    }
+    return value;
+}
+/**
+ * Why a report is not going anywhere, in words an operator can read.
+ *
+ * Stored on the row rather than left to be inferred from a missing outbox event.
+ * A missing row is also what a lost write looks like, and the two need to be
+ * distinguishable months later without re-deriving which types had providers at
+ * the time. Bounded by the schema's 300-character limit.
+ */
+function localOnlyReason(reportedType) {
+    return (`There is no moderation subject provider for '${reportedType}', so this report is ` +
+        'recorded locally and is not sent for community review.');
+}
+/**
+ * Store the report, and queue its delivery in the same transaction.
+ *
+ * Delivery is queued when — and only when — the reported type has a subject
+ * provider. A type without one is stored at `received` with the reason recorded,
+ * which is the behaviour the application had before CrowdSource existed: the
+ * report is a receipt and a local record, and nothing else ever happens to it.
+ *
+ * That branch is the reason the two writes stay in one transaction rather than
+ * being ordered carefully. The condition is read BEFORE the transaction body
+ * decides anything, so `localStatus` and the presence of an outbox row are
+ * decided together from one fact — a report can never commit as `queued` with
+ * nothing to deliver it, nor as `received` with a delivery event that will try
+ * anyway.
+ *
+ * Intake deliberately does not read whether the integration is enabled. A report
+ * taken while it is off still gets its delivery event, so turning the flag on
+ * delivers the backlog instead of stranding it — the dispatcher is what is
+ * gated, not the durable record. Nothing here is conditional on a third party's
+ * state; only on whether this application knows how to describe the object at
+ * all.
+ */
+function createIntake(input) {
+    return async (report) => {
+        const reporter = requireIdentifier(report.reporter, 'reporter');
+        const reportedId = requireIdentifier(report.reportedId, 'reportedId');
+        const reportedType = requireIdentifier(report.reportedType, 'reportedType');
+        if (!Array.isArray(report.categories) || report.categories.length === 0) {
+            throw new TypeError('createReport: categories must be a non-empty array.');
+        }
+        for (const category of report.categories) {
+            requireIdentifier(category, 'categories[]');
+        }
+        const deliverable = input.registry.providerFor(reportedType) !== undefined;
+        return await input.transaction.run(async (tx) => {
+            const existing = await input.reports.findDuplicate({ reporter, reportedId, reportedType }, tx);
+            if (existing)
+                throw new DuplicateReportError(existing);
+            const created = await input.reports.insert({
+                reportedType,
+                reportedId,
+                reporter,
+                categories: [...report.categories],
+                ...(report.details === undefined ? {} : { details: report.details }),
+                localStatus: deliverable ? 'queued' : 'received',
+                ...(deliverable ? {} : { localStatusReason: localOnlyReason(reportedType) }),
+                ...(report.extra === undefined ? {} : { extra: report.extra }),
+            }, tx);
+            if (!deliverable)
+                return { report: created };
+            const outboxEventId = await input.outbox.enqueue({
+                eventId: (0, service_js_1.reportSubmitEventId)(created.id),
+                kind: 'report.submit',
+                payload: { reportId: created.id },
+            }, tx);
+            return { report: created, outboxEventId };
+        });
+    };
+}
+//# sourceMappingURL=intake.js.map

package/dist/outbox/intake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intake.js","sourceRoot":"","sources":["../../src/outbox/intake.ts"],"names":[],"mappings":"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"}

package/dist/outbox/integration.d.ts

@@ -0,0 +1,62 @@
+import type { Router } from 'express';
+import { type CrowdSourceClientProvider } from './client.js';
+import { type EnforcementExecutor } from './enforcement/executor.js';
+import { type SubjectRegistry } from './evidence.js';
+import { ModerationOutboxDispatcher } from './outbox/dispatcher.js';
+import { ModerationReconciliationJob, type ReconcileModerationReports } from './reconciliation.js';
+import type { CreateReportInput, CreateReportResult, ModerationIntegrationConfig, ModerationReportFields } from './types.js';
+/**
+ * Everything wired together, from one object.
+ *
+ * A factory rather than a set of module-level singletons, and that is not
+ * stylistic: a module-level client, dispatcher or registry cannot be built
+ * twice, which makes two integrations in one test process impossible and makes
+ * test isolation depend on module-registry surgery. The store is built OUTSIDE
+ * and passed in, so the same wiring serves either backend and neither is
+ * reachable from here.
+ *
+ * `TTx` is deliberately absent from the returned interface. It is inferred from
+ * the config's store, used only inside this factory, and never surfaces — so a
+ * caller holding a `ModerationIntegration` cannot tell which backend built it,
+ * which is what lets one test suite run against both.
+ */
+export interface ModerationIntegration<TReport extends ModerationReportFields, TAction extends string> {
+    /**
+     * Store a report and, when there is somewhere to send it, the promise to
+     * deliver it — in ONE transaction.
+     *
+     * Throws `DuplicateReportError` when this reporter already reported this
+     * object, and `TypeError` for an identifier that is not a non-empty string.
+     */
+    createReport(input: CreateReportInput): Promise<CreateReportResult<TReport>>;
+    /**
+     * The webhook receiver. **Mount this BEFORE `express.json()`** — the signature
+     * covers the bytes that arrived, and a parser destroys them.
+     *
+     * Returns an empty router when no webhook secret is configured: an
+     * unconfigured deployment 404s, which is indistinguishable from not having the
+     * feature.
+     */
+    webhookRouter(options?: {
+        path?: string;
+    }): Router;
+    /**
+     * The outbox loop. Safe on every task — every event is claimed under a lease
+     * with an owner check, so N tasks share the work.
+     */
+    readonly dispatcher: ModerationOutboxDispatcher;
+    /**
+     * The reconciliation sweep on a timer. Start it from a LEADER-elected
+     * scheduler only.
+     */
+    readonly reconciliationJob: ModerationReconciliationJob;
+    /** One reconciliation sweep, on demand. */
+    readonly reconcile: ReconcileModerationReports;
+    /** The reported types that have a subject provider, so a test can pin the set. */
+    deliverableTypes(): string[];
+    readonly registry: SubjectRegistry;
+    readonly enforcement: EnforcementExecutor<TAction>;
+    readonly client: CrowdSourceClientProvider;
+}
+export declare function createModerationIntegration<TReport extends ModerationReportFields, TAction extends string, TTx>(config: ModerationIntegrationConfig<TReport, TAction, TTx>): ModerationIntegration<TReport, TAction>;
+//# sourceMappingURL=integration.d.ts.map

package/dist/outbox/integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.d.ts","sourceRoot":"","sources":["../../src/outbox/integration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAwB,KAAK,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAGnF,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAEhG,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAE5E,OAAO,EAAE,0BAA0B,EAAsB,MAAM,wBAAwB,CAAC;AAGxF,OAAO,EACL,2BAA2B,EAE3B,KAAK,0BAA0B,EAChC,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,2BAA2B,EAC3B,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,qBAAqB,CACpC,OAAO,SAAS,sBAAsB,EACtC,OAAO,SAAS,MAAM;IAEtB;;;;;;OAMG;IACH,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;IAE7E;;;;;;;OAOG;IACH,aAAa,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;IAEnD;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,0BAA0B,CAAC;IAEhD;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,2BAA2B,CAAC;IAExD,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,0BAA0B,CAAC;IAE/C,kFAAkF;IAClF,gBAAgB,IAAI,MAAM,EAAE,CAAC;IAE7B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAC;CAC5C;AAED,wBAAgB,2BAA2B,CACzC,OAAO,SAAS,sBAAsB,EACtC,OAAO,SAAS,MAAM,EACtB,GAAG,EAEH,MAAM,EAAE,2BAA2B,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,GACzD,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,CAiHzC"}

package/dist/outbox/integration.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createModerationIntegration = createModerationIntegration;
+const client_js_1 = require("./client.js");
+const decision_js_1 = require("./decision.js");
+const delivery_js_1 = require("./delivery.js");
+const executor_js_1 = require("./enforcement/executor.js");
+const planner_js_1 = require("./enforcement/planner.js");
+const evidence_js_1 = require("./evidence.js");
+const inbound_js_1 = require("./inbound.js");
+const dispatcher_js_1 = require("./outbox/dispatcher.js");
+const service_js_1 = require("./outbox/service.js");
+const intake_js_1 = require("./intake.js");
+const reconciliation_js_1 = require("./reconciliation.js");
+const webhook_js_1 = require("./webhook.js");
+function createModerationIntegration(config) {
+    /**
+     * Refuse an inverted `restoreAction` before anything is wired. It cannot be
+     * caught by the type — both directions are `TAction[]` — and it does not fail
+     * at runtime; it applies a punishment on an accepted appeal.
+     */
+    (0, planner_js_1.assertRestoreDirection)(config.enforcement);
+    const store = config.store;
+    const outbox = (0, service_js_1.createOutboxService)({ store: store.outbox, logger: config.logger });
+    const registry = (0, evidence_js_1.createSubjectRegistry)(config.subjects);
+    const client = (0, client_js_1.createClientProvider)({
+        config: config.crowdSource,
+        logger: config.logger,
+    });
+    const enforcement = (0, executor_js_1.createEnforcementExecutor)({
+        enforcement: store.enforcement,
+        config: config.enforcement,
+        defaultMode: config.crowdSource.enforcementMode,
+        logger: config.logger,
+        ...(config.metrics === undefined ? {} : { metrics: config.metrics }),
+    });
+    const deliverReport = (0, delivery_js_1.createDeliveryWorker)({
+        reports: store.reports,
+        registry,
+        taxonomy: config.taxonomy,
+        client,
+        logger: config.logger,
+        ...(config.metrics === undefined ? {} : { metrics: config.metrics }),
+    });
+    const applyDecision = (0, decision_js_1.createDecisionWorker)({
+        reports: store.reports,
+        executor: enforcement,
+        enforcement: config.enforcement,
+        logger: config.logger,
+        ...(config.reportDecisionExtraFields === undefined
+            ? {}
+            : { reportDecisionExtraFields: config.reportDecisionExtraFields }),
+    });
+    const inbound = (0, inbound_js_1.createInboundService)({
+        transaction: store.transaction,
+        events: store.events,
+        outbox,
+    });
+    const reconcile = (0, reconciliation_js_1.createReconciliation)({
+        transaction: store.transaction,
+        reports: store.reports,
+        outbox,
+        logger: config.logger,
+        ...(config.crowdSource.staleSubmittedHours === undefined
+            ? {}
+            : { staleSubmittedHours: config.crowdSource.staleSubmittedHours }),
+    });
+    const dispatcher = new dispatcher_js_1.ModerationOutboxDispatcher({
+        outbox,
+        handler: (0, dispatcher_js_1.createOutboxRouter)({ deliverReport, applyDecision }),
+        logger: config.logger,
+        enabled: config.crowdSource.enabled,
+        ...(config.crowdSource.outboxPollIntervalMs === undefined
+            ? {}
+            : { pollIntervalMs: config.crowdSource.outboxPollIntervalMs }),
+        ...(config.crowdSource.outboxBatchSize === undefined
+            ? {}
+            : { batchSize: config.crowdSource.outboxBatchSize }),
+    });
+    const reconciliationJob = new reconciliation_js_1.ModerationReconciliationJob({
+        reconcile,
+        logger: config.logger,
+        enabled: config.crowdSource.enabled,
+        ...(config.crowdSource.reconciliationIntervalMs === undefined
+            ? {}
+            : { intervalMs: config.crowdSource.reconciliationIntervalMs }),
+    });
+    return {
+        createReport: (0, intake_js_1.createIntake)({
+            transaction: store.transaction,
+            reports: store.reports,
+            registry,
+            outbox,
+        }),
+        webhookRouter(options = {}) {
+            return (0, webhook_js_1.createWebhookRouter)({
+                inbound,
+                store: (0, inbound_js_1.createProcessedEventStore)(store.events),
+                ...(config.crowdSource.webhookSecret === undefined
+                    ? {}
+                    : { secret: config.crowdSource.webhookSecret }),
+                ...(config.crowdSource.webhookPreviousSecret === undefined
+                    ? {}
+                    : { previousSecret: config.crowdSource.webhookPreviousSecret }),
+                logger: config.logger,
+                ...(config.metrics === undefined ? {} : { metrics: config.metrics }),
+                ...(options.path === undefined ? {} : { path: options.path }),
+            });
+        },
+        dispatcher,
+        reconciliationJob,
+        reconcile,
+        deliverableTypes: () => registry.deliverableTypes(),
+        registry,
+        enforcement,
+        client,
+    };
+}
+//# sourceMappingURL=integration.js.map

package/dist/outbox/integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.js","sourceRoot":"","sources":["../../src/outbox/integration.ts"],"names":[],"mappings":"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"}

package/dist/outbox/outbox/dispatcher.d.ts

@@ -0,0 +1,26 @@
+import type { ModerationLogger, ModerationOutboxEvent } from '../types.js';
+import type { ModerationOutboxHandler, OutboxDrain } from './service.js';
+export declare class ModerationOutboxDispatcher {
+    private readonly options;
+    private timer;
+    private inFlight;
+    private abortController;
+    private running;
+    constructor(options: {
+        outbox: OutboxDrain;
+        handler: ModerationOutboxHandler;
+        logger: ModerationLogger;
+        enabled: boolean;
+        pollIntervalMs?: number;
+        batchSize?: number;
+    });
+    start(): void;
+    stop(): Promise<void>;
+    private tick;
+}
+/** Route an event to the worker that owns its kind. */
+export declare function createOutboxRouter(handlers: {
+    deliverReport: (event: ModerationOutboxEvent) => Promise<void>;
+    applyDecision: (event: ModerationOutboxEvent) => Promise<void>;
+}): ModerationOutboxHandler;
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/outbox/outbox/dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../../src/outbox/outbox/dispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,KAAK,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAwBzE,qBAAa,0BAA0B;IAOnC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,OAAO,CAAS;gBAGL,OAAO,EAAE;QACxB,MAAM,EAAE,WAAW,CAAC;QACpB,OAAO,EAAE,uBAAuB,CAAC;QACjC,MAAM,EAAE,gBAAgB,CAAC;QACzB,OAAO,EAAE,OAAO,CAAC;QACjB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;IAGH,KAAK,IAAI,IAAI;IAsBP,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAcb,IAAI;CAmCnB;AAED,uDAAuD;AACvD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE;IAC3C,aAAa,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,aAAa,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE,GAAG,uBAAuB,CAW1B"}

package/dist/outbox/outbox/dispatcher.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModerationOutboxDispatcher = void 0;
+exports.createOutboxRouter = createOutboxRouter;
+/**
+ * The loop that drains the moderation outbox.
+ *
+ * A bounded interval, one batch in flight at a time, an abort signal that stops
+ * claiming new work but lets the event already being handled reach a durable
+ * state.
+ *
+ * It is NOT leader-gated, and that is a property of the claim rather than an
+ * oversight. Every event is taken under a lease with an owner check, so N tasks
+ * draining the same collection simply share the work — and a task dying
+ * mid-delivery has its lease expire and its event reclaimed, which a single
+ * leader would not give us.
+ *
+ * `enabled` gates the LOOP, never the durable record. Reports taken while the
+ * integration is off keep their outbox rows and deliver when it is switched on;
+ * running the loop instead would count attempts against a deployment that has
+ * nowhere to send anything and dead-letter the backlog it was supposed to
+ * preserve.
+ */
+const DEFAULT_POLL_INTERVAL_MS = 5000;
+class ModerationOutboxDispatcher {
+    constructor(options) {
+        this.options = options;
+        this.timer = null;
+        this.inFlight = null;
+        this.abortController = null;
+        this.running = false;
+    }
+    start() {
+        if (this.running)
+            return;
+        if (!this.options.enabled) {
+            this.options.logger.info('[CrowdSource] outbox dispatcher not started: the integration is disabled');
+            return;
+        }
+        const intervalMs = this.options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.running = true;
+        this.abortController = new AbortController();
+        void this.tick();
+        this.timer = setInterval(() => {
+            void this.tick();
+        }, intervalMs);
+        this.timer.unref?.();
+        this.options.logger.info('[CrowdSource] outbox dispatcher started', {
+            intervalMs,
+            batchSize: this.options.batchSize,
+        });
+    }
+    async stop() {
+        this.running = false;
+        const controller = this.abortController;
+        controller?.abort();
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.inFlight;
+        if (this.abortController === controller) {
+            this.abortController = null;
+        }
+    }
+    async tick() {
+        if (!this.running)
+            return;
+        if (this.inFlight)
+            return this.inFlight;
+        const work = this.options.outbox
+            .dispatch({
+            handler: this.options.handler,
+            ...(this.options.batchSize === undefined
+                ? {}
+                : { batchSize: this.options.batchSize }),
+            ...(this.abortController === null
+                ? {}
+                : { signal: this.abortController.signal }),
+        })
+            .then(({ processed, failed, deadLettered }) => {
+            if (processed > 0 || failed > 0) {
+                this.options.logger.info('[CrowdSource] outbox batch complete', {
+                    processed,
+                    failed,
+                    deadLettered,
+                });
+            }
+        })
+            .catch((error) => {
+            // Claim/database failures happen outside the per-event retry block. Keep
+            // the interval alive and avoid an unhandled rejection.
+            this.options.logger.error('[CrowdSource] outbox tick failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        })
+            .finally(() => {
+            if (this.inFlight === work)
+                this.inFlight = null;
+        });
+        this.inFlight = work;
+        return work;
+    }
+}
+exports.ModerationOutboxDispatcher = ModerationOutboxDispatcher;
+/** Route an event to the worker that owns its kind. */
+function createOutboxRouter(handlers) {
+    return async (event) => {
+        switch (event.kind) {
+            case 'report.submit':
+                await handlers.deliverReport(event);
+                return;
+            case 'decision.apply':
+                await handlers.applyDecision(event);
+                return;
+        }
+    };
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/outbox/outbox/dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../../src/outbox/outbox/dispatcher.ts"],"names":[],"mappings":";;;AAoHA,gDAcC;AA/HD;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,wBAAwB,GAAG,IAAK,CAAC;AAEvC,MAAa,0BAA0B;IAMrC,YACmB,OAOhB;QAPgB,YAAO,GAAP,OAAO,CAOvB;QAbK,UAAK,GAA0C,IAAI,CAAC;QACpD,aAAQ,GAAyB,IAAI,CAAC;QACtC,oBAAe,GAA2B,IAAI,CAAC;QAC/C,YAAO,GAAG,KAAK,CAAC;IAWrB,CAAC;IAEJ,KAAK;QACH,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YAC1B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CACtB,0EAA0E,CAC3E,CAAC;YACF,OAAO;QACT,CAAC;QACD,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,IAAI,wBAAwB,CAAC;QAC3E,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;QAC7C,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,CAAC,EAAE,UAAU,CAAC,CAAC;QACf,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QACrB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,yCAAyC,EAAE;YAClE,UAAU;YACV,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS;SAClC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,IAAI;QACR,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,CAAC;QACxC,UAAU,EAAE,KAAK,EAAE,CAAC;QACpB,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;QACD,MAAM,IAAI,CAAC,QAAQ,CAAC;QACpB,IAAI,IAAI,CAAC,eAAe,KAAK,UAAU,EAAE,CAAC;YACxC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAC9B,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,IAAI;QAChB,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAC;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM;aAC7B,QAAQ,CAAC;YACR,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO;YAC7B,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS;gBACtC,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YAC1C,GAAG,CAAC,IAAI,CAAC,eAAe,KAAK,IAAI;gBAC/B,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,CAAC;SAC7C,CAAC;aACD,IAAI,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,EAAE;YAC5C,IAAI,SAAS,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;gBAChC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,qCAAqC,EAAE;oBAC9D,SAAS;oBACT,MAAM;oBACN,YAAY;iBACb,CAAC,CAAC;YACL,CAAC;QACH,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACxB,yEAAyE;YACzE,uDAAuD;YACvD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,kCAAkC,EAAE;gBAC5D,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAC9D,CAAC,CAAC;QACL,CAAC,CAAC;aACD,OAAO,CAAC,GAAG,EAAE;YACZ,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI;gBAAE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACnD,CAAC,CAAC,CAAC;QACL,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAxFD,gEAwFC;AAED,uDAAuD;AACvD,SAAgB,kBAAkB,CAAC,QAGlC;IACC,OAAO,KAAK,EAAE,KAA4B,EAAiB,EAAE;QAC3D,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,eAAe;gBAClB,MAAM,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;gBACpC,OAAO;YACT,KAAK,gBAAgB;gBACnB,MAAM,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;gBACpC,OAAO;QACX,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/outbox/outbox/service.d.ts

@@ -0,0 +1,124 @@
+import type { ModerationOutboxStore } from '../store/types.js';
+import type { ModerationDispatchResult, ModerationLogger, ModerationOutboxEvent, ModerationOutboxKind, ModerationOutboxPayload, ModerationOutboxStatus } from '../types.js';
+/**
+ * The event id for delivering a report.
+ *
+ * Derived from the report, not from the request: a transaction retry or two
+ * concurrent duplicate submissions upsert the SAME event rather than queueing
+ * two deliveries. There is exactly one delivery event per report for the life of
+ * the report, which is also what makes the CrowdSource-side idempotency key
+ * stable.
+ */
+export declare function reportSubmitEventId(reportId: string): string;
+/**
+ * The event id for applying an inbound decision.
+ *
+ * The webhook event id is the key, so a redelivery of the same event can never
+ * queue the work twice even if the dedupe claim were somehow released.
+ */
+export declare function decisionApplyEventId(eventId: string): string;
+/**
+ * Raised when an outbox event is written outside a transaction.
+ *
+ * Never expected at runtime. It exists so the invariant is ENFORCED rather than
+ * reviewed. It is thrown by the STORE — only a backend knows what an open
+ * transaction looks like — and it lives here so that every backend throws the
+ * same error for the same mistake. See {@link ModerationOutboxStore.enqueue}.
+ */
+export declare class ModerationOutboxTransactionError extends Error {
+    constructor(eventId: string);
+}
+/**
+ * A failure that says whether trying the same payload again could ever work.
+ *
+ * Every error `@crowdsource.you/core` throws carries `retryable`, which is the only
+ * thing a delivery worker needs from it. Anything else — a bug in this code, a
+ * Mongo error — is treated as retryable, because assuming a defect is permanent
+ * is how a recoverable outage becomes lost moderation work.
+ */
+export declare function isRetryableDeliveryError(error: unknown): boolean;
+export interface ModerationOutboxFailure {
+    released: boolean;
+    deadLettered: boolean;
+}
+export type ModerationOutboxHandler = (event: ModerationOutboxEvent) => Promise<void>;
+/**
+ * Draining the outbox: the one operation that never touches a transaction.
+ *
+ * Split out so {@link ModerationOutboxDispatcher} — which only ever asks for a
+ * batch — does not carry a backend's transaction type through a class that has
+ * no use for it.
+ */
+export interface OutboxDrain {
+    /** Drain up to `batchSize` due events. Bounded, at-least-once, lease-protected. */
+    dispatch(options: {
+        handler: ModerationOutboxHandler;
+        leaseOwner?: string;
+        batchSize?: number;
+        leaseMs?: number;
+        signal?: AbortSignal;
+    }): Promise<ModerationDispatchResult>;
+}
+export interface OutboxService<TTx> extends OutboxDrain {
+    /**
+     * Write the event in the CALLER's transaction.
+     *
+     * The transaction is required, not optional. This is the whole point of the
+     * collection: the domain write and this row commit together or not at all. An
+     * overload that let a caller enqueue outside a transaction would be the one
+     * line that quietly reintroduces "the report was answered 201 and then
+     * vanished".
+     *
+     * The type makes the transaction mandatory; the STORE makes it mandatory that
+     * the transaction is ACTUALLY OPEN, by throwing
+     * {@link ModerationOutboxTransactionError}. A required parameter is satisfied
+     * by any handle — including a bare Mongo `startSession()` nobody opened a
+     * transaction on, which type-checks perfectly and commits the row on its own.
+     * That is the shape of the mistake worth catching: it looks exactly like
+     * correct code, it passes any test that only asserts the row exists, and it
+     * fails as lost moderation work with no trace on the day something restarts
+     * between the two writes.
+     *
+     * This function is also the ONLY writer of that table — the dispatcher claims
+     * existing rows and never creates one — so there is no second queue that can
+     * drift out of sync with the outbox. A job here is never the only evidence
+     * that work exists, because the row IS the job.
+     */
+    enqueue(input: {
+        eventId: string;
+        kind: ModerationOutboxKind;
+        payload: ModerationOutboxPayload;
+    }, tx: TTx): Promise<string>;
+    /**
+     * Atomically claim one due event. An expired `processing` lease is
+     * reclaimable, so a dead worker cannot strand moderation work forever.
+     */
+    claim(options: {
+        leaseOwner: string;
+        eventId?: string;
+        now?: Date;
+        leaseMs?: number;
+    }): Promise<ModerationOutboxEvent | null>;
+    /** Complete only the lease this dispatcher currently owns. */
+    complete(eventId: string, leaseOwner: string, now?: Date): Promise<boolean>;
+    /** Extend only a live lease still owned by this dispatcher. */
+    renew(eventId: string, leaseOwner: string, leaseMs: number, now?: Date): Promise<ModerationOutboxFailure['released']>;
+    /**
+     * Release a failed claim, with backoff — or stop.
+     *
+     * Stopping is not an optimisation. A 409 means this `externalReportId` already
+     * exists at CrowdSource with a different body, and no number of retries turns
+     * two payloads into one report; a 422 means the envelope is not processable.
+     * Both need the payload to change, so they become `dead_letter` immediately
+     * and stay visible with their error rather than accumulating attempts nobody
+     * reads.
+     */
+    fail(event: Pick<ModerationOutboxEvent, 'id' | 'attempts'>, leaseOwner: string, error: unknown, now?: Date): Promise<ModerationOutboxFailure>;
+    /** The status of one event, or `null`. Read by reconciliation. */
+    statusOf(eventId: string): Promise<ModerationOutboxStatus | null>;
+}
+export declare function createOutboxService<TTx>(input: {
+    store: ModerationOutboxStore<TTx>;
+    logger: ModerationLogger;
+}): OutboxService<TTx>;
+//# sourceMappingURL=service.d.ts.map

package/dist/outbox/outbox/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/outbox/outbox/service.ts"],"names":[],"mappings":"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"}