@crowdsource.you/core 1.2.0

package/dist/esm/outbox/decision.js

@@ -0,0 +1,153 @@
+import { DecisionSchema } from '@crowdsource.you/contracts';
+import { primaryAction } from './enforcement/planner.js';
+import { localStatusForDecision } from './reportStatus.js';
+/**
+ * Applying a decision that has already been received and recorded.
+ *
+ * The webhook answered 2xx long before this runs. What is left is the part that
+ * touches several collections: write the decision onto every report that opened
+ * or joined the case, and enforce it once.
+ *
+ * "Once" is the invariant that shapes this file. A hundred reports about the
+ * same material produce ONE case and ONE consequence, so enforcement is keyed on
+ * the decision and not on the reports — the executor is called a single time no
+ * matter how many reports are updated, and its own unique index makes even that
+ * call safe to repeat.
+ */
+/** A failure that will not be fixed by trying again. */
+export class ModerationDecisionRejectedError extends Error {
+    constructor(message) {
+        super(message);
+        /** Read by the outbox: `false` dead-letters instead of retrying. */
+        this.retryable = false;
+        this.name = 'ModerationDecisionRejectedError';
+    }
+}
+/** A failure that a later attempt can still resolve. */
+export class ModerationDecisionDeferredError extends Error {
+    constructor(message) {
+        super(message);
+        this.retryable = true;
+        this.name = 'ModerationDecisionDeferredError';
+    }
+}
+export function createDecisionWorker(input) {
+    /**
+     * Write the decision onto one report.
+     *
+     * `decision.revision` is passed as the ceiling the store guards on, so it is
+     * the DATABASE that refuses a stale write rather than a read-then-write in
+     * this process. Deliveries can overlap — CrowdSource retries for 24 hours, and
+     * a correction can arrive while the decision it supersedes is still being
+     * applied — and an older revision landing last would otherwise overwrite the
+     * current answer with a stale one.
+     */
+    const applyToReport = async (reportId, decision, enforced) => await input.reports.applyDecision(reportId, {
+        localStatus: localStatusForDecision(decision.status),
+        decisionId: decision.id,
+        decisionRevision: decision.revision,
+        decisionOutcome: decision.outcome,
+        decisionStatus: decision.status,
+        decidedAt: new Date(decision.publishedAt),
+        /**
+         * `enforcedAction` is what the application DECIDED to do; `enforcedAt`
+         * is when an effect actually landed. They are written separately because
+         * they are different claims, and conflating them puts a timestamp on
+         * something that never happened — which is the normal case in `observe`
+         * mode, and the permanent case for an application with no sanction
+         * primitive. An audit row that says "enforced at 14:02" for an effect
+         * nobody carried out is not explainable, and every effect being
+         * explainable is the invariant.
+         */
+        ...(enforced === undefined
+            ? {}
+            : {
+                enforcedAction: enforced.action,
+                ...(enforced.at === null ? {} : { enforcedAt: enforced.at }),
+            }),
+        ...(input.reportDecisionExtraFields === undefined
+            ? {}
+            : { extra: input.reportDecisionExtraFields(decision) }),
+    }, decision.revision);
+    return async (event) => {
+        const caseId = event.payload.caseId;
+        if (caseId === undefined) {
+            throw new ModerationDecisionRejectedError('A decision.apply event carried no caseId.');
+        }
+        /**
+         * Parsed HERE rather than at the webhook.
+         *
+         * The receiver's job was to prove the bytes came from CrowdSource and to
+         * record them; refusing an unrecognised shape at the door would put a real
+         * decision back on a retry schedule until it expired. Parsing at the point
+         * of use means an event this deployment cannot yet read waits in the outbox
+         * until it can.
+         */
+        const parsed = DecisionSchema.safeParse(event.payload.decision);
+        if (!parsed.success) {
+            throw new ModerationDecisionRejectedError(`The decision for case ${caseId} does not match the published contract: ${parsed.error.issues
+                .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+                .join('; ')}`);
+        }
+        const decision = parsed.data;
+        const reports = await input.reports.findByCaseId(caseId);
+        if (reports.length === 0) {
+            /**
+             * Retryable, and the race is real rather than theoretical: CrowdSource can
+             * decide a case and deliver the webhook while the response that carried
+             * the case id back to this deployment is still being written, or while a
+             * delivery is being retried. Backing off is correct; dead-lettering would
+             * throw the decision away.
+             */
+            throw new ModerationDecisionDeferredError(`No local report is linked to case ${caseId} yet.`);
+        }
+        /**
+         * One subject per case. The dedup key includes the subject's external id, so
+         * every report merged into a case is about the same object — the first
+         * report names it.
+         */
+        const [first] = reports;
+        const outcomes = await input.executor.apply({
+            decision,
+            caseId,
+            subject: { type: first.reportedType, id: first.reportedId },
+        });
+        /**
+         * The EFFECTIVE action, not the planned one. `apply` is the only place that
+         * knows a planned action could not apply to this particular object, and
+         * `recordedAs` is how it says so — see `EnforcementEffect`.
+         */
+        const effectiveAction = (outcome) => outcome.recordedAs ?? outcome.action;
+        const enforcedAction = primaryAction(outcomes.map(effectiveAction), input.enforcement.precedence ?? input.enforcement.actions);
+        /**
+         * The timestamp belongs to the outcome of THIS action, not to the plan. An
+         * action that was claimed and recorded — observe mode, a mode that does not
+         * apply it, or an application with nothing to apply — leaves `enforcedAt`
+         * unset while `enforcedAction` still says what was decided.
+         */
+        const enforced = enforcedAction === undefined
+            ? undefined
+            : {
+                action: enforcedAction,
+                at: outcomes.some((outcome) => effectiveAction(outcome) === enforcedAction &&
+                    outcome.result === 'applied')
+                    ? new Date()
+                    : null,
+            };
+        let updated = 0;
+        for (const report of reports) {
+            if (await applyToReport(report.id, decision, enforced))
+                updated += 1;
+        }
+        input.logger.info('[CrowdSource] decision applied', {
+            caseId,
+            decisionId: decision.id,
+            revision: decision.revision,
+            outcome: decision.outcome,
+            reportsMatched: reports.length,
+            reportsUpdated: updated,
+            actions: outcomes.map((outcome) => `${outcome.action}:${outcome.result}`).join(','),
+        });
+    };
+}
+//# sourceMappingURL=decision.js.map

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

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

