@crowdsource.you/core 1.2.0

package/dist/esm/outbox/index.js

@@ -0,0 +1,71 @@
+/**
+ * `@crowdsource.you/core/outbox` — the application half of a CrowdSource integration.
+ *
+ * An application that adopts CrowdSource has to solve the same six problems
+ * every other application does: store a report and its promise of delivery
+ * atomically, deliver it with retries and a dead-letter path, receive signed
+ * decisions without a body parser destroying the signature, deduplicate
+ * redeliveries across several tasks, apply a decision without a stale revision
+ * overwriting a fresh one, and carry out consequences exactly once and
+ * reversibly. None of that has anything to do with what the application's
+ * objects are.
+ *
+ * So all of it is here, and an application supplies four things: its subjects,
+ * its category mapping, its enforcement tables, and a STORE built by the
+ * PostgreSQL store factory.
+ *
+ * ```ts
+ * import { createModerationIntegration } from '@crowdsource.you/core/outbox';
+ * import { postgresModerationStore } from '@crowdsource.you/core/outbox/postgres';
+ *
+ * const moderation = createModerationIntegration({
+ *   store,
+ *   crowdSource: { enabled: true, serviceKey, webhookSecret, enforcementMode: 'observe' },
+ *   subjects: [listingSubjectProvider(), reviewSubjectProvider()],
+ *   taxonomy: { version: '2026.07', allegationsFor },
+ *   enforcement: commerceEnforcement,
+ *   logger,
+ * });
+ *
+ * // Indexes before the first write: the unique ones ARE the exactly-once
+ * // mechanism, and an index that does not exist yet refuses nothing.
+ * await store.ensureSchema();
+ *
+ * // BEFORE express.json() — the signature covers the bytes that arrived.
+ * app.use('/webhooks', moderation.webhookRouter());
+ * app.use(express.json());
+ *
+ * moderation.dispatcher.start();
+ * ```
+ *
+ * Two invariants are ENFORCED here rather than documented, because both fail
+ * silently and neither shows up in a test that only asserts the happy path:
+ *
+ * 1. Nothing can be enqueued that is not already recorded in the outbox, in the
+ *    same transaction. {@link ModerationOutboxTransactionError} is thrown by the
+ *    only writer of that collection when the transaction it was handed is not
+ *    open.
+ * 2. The webhook receiver reads raw bytes. Mounted after a JSON parser it
+ *    refuses rather than verifying a signature over a re-serialisation.
+ *
+ * Types come from `@crowdsource.you/contracts` and `@crowdsource.you/core`. This
+ * package re-exports none of them: a `Decision` or a `TaxonomyCode` has exactly
+ * one definition.
+ */
+export { createModerationIntegration } from './integration.js';
+/**
+ * The retention windows are storage-independent policy, so they stay here while
+ * PostgreSQL-specific tables and stores live behind the `/postgres` subpath.
+ */
+export { MODERATION_EVENT_RETENTION_SECONDS, MODERATION_OUTBOX_RETENTION_SECONDS, } from './retention.js';
+export { ModerationOutboxTransactionError, decisionApplyEventId, isRetryableDeliveryError, reportSubmitEventId, } from './outbox/service.js';
+export { ModerationOutboxDispatcher } from './outbox/dispatcher.js';
+export { ModerationReconciliationJob } from './reconciliation.js';
+export { DuplicateReportError } from './intake.js';
+export { CrowdSourceUnavailableError, ModerationDeliveryRejectedError, } from './delivery.js';
+export { ModerationDecisionDeferredError, ModerationDecisionRejectedError, } from './decision.js';
+export { ModerationSubjectUnsupportedError, ModerationTaxonomyError, createSubjectRegistry, snapshotHash, } from './evidence.js';
+export { ModerationRestoreDirectionError, assertRestoreDirection, planEnforcement, primaryAction, } from './enforcement/planner.js';
+export { localStatusForDecision } from './reportStatus.js';
+export { createProcessedEventStore } from './inbound.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/outbox/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/outbox/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAG/D;;;GAGG;AACH,OAAO,EACL,kCAAkC,EAClC,mCAAmC,GACpC,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,gCAAgC,EAChC,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAsB7B,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAGlE,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EACL,2BAA2B,EAC3B,+BAA+B,GAChC,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,+BAA+B,EAC/B,+BAA+B,GAChC,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,iCAAiC,EACjC,uBAAuB,EACvB,qBAAqB,EACrB,YAAY,GACb,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,+BAA+B,EAC/B,sBAAsB,EACtB,eAAe,EACf,aAAa,GACd,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC"}

package/dist/esm/outbox/intake.js

@@ -0,0 +1,140 @@
+import { reportSubmitEventId } from './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.
+ */
+export class DuplicateReportError extends Error {
+    constructor(existing) {
+        super('This item has already been reported by this reporter.');
+        this.name = 'DuplicateReportError';
+        this.existing = existing;
+    }
+}
+/**
+ * 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.
+ */
+export 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: reportSubmitEventId(created.id),
+                kind: 'report.submit',
+                payload: { reportId: created.id },
+            }, tx);
+            return { report: created, outboxEventId };
+        });
+    };
+}
+//# sourceMappingURL=intake.js.map

