@crowdsource.you/core 1.2.0

package/src/outbox/enforcement/executor.ts

@@ -0,0 +1,288 @@
+import type { Decision } from '@crowdsource.you/contracts';
+import { planEnforcement } from './planner.js';
+import type {
+  ModerationEnforcementKey,
+  ModerationEnforcementStore,
+} from '../store/types.js';
+import type {
+  EnforcementEffect,
+  EnforcementOutcome,
+  EnforcementPreviousState,
+  EnforcementSubject,
+  ModerationEnforcementConfig,
+  ModerationEnforcementMode,
+  ModerationLogger,
+  ModerationMetrics,
+  PlannedEnforcementAction,
+} from '../types.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<TAction extends string>(
+  mode: ModerationEnforcementMode,
+  action: TAction,
+  config: ModerationEnforcementConfig<TAction>,
+): boolean {
+  switch (mode) {
+    case 'observe':
+      return false;
+    case 'manual':
+      return (config.reversibleActions ?? []).includes(action);
+    case 'automatic':
+      return true;
+  }
+}
+
+export interface EnforcementExecutor<TAction extends string> {
+  /**
+   * Plan and carry out everything this decision revision asks for.
+   *
+   * Returns one outcome per planned action, in plan order, so a caller can
+   * record what happened without asking a second time.
+   */
+  apply(input: {
+    decision: Decision;
+    caseId: string;
+    subject: EnforcementSubject;
+    /** Defaults to the configured mode. Explicit in tests. */
+    mode?: ModerationEnforcementMode;
+  }): Promise<EnforcementOutcome<TAction>[]>;
+}
+
+export function createEnforcementExecutor<TAction extends string>(input: {
+  enforcement: ModerationEnforcementStore;
+  config: ModerationEnforcementConfig<TAction>;
+  defaultMode: ModerationEnforcementMode;
+  logger: ModerationLogger;
+  metrics?: ModerationMetrics;
+}): EnforcementExecutor<TAction> {
+  const { enforcement, config, logger } = input;
+
+  const count = (
+    action: TAction,
+    mode: ModerationEnforcementMode,
+    result: string,
+  ): void => {
+    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: TAction,
+    subject: EnforcementSubject,
+  ): Promise<
+    { previousState?: EnforcementPreviousState; previousAction: TAction } | undefined
+  > => {
+    const reversed: TAction | readonly TAction[] | undefined = 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: readonly TAction[] =
+      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: PlannedEnforcementAction<TAction>,
+    context: { decision: Decision; caseId: string; subject: EnforcementSubject },
+    mode: ModerationEnforcementMode,
+  ): Promise<EnforcementOutcome<TAction>> => {
+    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: ModerationEnforcementKey = {
+      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: EnforcementEffect<TAction> = {
+        changed: false,
+        reason: 'This application has no enforcement primitive for any action',
+      };
+      const effect: EnforcementEffect<TAction> = 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: unknown) {
+      /**
+       * 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: EnforcementOutcome<TAction>[] = [];
+      for (const planned of plan) {
+        outcomes.push(
+          await applyOne(
+            planned,
+            {
+              decision: applyInput.decision,
+              caseId: applyInput.caseId,
+              subject: applyInput.subject,
+            },
+            mode,
+          ),
+        );
+      }
+      return outcomes;
+    },
+  };
+}

package/src/outbox/enforcement/planner.ts

@@ -0,0 +1,377 @@
+import type { Decision, RecommendedAction, Severity } from '@crowdsource.you/contracts';
+import type { ModerationEnforcementConfig, PlannedEnforcementAction } from '../types.js';
+
+/**
+ * Deciding what an application will do about a decision — and nothing else.
+ *
+ * Pure: no database, no clock, no configuration. A decision in, a plan out. That
+ * is what makes the mapping testable as a table rather than as an integration
+ * scenario, and it is why `observe` mode is a real audit rather than a comment —
+ * the plan is computed identically in every mode and only its EXECUTION is
+ * gated.
+ *
+ * ## The application maps recommendations, not findings
+ *
+ * `decision.recommendedActions` is what this reads, falling back to severity
+ * only when a violation arrives with no recommendation at all.
+ *
+ * The reason is a division of labour: the jury classified the material and the
+ * consensus engine turned that into a recommendation under a versioned policy.
+ * An application that re-derived its action from raw severity would be quietly
+ * re-deciding the case with a second, unversioned policy of its own — and the
+ * two would diverge the first time CrowdSource's policy was updated. The
+ * fallback exists because a `violation` the application did nothing about would
+ * be worse than a mapped one.
+ *
+ * ## Why this ALGORITHM is shared and only the TABLES are per-application
+ *
+ * Every application has different actions, so the tables have to be its own. The
+ * algorithm must not be, because it carries a correctness property that is
+ * invisible by construction — see {@link withRestoreForNoViolation}. An
+ * application writing its own planner is a chance to ship that bug silently, and
+ * no test written against the application's own mapping would catch it.
+ */
+
+const SEVERITY_ORDER: readonly Severity[] = ['low', 'medium', 'high', 'critical'];
+
+/**
+ * Recommendations that ask for NO effect.
+ *
+ * An unmapped recommendation goes to `reviewAction`, because a recommendation
+ * this application has no action for is a decision a human should see. These
+ * three are the exception, and the distinction is not cosmetic: they are
+ * CrowdSource saying "take no action", so routing them to review would put a
+ * human in front of every cleared case and bury the ones that need looking at.
+ *
+ * An application's own table still wins — it may genuinely want `allow` to mean
+ * something — but the default for an application that maps nothing has to be
+ * "do nothing" rather than "wake somebody".
+ */
+const NO_EFFECT_RECOMMENDATIONS: ReadonlySet<string> = new Set([
+  'allow',
+  'no_action',
+  'no_global_effect',
+]);
+
+function actionForRecommendation<TAction extends string>(
+  recommended: RecommendedAction,
+  config: ModerationEnforcementConfig<TAction>,
+): TAction {
+  const mapped = config.recommendationToAction?.[recommended];
+  if (mapped !== undefined) return mapped;
+  return NO_EFFECT_RECOMMENDATIONS.has(recommended)
+    ? config.noneAction
+    : config.reviewAction;
+}
+
+function highestSeverity(decision: Decision): Severity | undefined {
+  let highest: Severity | undefined;
+  for (const finding of decision.findings) {
+    if (
+      highest === undefined ||
+      SEVERITY_ORDER.indexOf(finding.severity) > SEVERITY_ORDER.indexOf(highest)
+    ) {
+      highest = finding.severity;
+    }
+  }
+  return highest;
+}
+
+/**
+ * `no_violation` always carries a restore, whatever it recommended.
+ *
+ * This exists because of a failure that is very easy to ship and very hard to
+ * see. A correction is a new revision whose outcome is `no_violation`, and its
+ * recommendation is frequently `no_action` — which is CrowdSource saying "take
+ * no NEW action", not "leave what you already did in place". Mapping that
+ * straight through plans nothing, and the object an earlier revision removed
+ * stays removed forever: the appeal succeeded, the case says the content was
+ * fine, and nothing in the application ever puts it back. No error, no log line,
+ * no failing test anywhere else.
+ *
+ * `allow`, `restore` and `no_action` are listed together as an application's
+ * options for `no_violation` precisely because choosing between them needs
+ * knowledge only the application has — whether it did something earlier. So the
+ * plan always includes the restore, and the executor records "there was nothing
+ * restricted" when that is the case, which is evidence rather than a silent
+ * no-op.
+ */
+function restoreActions<TAction extends string>(
+  declared: TAction | readonly TAction[] | null,
+): readonly TAction[] {
+  if (declared === null) return [];
+  return typeof declared === 'string' ? [declared] : declared;
+}
+
+function withRestoreForNoViolation<TAction extends string>(
+  decision: Decision,
+  planned: readonly PlannedEnforcementAction<TAction>[],
+  declared: TAction | readonly TAction[] | null,
+): readonly PlannedEnforcementAction<TAction>[] {
+  /**
+   * `null` is a decision the application made, not an omission — the type
+   * requires it to be written down. An application with no sanction primitive
+   * has nothing an earlier revision could have removed, so there is nothing for
+   * a correction to put back.
+   */
+  if (decision.outcome !== 'no_violation') return planned;
+  /**
+   * EVERY declared restore, not just the first. An application whose levers are
+   * "hide it" and "label it" has two things a correction must undo, and planning
+   * one leaves the other stuck forever — the object is un-hidden and stays
+   * labelled, with no error and nothing failing. That is the same failure this
+   * function exists to prevent, applied to the second reversible action instead
+   * of the first.
+   *
+   * A restore with nothing to undo is not waste: the executor records
+   * `changed: false` with its reason, which is evidence that it was checked.
+   */
+  const missing = restoreActions(declared).filter(
+    (action) => !planned.some((entry) => entry.action === action),
+  );
+  if (missing.length === 0) return planned;
+  return [
+    ...planned,
+    ...missing.map((action) => ({
+      action,
+      reason: 'No violation: undo any earlier restriction',
+    })),
+  ];
+}
+
+/**
+ * Collapse a plan to the actions that can coexist.
+ *
+ * A decision may recommend both removal and a label; a removed object does not
+ * need one, and recording both would claim two effects where one happened. So an
+ * action absorbs whatever the application declared it absorbs, and the explicit
+ * "nothing" never survives alongside anything else.
+ *
+ * `reviewAction` always survives — it is a note for a human, and dropping it
+ * because something else was also done is how a `suspend_user` recommendation
+ * gets lost.
+ */
+function collapse<TAction extends string>(
+  actions: readonly PlannedEnforcementAction<TAction>[],
+  config: ModerationEnforcementConfig<TAction>,
+): PlannedEnforcementAction<TAction>[] {
+  const byAction = new Map<TAction, PlannedEnforcementAction<TAction>>();
+  for (const planned of actions) {
+    if (!byAction.has(planned.action)) byAction.set(planned.action, planned);
+  }
+
+  for (const [action, absorbed] of Object.entries(config.absorb ?? {}) as [
+    TAction,
+    readonly TAction[] | undefined,
+  ][]) {
+    if (!byAction.has(action)) continue;
+    for (const loser of absorbed ?? []) {
+      if (loser === config.reviewAction) continue;
+      byAction.delete(loser);
+    }
+  }
+
+  if (byAction.size > 1) byAction.delete(config.noneAction);
+
+  return Array.from(byAction.values());
+}
+
+/**
+ * What the application will do about this decision.
+ *
+ * Never empty: a decision that produces no action produces an explicit
+ * `noneAction`, because a row saying "we decided to do nothing, and why" is
+ * evidence and an absent row is a question.
+ */
+/**
+ * Raised when `restoreAction` names actions that are being UNDONE rather than
+ * actions that DO the undoing.
+ *
+ * A doc line is not enough for this one. An inverted `restoreAction` type-checks
+ * — both directions are `TAction[]` — and it does not fail at runtime either: it
+ * plans, it claims, and it applies a restriction and a label on an accepted
+ * appeal. It succeeds at the opposite thing, on the one path whose whole purpose
+ * is to give something back.
+ *
+ * The signal is unambiguous when it exists. `reverses` maps each undoing action
+ * to what it undoes, so its VALUES are targets and its KEYS are actors. An
+ * action that appears only as a target has been declared as a restore by
+ * someone reading the targets, which is exactly the mistake this catches.
+ *
+ * Deliberately narrow: an action absent from `reverses` entirely is fine (it may
+ * undo something needing no previous state), and one that is both a key and a
+ * value is fine (it undoes and is undone). Only "a target, and never an actor"
+ * is reported, so a correct configuration cannot trip it.
+ */
+export class ModerationRestoreDirectionError extends Error {
+  constructor(inverted: readonly string[]) {
+    super(
+      `restoreAction names [${inverted.join(', ')}], which 'reverses' lists as actions ` +
+        'being UNDONE rather than actions that do the undoing. restoreAction holds what ' +
+        "the planner emits on 'no_violation' — the restoring actions, e.g. " +
+        "['restore', 'unlabel_sensitive'] — not the restrictions being lifted. As written, " +
+        'an accepted appeal would apply the punishment it was correcting.',
+    );
+    this.name = 'ModerationRestoreDirectionError';
+  }
+}
+
+/**
+ * Refuse an inverted `restoreAction` at construction rather than at the first
+ * correction, which may be weeks later and reads as a moderation decision
+ * rather than a configuration error.
+ */
+export function assertRestoreDirection<TAction extends string>(
+  config: ModerationEnforcementConfig<TAction>,
+): void {
+  const reverses: Partial<Record<TAction, TAction | readonly TAction[]>> =
+    config.reverses ?? {};
+  const entries = Object.entries(reverses) as [
+    TAction,
+    TAction | readonly TAction[] | undefined,
+  ][];
+  const actors = new Set<string>(entries.map(([actor]) => actor));
+  const targets = new Set<string>();
+  for (const [, undone] of entries) {
+    if (undone === undefined) continue;
+    for (const action of typeof undone === 'string' ? [undone] : undone) {
+      targets.add(action);
+    }
+  }
+  const inverted = restoreActions(config.restoreAction).filter(
+    (action) => targets.has(action) && !actors.has(action),
+  );
+  if (inverted.length > 0) throw new ModerationRestoreDirectionError(inverted);
+}
+
+export function planEnforcement<TAction extends string>(
+  decision: Decision,
+  config: ModerationEnforcementConfig<TAction>,
+): PlannedEnforcementAction<TAction>[] {
+  const fromRecommendations = decision.recommendedActions.map(
+    (recommended): PlannedEnforcementAction<TAction> => ({
+      action: actionForRecommendation(recommended.action, config),
+      reason: `CrowdSource recommended ${recommended.action}`,
+      recommendedAction: recommended.action,
+    }),
+  );
+
+  if (fromRecommendations.length > 0) {
+    const collapsed = collapse(
+      withRestoreForNoViolation(decision, fromRecommendations, config.restoreAction),
+      config,
+    );
+    return collapsed.length > 0
+      ? collapsed
+      : [
+          {
+            action: config.noneAction,
+            reason: 'No recommended action maps to an effect this application has',
+          },
+        ];
+  }
+
+  switch (decision.outcome) {
+    case 'violation': {
+      const severity = highestSeverity(decision);
+      /**
+       * A `violation` with no findings cannot happen — the contract refuses it —
+       * so an absent severity here means a newer CrowdSource sent something this
+       * code has not seen. A human looks at it rather than a default removing an
+       * object.
+       */
+      if (severity === undefined) {
+        return [
+          {
+            action: config.reviewAction,
+            reason: 'Violation carried no finding severity this version understands',
+          },
+        ];
+      }
+      return [
+        {
+          action: config.severityFallback?.[severity] ?? config.reviewAction,
+          reason: `Violation with no recommended action, highest severity ${severity}`,
+        },
+      ];
+    }
+
+    case 'no_violation':
+      /**
+       * A restore, always planned — even when nothing was restricted. The
+       * executor records it as not applied with the reason, which is how "we
+       * checked and there was nothing to undo" is distinguishable from "we never
+       * looked".
+       */
+      {
+        const declared = restoreActions(config.restoreAction);
+        return declared.length === 0
+          ? [
+              {
+                action: config.noneAction,
+                reason: 'No violation, and this application has nothing to restore',
+              },
+            ]
+          : declared.map((action) => ({
+              action,
+              reason: 'No violation: undo any earlier restriction',
+            }));
+      }
+
+    case 'insufficient_context':
+    case 'inconclusive':
+    case 'escalated':
+      /**
+       * None of these is "remove", and none is "it was fine": absence of
+       * consensus is neither guilt nor innocence, so the application changes
+       * nothing on its own and asks a human.
+       */
+      return [
+        {
+          action: config.reviewAction,
+          reason: `Outcome ${decision.outcome}: no automatic action, internal review`,
+        },
+      ];
+
+    case 'content_unavailable':
+    case 'duplicate':
+      return [
+        {
+          action: config.noneAction,
+          reason: `Outcome ${decision.outcome}: nothing to enforce`,
+        },
+      ];
+
+    default:
+      /**
+       * An outcome the contract does not currently define. A newer server must
+       * not break an older client, and the safe reading of an unknown outcome is
+       * a human, never a default effect.
+       */
+      return [
+        {
+          action: config.reviewAction,
+          reason: 'Decision outcome not recognised by this version of the application',
+        },
+      ];
+  }
+}
+
+/**
+ * The one action worth recording on the report.
+ *
+ * One field, several planned actions, so it has to be the one that answers "what
+ * happened to this object". The application's `precedence` decides, strongest
+ * first — and `reviewAction` should sit near the end but ABOVE `noneAction`,
+ * because a reporter told "nothing happened" when a human is about to look is
+ * being told something untrue.
+ */
+export function primaryAction<TAction extends string>(
+  actions: readonly TAction[],
+  precedence: readonly TAction[],
+): TAction | undefined {
+  for (const candidate of precedence) {
+    if (actions.includes(candidate)) return candidate;
+  }
+  return actions[0];
+}