package/dist/esm/outbox/delivery.js

@@ -0,0 +1,129 @@
+import { buildModerationReportInput } from './evidence.js';
+/**
+ * Delivering a stored report to CrowdSource.
+ *
+ * Everything hard about this is already handled elsewhere and the shape of this
+ * file is what is left over: the SDK owns the envelope, the idempotency key, the
+ * timeouts, the per-attempt retries and the classification of failures; the
+ * outbox owns durability, backoff and dead-lettering. What remains is to
+ * describe the material, hand it over, and write down what came back.
+ *
+ * The failures are as important as the success:
+ *
+ * - **Nowhere to send it.** The integration is not configured. The event stays
+ *   pending, untouched, and delivers when it is — a delay, never a loss.
+ * - **The object is gone.** Deleted between the report and its delivery. There
+ *   is nothing to review, so the report closes locally instead of retrying for
+ *   days.
+ * - **The type has no provider.** Unreachable by design — such a report never
+ *   gets a delivery event — so an event that reaches it is a defect and is
+ *   dead-lettered rather than retried or filed as a state.
+ * - **Anything else** is the SDK's `retryable` to answer, and the outbox obeys
+ *   it.
+ */
+/** Thrown when there is nowhere to deliver to yet. Always retryable. */
+export class CrowdSourceUnavailableError extends Error {
+    constructor() {
+        super('The CrowdSource integration is not configured in this deployment.');
+        this.retryable = true;
+        this.name = 'CrowdSourceUnavailableError';
+    }
+}
+/**
+ * A delivery event that cannot become deliverable.
+ *
+ * `retryable: false` is the field the outbox reads to dead-letter instead of
+ * backing off — the same contract every error from `@crowdsource.you/core` answers.
+ */
+export class ModerationDeliveryRejectedError extends Error {
+    constructor(message) {
+        super(message);
+        this.retryable = false;
+        this.name = 'ModerationDeliveryRejectedError';
+    }
+}
+export function createDeliveryWorker(input) {
+    const count = (result) => {
+        input.metrics?.incrementCounter('crowdsource_report_delivery_total', 1, { result });
+    };
+    return async (event) => {
+        const reportId = event.payload.reportId;
+        if (reportId === undefined) {
+            throw new ModerationDeliveryRejectedError('A report.submit event carried no reportId.');
+        }
+        const report = await input.reports.findById(reportId);
+        if (!report) {
+            /**
+             * The report is gone but its delivery event survived. Nothing to deliver
+             * and nothing to fix, so the event completes — retrying would keep looking
+             * for a row that no longer exists.
+             */
+            input.logger.warn('[CrowdSource] delivery event has no report', { reportId });
+            return;
+        }
+        const crowdsource = input.client.get();
+        if (!crowdsource)
+            throw new CrowdSourceUnavailableError();
+        /**
+         * A `ModerationSubjectUnsupportedError` from here is NOT caught. It carries
+         * `retryable: false`, so the outbox dead-letters the event and the
+         * reconciliation sweep counts it — which is the right channel for a defect
+         * that needs a human. Catching it and writing a local state would put the
+         * report somewhere nothing alerts on.
+         */
+        const described = await buildModerationReportInput({
+            report: {
+                id: reportId,
+                reportedType: report.reportedType,
+                reportedId: report.reportedId,
+                reporter: report.reporter,
+                categories: report.categories,
+                ...(report.details === undefined ? {} : { details: report.details }),
+                createdAt: report.createdAt,
+            },
+            registry: input.registry,
+            taxonomy: input.taxonomy,
+        });
+        if (described === null) {
+            // Nothing left to review, so the report is closed with the reason rather
+            // than retried against material that is gone.
+            await input.reports.close(reportId, 'The reported content no longer exists, so there is nothing to review.');
+            count('content_unavailable');
+            return;
+        }
+        let receipt;
+        try {
+            receipt = await crowdsource.reports.create(described.reportInput);
+        }
+        catch (error) {
+            /**
+             * The failure is visible on the report itself, not only in the outbox row.
+             * `delivery_failed` is what a reporter's receipt and the reconciliation
+             * sweep both read; leaving the report at `queued` while the outbox quietly
+             * backed off would hide the problem in a collection nobody looks at.
+             * Written before rethrowing so the outbox still applies its own backoff or
+             * dead-letters the event.
+             */
+            await input.reports.markDeliveryFailed(reportId, 
+            // Bounded here rather than by a column width, so both dialects agree: a
+            // Mongoose validator throws on overflow and Postgres errors 22001.
+            (error instanceof Error ? error.message : String(error)).slice(0, 2000));
+            count('failed');
+            throw error;
+        }
+        await input.reports.markSubmitted(reportId, {
+            crowdSourceReportId: receipt.reportId,
+            crowdSourceCaseId: receipt.caseId,
+            crowdSourceMerged: receipt.merged,
+            contentSnapshotHash: described.snapshotHash,
+            submittedAt: new Date(),
+        });
+        count(receipt.merged ? 'merged' : 'delivered');
+        input.logger.info('[CrowdSource] report delivered', {
+            reportId,
+            caseId: receipt.caseId,
+            merged: receipt.merged,
+        });
+    };
+}
+//# sourceMappingURL=delivery.js.map

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

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