package/dist/esm/outbox/intake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intake.js","sourceRoot":"","sources":["../../../src/outbox/intake.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAsB,MAAM,qBAAqB,CAAC;AAW9E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,OAAO,oBAA8B,SAAQ,KAAK;IAGtD,YAAY,QAAiB;QAC3B,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC/D,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAS,iBAAiB,CAAC,KAAc,EAAE,KAAa;IACtD;;;;;;;;;OASG;IACH,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,MAAM,IAAI,SAAS,CAAC,iBAAiB,KAAK,8BAA8B,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,eAAe,CAAC,YAAoB;IAC3C,OAAO,CACL,gDAAgD,YAAY,uBAAuB;QACnF,wDAAwD,CACzD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,YAAY,CAA8C,KAKzE;IACC,OAAO,KAAK,EAAE,MAAM,EAAE,EAAE;QACtB,MAAM,QAAQ,GAAG,iBAAiB,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QAChE,MAAM,UAAU,GAAG,iBAAiB,CAAC,MAAM,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;QACtE,MAAM,YAAY,GAAG,iBAAiB,CAAC,MAAM,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC;QAC5E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxE,MAAM,IAAI,SAAS,CAAC,qDAAqD,CAAC,CAAC;QAC7E,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACzC,iBAAiB,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;QAC9C,CAAC;QACD,MAAM,WAAW,GAAG,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,YAAY,CAAC,KAAK,SAAS,CAAC;QAE3E,OAAO,MAAM,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;YAC9C,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,aAAa,CAChD,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,EACtC,EAAE,CACH,CAAC;YACF,IAAI,QAAQ;gBAAE,MAAM,IAAI,oBAAoB,CAAC,QAAQ,CAAC,CAAC;YAEvD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,CACxC;gBACE,YAAY;gBACZ,UAAU;gBACV,QAAQ;gBACR,UAAU,EAAE,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC;gBAClC,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpE,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU;gBAChD,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,eAAe,CAAC,YAAY,CAAC,EAAE,CAAC;gBAC5E,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;aAC/D,EACD,EAAE,CACH,CAAC;YAEF,IAAI,CAAC,WAAW;gBAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;YAE7C,MAAM,aAAa,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAC9C;gBACE,OAAO,EAAE,mBAAmB,CAAC,OAAO,CAAC,EAAE,CAAC;gBACxC,IAAI,EAAE,eAAe;gBACrB,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,EAAE;aAClC,EACD,EAAE,CACH,CAAC;YAEF,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;QAC5C,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/esm/outbox/integration.js