package/dist/esm/outbox/enforcement/executor.js

@@ -0,0 +1,219 @@
+import { planEnforcement } from './planner.js';
+/**
+ * Carrying out a decision, exactly once.
+ *
+ * Two guarantees, and everything here exists for one of them.
+ *
+ * **Once.** The idempotency key is `decisionId + revision + action`, and the
+ * unique index on the enforcement collection is that key. Each action CLAIMS its
+ * row before doing anything; a second attempt — a redelivered webhook, a
+ * reclaimed outbox lease, a manual replay — loses the insert and does nothing.
+ * Reading "have I done this?" and then acting would leave the gap between the
+ * two, which is exactly when a redelivery arrives.
+ *
+ * **Reversibly.** Every action that changes state records what the state WAS,
+ * and a reversal puts that back. So a correction does not lift a content warning
+ * the author set themselves, and a restore returns an object to the state it
+ * actually had rather than to a guess at one.
+ *
+ * `observe` mode runs all of this except the effect. That is deliberate: the
+ * plan, the claim and the record are identical to production, so what the mode
+ * proves is exactly what will happen when it is switched off — and the audit
+ * trail is real rather than a log line saying a decision was seen.
+ *
+ * The application supplies the tables and one `apply`. Everything above is this
+ * package's and is not configurable, because it is the invariant rather than the
+ * policy.
+ */
+/**
+ * Whether the current mode allows this action to actually happen.
+ *
+ * `observe` allows nothing — that is the mode. `manual` allows what the
+ * application declared reversible: those actions give something BACK, and
+ * holding them behind a human review means a wrongly-removed object stays
+ * removed while somebody reads a queue. Taking content down still waits for a
+ * person. `automatic` allows the mapped set.
+ */
+function modeAllows(mode, action, config) {
+    switch (mode) {
+        case 'observe':
+            return false;
+        case 'manual':
+            return (config.reversibleActions ?? []).includes(action);
+        case 'automatic':
+            return true;
+    }
+}
+export function createEnforcementExecutor(input) {
+    const { enforcement, config, logger } = input;
+    const count = (action, mode, result) => {
+        input.metrics?.incrementCounter('crowdsource_enforcement_total', 1, {
+            action,
+            mode,
+            result,
+        });
+    };
+    /**
+     * What the earlier action this one reverses left behind.
+     *
+     * Read from the most recent APPLIED row, so an action that was recorded but
+     * never carried out cannot be mistaken for one that changed something. This is
+     * the mechanism behind "only lift what moderation set": an absent row means
+     * the state was not moderation's doing, and the application's `apply` decides
+     * what to do with that.
+     */
+    const previousStateFor = async (action, subject) => {
+        const reversed = config.reverses?.[action];
+        if (reversed === undefined)
+            return undefined;
+        /**
+         * One action may reverse several. The most recent APPLIED row across the
+         * whole set wins, so `apply` receives what actually happened last rather
+         * than what a single declared action happened to be.
+         */
+        const candidates = typeof reversed === 'string' ? [reversed] : reversed;
+        if (candidates.length === 0)
+            return undefined;
+        const row = await enforcement.latestApplied({
+            subjectType: subject.type,
+            subjectId: subject.id,
+            actions: candidates,
+        });
+        if (row === null)
+            return undefined;
+        /**
+         * The row's own action, narrowed THROUGH the declared set rather than cast.
+         * The query guarantees membership; finding it here is what lets
+         * `previousAction` be a `TAction` without asserting that it is one.
+         */
+        const previousAction = candidates.find((candidate) => candidate === row.action);
+        if (previousAction === undefined)
+            return undefined;
+        return {
+            ...(row.previousState === undefined ? {} : { previousState: row.previousState }),
+            previousAction,
+        };
+    };
+    const applyOne = async (planned, context, mode) => {
+        const { decision, caseId, subject } = context;
+        /**
+         * The claim, and the ONLY way this row is ever addressed afterwards: the
+         * idempotency key itself, never a record id the insert happened to return.
+         * `false` means another delivery of this same decision revision already
+         * holds it, which is an answer rather than an error — a read of "have I done
+         * this?" before writing would leave the gap a redelivery arrives in.
+         */
+        const key = {
+            decisionId: decision.id,
+            decisionRevision: decision.revision,
+            action: planned.action,
+        };
+        const claimed = await enforcement.claim({
+            ...key,
+            caseId,
+            subjectType: subject.type,
+            subjectId: subject.id,
+            outcome: decision.outcome,
+            ...(planned.recommendedAction === undefined
+                ? {}
+                : { recommendedAction: planned.recommendedAction }),
+            reason: planned.reason.slice(0, 500),
+            mode,
+            now: new Date(),
+        });
+        if (!claimed) {
+            count(planned.action, mode, 'duplicate');
+            return { action: planned.action, result: 'duplicate' };
+        }
+        if (!modeAllows(mode, planned.action, config)) {
+            await enforcement.markSkipped(key, {
+                skippedReason: mode === 'observe'
+                    ? 'observe mode: recorded, not applied'
+                    : `${mode} mode does not apply '${planned.action}' automatically`,
+                now: new Date(),
+            });
+            count(planned.action, mode, 'recorded');
+            return { action: planned.action, result: 'recorded' };
+        }
+        try {
+            const reversal = await previousStateFor(planned.action, subject);
+            /**
+             * An application with no sanction primitive supplies no `apply`, and every
+             * planned action is recorded with the reason rather than silently
+             * dropped. The plan, the claim and the audit row stay real, so "CrowdSource
+             * decided this and this application has no way to carry it out" is written
+             * down — which is the record that would justify building the primitive.
+             */
+            const noPrimitive = {
+                changed: false,
+                reason: 'This application has no enforcement primitive for any action',
+            };
+            const effect = await (config.apply?.({
+                action: planned.action,
+                subject,
+                ...(reversal ?? {}),
+                decision,
+            }) ?? Promise.resolve(noPrimitive));
+            if (!effect.changed) {
+                /**
+                 * `recordedAs` corrects the LABEL, never the claim. The row keeps the
+                 * planned action because that is half the idempotency key and is what
+                 * was decided; the effective label rides alongside it and is what
+                 * reaches the report.
+                 */
+                await enforcement.markSkipped(key, {
+                    skippedReason: effect.reason.slice(0, 300),
+                    ...(effect.recordedAs === undefined ? {} : { recordedAs: effect.recordedAs }),
+                    now: new Date(),
+                });
+                count(planned.action, mode, 'recorded');
+                return {
+                    action: planned.action,
+                    result: 'recorded',
+                    ...(effect.recordedAs === undefined ? {} : { recordedAs: effect.recordedAs }),
+                };
+            }
+            const appliedAt = new Date();
+            await enforcement.markApplied(key, {
+                appliedAt,
+                ...(effect.previousState === undefined
+                    ? {}
+                    : { previousState: effect.previousState }),
+                now: appliedAt,
+            });
+            count(planned.action, mode, 'applied');
+            return { action: planned.action, result: 'applied' };
+        }
+        catch (error) {
+            /**
+             * The claim goes back so a retry can try again. Keeping it would make a
+             * transient failure permanent: the action would be deduplicated away
+             * forever and the decision would silently never be carried out.
+             */
+            await enforcement.releaseClaim(key);
+            logger.error('[CrowdSource] enforcement effect failed, claim released', {
+                decisionId: decision.id,
+                revision: decision.revision,
+                action: planned.action,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    };
+    return {
+        async apply(applyInput) {
+            const mode = applyInput.mode ?? input.defaultMode;
+            const plan = planEnforcement(applyInput.decision, config);
+            const outcomes = [];
+            for (const planned of plan) {
+                outcomes.push(await applyOne(planned, {
+                    decision: applyInput.decision,
+                    caseId: applyInput.caseId,
+                    subject: applyInput.subject,
+                }, mode));
+            }
+            return outcomes;
+        },
+    };
+}
+//# sourceMappingURL=executor.js.map

package/dist/esm/outbox/enforcement/executor.js.map

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