@@ -0,0 +1,116 @@
+import { createClientProvider } from './client.js';
+import { createDecisionWorker } from './decision.js';
+import { createDeliveryWorker } from './delivery.js';
+import { createEnforcementExecutor } from './enforcement/executor.js';
+import { assertRestoreDirection } from './enforcement/planner.js';
+import { createSubjectRegistry } from './evidence.js';
+import { createInboundService, createProcessedEventStore } from './inbound.js';
+import { ModerationOutboxDispatcher, createOutboxRouter } from './outbox/dispatcher.js';
+import { createOutboxService } from './outbox/service.js';
+import { createIntake } from './intake.js';
+import { ModerationReconciliationJob, createReconciliation, } from './reconciliation.js';
+import { createWebhookRouter } from './webhook.js';
+export 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.
+     */
+    assertRestoreDirection(config.enforcement);
+    const store = config.store;
+    const outbox = createOutboxService({ store: store.outbox, logger: config.logger });
+    const registry = createSubjectRegistry(config.subjects);
+    const client = createClientProvider({
+        config: config.crowdSource,
+        logger: config.logger,
+    });
+    const enforcement = createEnforcementExecutor({
+        enforcement: store.enforcement,
+        config: config.enforcement,
+        defaultMode: config.crowdSource.enforcementMode,
+        logger: config.logger,
+        ...(config.metrics === undefined ? {} : { metrics: config.metrics }),
+    });
+    const deliverReport = createDeliveryWorker({
+        reports: store.reports,
+        registry,
+        taxonomy: config.taxonomy,
+        client,
+        logger: config.logger,
+        ...(config.metrics === undefined ? {} : { metrics: config.metrics }),
+    });
+    const applyDecision = createDecisionWorker({
+        reports: store.reports,
+        executor: enforcement,
+        enforcement: config.enforcement,
+        logger: config.logger,
+        ...(config.reportDecisionExtraFields === undefined
+            ? {}
+            : { reportDecisionExtraFields: config.reportDecisionExtraFields }),
+    });
+    const inbound = createInboundService({
+        transaction: store.transaction,
+        events: store.events,
+        outbox,
+    });
+    const reconcile = createReconciliation({
+        transaction: store.transaction,
+        reports: store.reports,
+        outbox,
+        logger: config.logger,
+        ...(config.crowdSource.staleSubmittedHours === undefined
+            ? {}
+            : { staleSubmittedHours: config.crowdSource.staleSubmittedHours }),
+    });
+    const dispatcher = new ModerationOutboxDispatcher({
+        outbox,
+        handler: 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 ModerationReconciliationJob({
+        reconcile,
+        logger: config.logger,
+        enabled: config.crowdSource.enabled,
+        ...(config.crowdSource.reconciliationIntervalMs === undefined
+            ? {}
+            : { intervalMs: config.crowdSource.reconciliationIntervalMs }),
+    });
+    return {
+        createReport: createIntake({
+            transaction: store.transaction,
+            reports: store.reports,
+            registry,
+            outbox,
+        }),
+        webhookRouter(options = {}) {
+            return createWebhookRouter({
+                inbound,
+                store: 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/esm/outbox/integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.js","sourceRoot":"","sources":["../../../src/outbox/integration.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAkC,MAAM,aAAa,CAAC;AACnF,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,yBAAyB,EAA4B,MAAM,2BAA2B,CAAC;AAChG,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAwB,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,2BAA2B,EAC3B,oBAAoB,GAErB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAqEnD,MAAM,UAAU,2BAA2B,CAKzC,MAA0D;IAE1D;;;;OAIG;IACH,sBAAsB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAE3C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC3B,MAAM,MAAM,GAAG,mBAAmB,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACnF,MAAM,QAAQ,GAAG,qBAAqB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,oBAAoB,CAAC;QAClC,MAAM,EAAE,MAAM,CAAC,WAAW;QAC1B,MAAM,EAAE,MAAM,CAAC,MAAM;KACtB,CAAC,CAAC;IAEH,MAAM,WAAW,GAAG,yBAAyB,CAAU;QACrD,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,MAAM,EAAE,MAAM,CAAC,WAAW;QAC1B,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC,eAAe;QAC/C,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;KACrE,CAAC,CAAC;IAEH,MAAM,aAAa,GAAG,oBAAoB,CAAC;QACzC,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,QAAQ;QACR,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,MAAM;QACN,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;KACrE,CAAC,CAAC;IAEH,MAAM,aAAa,GAAG,oBAAoB,CAAC;QACzC,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,QAAQ,EAAE,WAAW;QACrB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,GAAG,CAAC,MAAM,CAAC,yBAAyB,KAAK,SAAS;YAChD,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,yBAAyB,EAAE,MAAM,CAAC,yBAAyB,EAAE,CAAC;KACrE,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,oBAAoB,CAAC;QACnC,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,MAAM;KACP,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,oBAAoB,CAAC;QACrC,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,MAAM;QACN,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,mBAAmB,KAAK,SAAS;YACtD,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,mBAAmB,EAAE,MAAM,CAAC,WAAW,CAAC,mBAAmB,EAAE,CAAC;KACrE,CAAC,CAAC;IAEH,MAAM,UAAU,GAAG,IAAI,0BAA0B,CAAC;QAChD,MAAM;QACN,OAAO,EAAE,kBAAkB,CAAC,EAAE,aAAa,EAAE,aAAa,EAAE,CAAC;QAC7D,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,OAAO;QACnC,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,oBAAoB,KAAK,SAAS;YACvD,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,WAAW,CAAC,oBAAoB,EAAE,CAAC;QAChE,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,eAAe,KAAK,SAAS;YAClD,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC;KACvD,CAAC,CAAC;IAEH,MAAM,iBAAiB,GAAG,IAAI,2BAA2B,CAAC;QACxD,SAAS;QACT,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,OAAO;QACnC,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,wBAAwB,KAAK,SAAS;YAC3D,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,WAAW,CAAC,wBAAwB,EAAE,CAAC;KACjE,CAAC,CAAC;IAEH,OAAO;QACL,YAAY,EAAE,YAAY,CAAC;YACzB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,QAAQ;YACR,MAAM;SACP,CAAC;QAEF,aAAa,CAAC,OAAO,GAAG,EAAE;YACxB,OAAO,mBAAmB,CAAC;gBACzB,OAAO;gBACP,KAAK,EAAE,yBAAyB,CAAC,KAAK,CAAC,MAAM,CAAC;gBAC9C,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,aAAa,KAAK,SAAS;oBAChD,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,aAAa,EAAE,CAAC;gBACjD,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,qBAAqB,KAAK,SAAS;oBACxD,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,WAAW,CAAC,qBAAqB,EAAE,CAAC;gBACjE,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpE,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;aAC9D,CAAC,CAAC;QACL,CAAC;QAED,UAAU;QACV,iBAAiB;QACjB,SAAS;QACT,gBAAgB,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,gBAAgB,EAAE;QACnD,QAAQ;QACR,WAAW;QACX,MAAM;KACP,CAAC;AACJ,CAAC"}

package/dist/esm/outbox/outbox/dispatcher.js

@@ -0,0 +1,114 @@
+/**
+ * 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;
+export 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;
+    }
+}
+/** Route an event to the worker that owns its kind. */
+export 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/esm/outbox/outbox/dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../../../src/outbox/outbox/dispatcher.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,wBAAwB,GAAG,IAAK,CAAC;AAEvC,MAAM,OAAO,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;AAED,uDAAuD;AACvD,MAAM,UAAU,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"}