@de-otio/trellis 0.11.0 → 0.12.0

package/dist/lib/media/moderation-provider.js

@@ -0,0 +1,130 @@
+// CONTRACT: stable — coordinate changes.
+//
+// The MediaModerationProvider capability seam — THE interface every media
+// moderation backend binds to, mirroring the RealtimeTransport seam
+// (apps/api/src/lib/realtime/). Core ships the interface plus a fail-closed
+// Null provider and a test-only Mock; the consuming app (Skybber) injects the
+// concrete cloud adapter at startup. Core imports no cloud SDK.
+//
+// Binding rules for every provider implementor:
+//   - A verdict carries a 3-value `decision` (approved | review | quarantine).
+//     `rejected` is a lifecycle state reached only by human/CSAM action, never a
+//     provider decision (see ModerationStatus state machine).
+//   - Absence of signal, an internal fault, or any uncertainty MUST fail closed
+//     to `review`. A provider must NEVER manufacture `approved` from doubt.
+//   - This interface ships in the PUBLIC npm tarball: NO thresholds, secrets, or
+//     real-category vocabulary live here. Labels carry opaque category tokens;
+//     the operative numeric thresholds are injected via Env (config), not code.
+//   - CSAM detection is deliberately NOT on this interface — it is a separate,
+//     statutory provider with preserve-and-report duties.
+//   - Refs are opaque (key + bucket handle), never raw image/video bytes.
+const NULL_PROVIDER_NAME = "null";
+const NULL_PROVIDER_WARNING = "[NullModerationProvider] No moderation backend injected — failing closed to" +
+    ' decision="review". Media will NOT auto-approve. Inject a real provider in' +
+    " any non-dev environment.";
+/**
+ * A verdict that fails closed: every call resolves to `review` with no labels.
+ * Nothing this provider returns can ever auto-approve media. Used as the safe
+ * default before a concrete provider is injected (dev only — see the startup
+ * guard below).
+ */
+export class NullModerationProvider {
+    warn;
+    constructor(warn = (msg, data) => console.warn(msg, data)) {
+        this.warn = warn;
+    }
+    failClosed() {
+        this.warn(NULL_PROVIDER_WARNING);
+        return { decision: "review", labels: [], provider: NULL_PROVIDER_NAME };
+    }
+    async moderateImage(_input) {
+        return this.failClosed();
+    }
+    async startVideoModeration(_input) {
+        // Even starting a job warns: there is no backend to do the work.
+        this.warn(NULL_PROVIDER_WARNING);
+        return { jobId: `${NULL_PROVIDER_NAME}-noop` };
+    }
+    async getVideoModeration(_jobId) {
+        return this.failClosed();
+    }
+}
+/**
+ * Returns true for the fail-closed Null provider. The startup guard uses this to
+ * reject Null outside dev.
+ */
+export function isNullModerationProvider(provider) {
+    return provider instanceof NullModerationProvider;
+}
+const MOCK_PROVIDER_NAME = "mock";
+const MOCK_DEFAULT_VERDICT = {
+    decision: "review",
+    labels: [],
+    provider: MOCK_PROVIDER_NAME,
+};
+/**
+ * A test seam: returns canned verdicts on demand. Default is the fail-closed
+ * `review`. Labels use ONLY abstract category tokens (`category_a`,
+ * `category_b`); no real-category strings, no real imagery ever.
+ */
+export class MockModerationProvider {
+    imageVerdict;
+    videoVerdict;
+    jobIdSeq = 0;
+    constructor(canned = {}) {
+        this.imageVerdict = canned.image ?? MOCK_DEFAULT_VERDICT;
+        this.videoVerdict = canned.video ?? MOCK_DEFAULT_VERDICT;
+    }
+    /** Program the verdict returned by `moderateImage`. */
+    setImageVerdict(verdict) {
+        this.imageVerdict = verdict;
+    }
+    /** Program the verdict returned by `getVideoModeration`. */
+    setVideoVerdict(verdict) {
+        this.videoVerdict = verdict;
+    }
+    async moderateImage(_input) {
+        return this.imageVerdict;
+    }
+    async startVideoModeration(_input) {
+        this.jobIdSeq += 1;
+        return { jobId: `${MOCK_PROVIDER_NAME}-job-${this.jobIdSeq}` };
+    }
+    async getVideoModeration(_jobId) {
+        return this.videoVerdict;
+    }
+}
+/** Abstract category tokens for Mock verdicts — never real-category strings. */
+export const MOCK_CATEGORY_A = "category_a";
+export const MOCK_CATEGORY_B = "category_b";
+/**
+ * Error raised by the startup guard when the fail-closed Null provider would run
+ * outside dev. Carrying a distinct type lets the wiring fail loudly and lets
+ * tests assert on it.
+ */
+export class NullProviderInProductionError extends Error {
+    constructor(environment) {
+        super(`NullModerationProvider must not run in environment "${environment}" — a` +
+            " real moderation provider must be injected outside dev. Refusing to" +
+            " start: an un-moderated, fail-closed backend in production silently" +
+            " sends all media to review with no path to approval.");
+        this.name = "NullProviderInProductionError";
+    }
+}
+/**
+ * Startup guard for the seam wiring. Validates that a non-Null provider is
+ * injected whenever `environment !== "dev"`, and throws loudly otherwise.
+ * Returns the provider unchanged when the check passes, so it can wrap the
+ * injection site directly:
+ *
+ *   const provider = assertModerationProviderAllowed(injected, env.ENVIRONMENT);
+ *
+ * Fail loud, never silently run Null in prod.
+ */
+export function assertModerationProviderAllowed(provider, environment) {
+    if (environment !== "dev" && isNullModerationProvider(provider)) {
+        throw new NullProviderInProductionError(environment);
+    }
+    return provider;
+}
+//# sourceMappingURL=moderation-provider.js.map

package/dist/lib/media/moderation-provider.js.map

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

package/dist/lib/media/moderation-resolved-payload.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Anti-oracle resolved payload for media moderation.
+ *
+ * When the moderation pipeline settles, downstream consumers (CDN gate,
+ * client notifications) need exactly one bit of information: is this
+ * media object ready to serve? They must NOT receive the verdict, labels,
+ * confidence score, or any other signal that lets a caller infer why a
+ * piece of content was held back — that would publish operational
+ * thresholds and give bad actors a tuning signal.
+ *
+ * This module enforces the anti-oracle contract at the type level: the
+ * payload type has exactly two fields and the constructor function accepts
+ * a full ModerationStatus but discards everything except the binary
+ * ready/not-ready distinction.
+ *
+ * Pure functional core: no I/O, no clock, no randomness. Deterministic
+ * in => deterministic out.
+ */
+import type { ModerationStatus } from "./moderation-status.js";
+/**
+ * The only view of a moderation outcome that leaves the moderation domain.
+ *
+ * Invariants enforced by the type (structural, not just convention):
+ * - Exactly two keys: `mediaId` and `status`. No third key is possible
+ *   without a type error — there is no `decision`, `labels`, `confidence`,
+ *   `reason`, or per-track field.
+ * - `status` is a binary flag: `"ready"` or `"not-ready"`. The caller
+ *   cannot distinguish PENDING from REVIEW from QUARANTINED from REJECTED —
+ *   all four collapse to `"not-ready"`.
+ */
+export interface ModerationResolvedPayload {
+    readonly mediaId: string;
+    readonly status: "ready" | "not-ready";
+}
+/**
+ * Construct the anti-oracle resolved payload from a full ModerationStatus.
+ *
+ * `"ready"` if and only if `status === "APPROVED"`. Every other status —
+ * `PENDING`, `REVIEW`, `QUARANTINED`, `REJECTED` — maps to `"not-ready"`.
+ * The asymmetry is intentional and fail-closed: uncertainty never yields
+ * `"ready"`.
+ *
+ * @param mediaId - The stable identifier of the media object.
+ * @param status  - The settled ModerationStatus (sourced from Env.media /
+ *                  the moderation state machine; never hard-coded here).
+ */
+export declare function moderationResolvedPayload(mediaId: string, status: ModerationStatus): ModerationResolvedPayload;
+//# sourceMappingURL=moderation-resolved-payload.d.ts.map

package/dist/lib/media/moderation-resolved-payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moderation-resolved-payload.d.ts","sourceRoot":"","sources":["../../../src/lib/media/moderation-resolved-payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW,CAAC;CACxC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,gBAAgB,GACvB,yBAAyB,CAK3B"}

package/dist/lib/media/moderation-resolved-payload.js

@@ -0,0 +1,37 @@
+/**
+ * Anti-oracle resolved payload for media moderation.
+ *
+ * When the moderation pipeline settles, downstream consumers (CDN gate,
+ * client notifications) need exactly one bit of information: is this
+ * media object ready to serve? They must NOT receive the verdict, labels,
+ * confidence score, or any other signal that lets a caller infer why a
+ * piece of content was held back — that would publish operational
+ * thresholds and give bad actors a tuning signal.
+ *
+ * This module enforces the anti-oracle contract at the type level: the
+ * payload type has exactly two fields and the constructor function accepts
+ * a full ModerationStatus but discards everything except the binary
+ * ready/not-ready distinction.
+ *
+ * Pure functional core: no I/O, no clock, no randomness. Deterministic
+ * in => deterministic out.
+ */
+/**
+ * Construct the anti-oracle resolved payload from a full ModerationStatus.
+ *
+ * `"ready"` if and only if `status === "APPROVED"`. Every other status —
+ * `PENDING`, `REVIEW`, `QUARANTINED`, `REJECTED` — maps to `"not-ready"`.
+ * The asymmetry is intentional and fail-closed: uncertainty never yields
+ * `"ready"`.
+ *
+ * @param mediaId - The stable identifier of the media object.
+ * @param status  - The settled ModerationStatus (sourced from Env.media /
+ *                  the moderation state machine; never hard-coded here).
+ */
+export function moderationResolvedPayload(mediaId, status) {
+    return {
+        mediaId,
+        status: status === "APPROVED" ? "ready" : "not-ready",
+    };
+}
+//# sourceMappingURL=moderation-resolved-payload.js.map

package/dist/lib/media/moderation-resolved-payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moderation-resolved-payload.js","sourceRoot":"","sources":["../../../src/lib/media/moderation-resolved-payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAoBH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAe,EACf,MAAwB;IAExB,OAAO;QACL,OAAO;QACP,MAAM,EAAE,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW;KACtD,CAAC;AACJ,CAAC"}

package/dist/lib/media/moderation-status.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Media moderation lifecycle: status union, classifier-decision union, and the
+ * pure `nextStatus()` state machine.
+ *
+ * This module is the **hand-written source of truth** for the moderation
+ * lifecycle states. It deliberately has **zero dependency on the
+ * Prisma-generated client** so the serve gate and key-adoption code can compile
+ * in worktrees that have not regenerated the client. The Prisma
+ * `enum ModerationStatus` mirrors {@link ModerationStatus} exactly; the
+ * imperative shell maps `Prisma.MediaFile.moderationStatus -> this union` at the
+ * I/O boundary.
+ *
+ * Pure functional core: no I/O, no clock, no Prisma import. Exhaustively
+ * property-tested.
+ */
+/**
+ * The lifecycle state of a media object's moderation, persisted as
+ * `MediaFile.moderationStatus`. Hand-written source of truth — the Prisma enum
+ * must match this union member-for-member.
+ *
+ * - `PENDING`     — born here; nothing serves until a verdict moves it forward.
+ * - `APPROVED`    — the only state that serves bytes (the gate is APPROVED-only).
+ * - `REVIEW`      — classifier was uncertain; awaiting a human moderator.
+ * - `QUARANTINED` — classifier flagged it; awaiting a human moderator.
+ * - `REJECTED`    — terminal; never serves.
+ */
+export type ModerationStatus = "PENDING" | "APPROVED" | "REVIEW" | "QUARANTINED" | "REJECTED";
+/**
+ * The 3-value classifier verdict (the `decision` field of a moderation
+ * provider's result). This is intentionally **not** 4-value: `rejected` is a
+ * lifecycle *status* a human (or the CSAM provider) produces, never a classifier
+ * decision.
+ */
+export type ModerationDecision = "approved" | "review" | "quarantine";
+/**
+ * Events that drive a `moderationStatus` transition.
+ *
+ * - `decision` — the classifier/worker verdict on a `PENDING` object.
+ * - `human`    — a human moderator resolving a `REVIEW`/`QUARANTINED` object.
+ * - `csam`     — a confirmed hit from the separate (statutory) CSAM provider;
+ *                drives `-> REJECTED` from *any* state, with the preserve-and-
+ *                report duty handled by the shell (a human checkpoint).
+ */
+export type ModerationEvent = {
+    readonly kind: "decision";
+    readonly decision: ModerationDecision;
+} | {
+    readonly kind: "human";
+    readonly action: "approve" | "reject";
+} | {
+    readonly kind: "csam";
+};
+/**
+ * A transition that the state machine refuses. Returned (never thrown) so the
+ * machine stays a pure total function and callers must handle the illegal case
+ * explicitly — an illegal transition must **never** silently no-op into
+ * `APPROVED`.
+ */
+export type IllegalTransition = {
+    readonly ok: false;
+    readonly reason: "illegal-transition";
+    readonly from: ModerationStatus;
+    readonly event: ModerationEvent;
+};
+/** A successful transition to a next status. */
+export type TransitionResult = {
+    readonly ok: true;
+    readonly status: ModerationStatus;
+} | IllegalTransition;
+/**
+ * The pure moderation state machine.
+ *
+ * Transitions (everything else is an {@link IllegalTransition}):
+ *
+ * ```
+ * PENDING            --decision approved-->   APPROVED
+ * PENDING            --decision review-->     REVIEW
+ * PENDING            --decision quarantine--> QUARANTINED
+ * REVIEW|QUARANTINED --human approve-->       APPROVED
+ * REVIEW|QUARANTINED --human reject-->        REJECTED
+ * (any)              --csam-->                REJECTED   (terminal; from any state)
+ * ```
+ *
+ * Invariants (property-tested):
+ * - `APPROVED` and `REJECTED` are absorbing under non-CSAM events.
+ * - A CSAM event drives any state to `REJECTED`.
+ * - `QUARANTINED`/`REJECTED` never reach `APPROVED` without a human approve.
+ * - An illegal transition is reported, never coerced to `APPROVED`.
+ *
+ * @param current the current persisted status
+ * @param event   the driving event
+ */
+export declare function nextStatus(current: ModerationStatus, event: ModerationEvent): TransitionResult;
+/** All lifecycle states, for exhaustive iteration in tests and the shell. */
+export declare const ALL_MODERATION_STATUSES: readonly ModerationStatus[];
+/** All classifier decisions, for exhaustive iteration in tests and the shell. */
+export declare const ALL_MODERATION_DECISIONS: readonly ModerationDecision[];
+//# sourceMappingURL=moderation-status.d.ts.map

package/dist/lib/media/moderation-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moderation-status.d.ts","sourceRoot":"","sources":["../../../src/lib/media/moderation-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,UAAU,GACV,QAAQ,GACR,aAAa,GACb,UAAU,CAAC;AAEf;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,QAAQ,GAAG,YAAY,CAAC;AAEtE;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAA;CAAE,GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CACjC,CAAC;AAEF,gDAAgD;AAChD,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,GACxD,iBAAiB,CAAC;AAwBtB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,eAAe,GACrB,gBAAgB,CAoClB;AA4BD,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,EAAE,SAAS,gBAAgB,EAExC,CAAC;AAExB,iFAAiF;AACjF,eAAO,MAAM,wBAAwB,EAAE,SAAS,kBAAkB,EAIxD,CAAC"}

package/dist/lib/media/moderation-status.js

@@ -0,0 +1,122 @@
+/**
+ * Media moderation lifecycle: status union, classifier-decision union, and the
+ * pure `nextStatus()` state machine.
+ *
+ * This module is the **hand-written source of truth** for the moderation
+ * lifecycle states. It deliberately has **zero dependency on the
+ * Prisma-generated client** so the serve gate and key-adoption code can compile
+ * in worktrees that have not regenerated the client. The Prisma
+ * `enum ModerationStatus` mirrors {@link ModerationStatus} exactly; the
+ * imperative shell maps `Prisma.MediaFile.moderationStatus -> this union` at the
+ * I/O boundary.
+ *
+ * Pure functional core: no I/O, no clock, no Prisma import. Exhaustively
+ * property-tested.
+ */
+/**
+ * Map a classifier decision to the status it drives a `PENDING` object into.
+ *
+ * Fail-closed: any value that is not one of the three known decisions resolves
+ * to `REVIEW` (never `APPROVED`). This is the only place the union is widened —
+ * callers at the I/O boundary may hand us an unexpected provider string, and we
+ * must degrade to human review, not to serving.
+ */
+function statusForDecision(decision) {
+    switch (decision) {
+        case "approved":
+            return "APPROVED";
+        case "review":
+            return "REVIEW";
+        case "quarantine":
+            return "QUARANTINED";
+        default:
+            // Unknown/unexpected decision => fail closed to human review.
+            return "REVIEW";
+    }
+}
+/**
+ * The pure moderation state machine.
+ *
+ * Transitions (everything else is an {@link IllegalTransition}):
+ *
+ * ```
+ * PENDING            --decision approved-->   APPROVED
+ * PENDING            --decision review-->     REVIEW
+ * PENDING            --decision quarantine--> QUARANTINED
+ * REVIEW|QUARANTINED --human approve-->       APPROVED
+ * REVIEW|QUARANTINED --human reject-->        REJECTED
+ * (any)              --csam-->                REJECTED   (terminal; from any state)
+ * ```
+ *
+ * Invariants (property-tested):
+ * - `APPROVED` and `REJECTED` are absorbing under non-CSAM events.
+ * - A CSAM event drives any state to `REJECTED`.
+ * - `QUARANTINED`/`REJECTED` never reach `APPROVED` without a human approve.
+ * - An illegal transition is reported, never coerced to `APPROVED`.
+ *
+ * @param current the current persisted status
+ * @param event   the driving event
+ */
+export function nextStatus(current, event) {
+    // CSAM is terminal from any state — checked first so it overrides every
+    // absorbing/illegal rule below.
+    if (event.kind === "csam") {
+        return { ok: true, status: "REJECTED" };
+    }
+    switch (current) {
+        case "PENDING": {
+            // Only the classifier acts on a freshly-uploaded object.
+            if (event.kind === "decision") {
+                return { ok: true, status: statusForDecision(event.decision) };
+            }
+            return illegal(current, event);
+        }
+        case "REVIEW":
+        case "QUARANTINED": {
+            // Only a human moderator resolves these.
+            if (event.kind === "human") {
+                return {
+                    ok: true,
+                    status: event.action === "approve" ? "APPROVED" : "REJECTED",
+                };
+            }
+            return illegal(current, event);
+        }
+        case "APPROVED":
+        case "REJECTED":
+            // Absorbing under any non-CSAM event.
+            return illegal(current, event);
+        default:
+            return illegal(current, event);
+    }
+}
+function illegal(from, event) {
+    return { ok: false, reason: "illegal-transition", from, event };
+}
+/**
+ * Compile-time exhaustiveness guard for {@link ModerationStatus}.
+ *
+ * Keyed by the union, so adding a member to `ModerationStatus` without adding it
+ * here is a TYPE error (TS2741 "missing key"), and a stale key that is no longer
+ * a union member is a TYPE error too. This makes it impossible for
+ * {@link ALL_MODERATION_STATUSES} below to silently drift from the union — a
+ * drift that would let a new, un-enumerated status bypass the exhaustive
+ * anti-oracle property tests (which iterate this array). Pure type-level, no
+ * behavior.
+ */
+const MODERATION_STATUS_MEMBERS = {
+    PENDING: true,
+    APPROVED: true,
+    REVIEW: true,
+    QUARANTINED: true,
+    REJECTED: true,
+};
+/** All lifecycle states, for exhaustive iteration in tests and the shell. */
+export const ALL_MODERATION_STATUSES = Object.keys(MODERATION_STATUS_MEMBERS);
+/** All classifier decisions, for exhaustive iteration in tests and the shell. */
+export const ALL_MODERATION_DECISIONS = [
+    "approved",
+    "review",
+    "quarantine",
+];
+//# sourceMappingURL=moderation-status.js.map

package/dist/lib/media/moderation-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moderation-status.js","sourceRoot":"","sources":["../../../src/lib/media/moderation-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA4DH;;;;;;;GAOG;AACH,SAAS,iBAAiB,CAAC,QAA4B;IACrD,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,UAAU;YACb,OAAO,UAAU,CAAC;QACpB,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;QAClB,KAAK,YAAY;YACf,OAAO,aAAa,CAAC;QACvB;YACE,8DAA8D;YAC9D,OAAO,QAAQ,CAAC;IACpB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,UAAU,CACxB,OAAyB,EACzB,KAAsB;IAEtB,wEAAwE;IACxE,gCAAgC;IAChC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC1B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC1C,CAAC;IAED,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,yDAAyD;YACzD,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBAC9B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,iBAAiB,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjE,CAAC;YACD,OAAO,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACjC,CAAC;QAED,KAAK,QAAQ,CAAC;QACd,KAAK,aAAa,CAAC,CAAC,CAAC;YACnB,yCAAyC;YACzC,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBAC3B,OAAO;oBACL,EAAE,EAAE,IAAI;oBACR,MAAM,EAAE,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU;iBAC7D,CAAC;YACJ,CAAC;YACD,OAAO,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACjC,CAAC;QAED,KAAK,UAAU,CAAC;QAChB,KAAK,UAAU;YACb,sCAAsC;YACtC,OAAO,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAEjC;YACE,OAAO,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACnC,CAAC;AACH,CAAC;AAED,SAAS,OAAO,CACd,IAAsB,EACtB,KAAsB;IAEtB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAClE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,yBAAyB,GAAG;IAChC,OAAO,EAAE,IAAI;IACb,QAAQ,EAAE,IAAI;IACd,MAAM,EAAE,IAAI;IACZ,WAAW,EAAE,IAAI;IACjB,QAAQ,EAAE,IAAI;CACmC,CAAC;AAEpD,6EAA6E;AAC7E,MAAM,CAAC,MAAM,uBAAuB,GAAgC,MAAM,CAAC,IAAI,CAC7E,yBAAyB,CACJ,CAAC;AAExB,iFAAiF;AACjF,MAAM,CAAC,MAAM,wBAAwB,GAAkC;IACrE,UAAU;IACV,QAAQ;IACR,YAAY;CACJ,CAAC"}

package/dist/lib/media/processing-types.d.ts

@@ -0,0 +1,45 @@
+import type { Track } from "./track-verdict.js";
+/**
+ * A unit of work the processing worker dequeues for one uploaded object.
+ *
+ * - `tenantId` — owning tenant (CUID; validated by ./cas-keys.ts before use).
+ * - `uploadId` — the upload session id (CUID).
+ * - `key`      — the staging/pending storage key the bytes currently live at
+ *                (built ONLY via ./cas-keys.ts `pendingKey`).
+ */
+export interface ProcessingJob {
+    readonly tenantId: string;
+    readonly uploadId: string;
+    readonly key: string;
+}
+/**
+ * The outcome of processing one object.
+ *
+ * - `casKey`      — the canonical content-addressed key the cleaned bytes were
+ *                   stored at (built via ./cas-keys.ts `casKey`).
+ * - `contentHash` — the 64-char lowercase SHA-256 of the cleaned bytes (the CAS
+ *                   address; validated by ./cas-keys.ts `validateContentHash`).
+ * - `visualJobId` — async moderation job handle for the VISUAL track, when a
+ *                   visual track was started; absent for audio-only objects.
+ * - `audioJobId`  — async transcription/moderation handle for the AUDIO track,
+ *                   when an audio track was started; absent for objects with no
+ *                   audio.
+ */
+export interface ProcessingResult {
+    readonly casKey: string;
+    readonly contentHash: string;
+    readonly visualJobId?: string;
+    readonly audioJobId?: string;
+}
+/**
+ * Input to the per-track dedupe key the worker uses to idempotently fan out /
+ * fan in async track jobs without double-processing. Keyed by the content hash
+ * (so identical bytes share work), the provider/transcription job id, and which
+ * track it is — so the VISUAL and AUDIO tracks of the same bytes never collide.
+ */
+export interface DedupeKeyInput {
+    readonly contentHash: string;
+    readonly jobId: string;
+    readonly track: Track;
+}
+//# sourceMappingURL=processing-types.d.ts.map

package/dist/lib/media/processing-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processing-types.d.ts","sourceRoot":"","sources":["../../../src/lib/media/processing-types.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB"}

package/dist/lib/media/processing-types.js

@@ -0,0 +1,9 @@
+// CONTRACT: stable — coordinate changes. Shared P0b processing value types.
+//
+// Pure data contracts that thread a media object through the processing
+// pipeline: the job the worker dequeues, the result it produces, and the input
+// to the per-track dedupe key. NO behavior here — just the shapes the shell and
+// the functional-core units agree on. Ships in the PUBLIC npm tarball: no
+// thresholds, secrets, or real-category vocabulary.
+export {};
+//# sourceMappingURL=processing-types.js.map

package/dist/lib/media/processing-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processing-types.js","sourceRoot":"","sources":["../../../src/lib/media/processing-types.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,wEAAwE;AACxE,+EAA+E;AAC/E,gFAAgF;AAChF,0EAA0E;AAC1E,oDAAoD"}

package/dist/lib/media/promote-decision.d.ts

@@ -0,0 +1,64 @@
+import { type TrackOutcome } from "./track-verdict.js";
+import { type ModerationDecision, type ModerationStatus, type TransitionResult } from "./moderation-status.js";
+/**
+ * Everything {@link decidePromotion} needs to decide the worker's action.
+ *
+ * - `visual` / `audio` — the per-track outcomes (see {@link TrackOutcome}).
+ * - `currentStatus`    — the object's persisted moderation status *before* this
+ *                        decision is applied. Used to detect replay / illegal
+ *                        transitions (terminal states absorb).
+ * - `casObjectPresent` — whether the content-addressed object actually exists in
+ *                        durable storage. Approval alone must not serve bytes
+ *                        that are not there; promotion is gated on presence.
+ */
+export interface PromotionInput {
+    readonly visual: TrackOutcome;
+    readonly audio: TrackOutcome;
+    readonly currentStatus: ModerationStatus;
+    readonly casObjectPresent: boolean;
+}
+/**
+ * The worker's decided action. All side effects are reported as booleans; the
+ * shell performs them in the fixed order promote -> persist -> emit.
+ *
+ * - `combined`          — the object-level decision from {@link combineTrackVerdicts}.
+ * - `transition`        — the result of running `combined` through the state
+ *                         machine from `currentStatus`. `ok:false` means the
+ *                         transition is illegal (e.g. replay on a terminal
+ *                         status) and the action is a no-op.
+ * - `shouldPromote`     — adopt/publish the CAS object so it can serve. True
+ *                         IFF the transition is legal AND lands on APPROVED AND
+ *                         the CAS object is present.
+ * - `shouldPersistStatus` — write the new status. True IFF the transition is legal.
+ * - `shouldEmitResolved`  — emit the "resolved" event. True IFF the transition is legal.
+ */
+export interface PromotionAction {
+    readonly combined: ModerationDecision;
+    readonly transition: TransitionResult;
+    readonly shouldPromote: boolean;
+    readonly shouldPersistStatus: boolean;
+    readonly shouldEmitResolved: boolean;
+}
+/**
+ * Decide the worker's action for a media object whose tracks have both resolved.
+ *
+ * Logic (total):
+ *  1. `combined = combineTrackVerdicts(visual, audio)` — fail-closed track join.
+ *  2. `transition = nextStatus(currentStatus, { kind: "decision", decision: combined })`.
+ *  3. If `transition.ok === false` (illegal — e.g. replay on a terminal status):
+ *     idempotent NO-OP — `shouldPromote`/`shouldPersistStatus`/`shouldEmitResolved`
+ *     are all `false`.
+ *  4. If `transition.ok === true`:
+ *       - `shouldPersistStatus = true`
+ *       - `shouldEmitResolved  = true`
+ *       - `shouldPromote = transition.status === "APPROVED" && casObjectPresent`
+ *
+ * Safety invariants (property-tested):
+ *  - `shouldPromote === true` ⇒ BOTH tracks were decided-and-approved AND the
+ *    resulting status is APPROVED. Promotion never happens from doubt.
+ *  - APPROVED is never reached unless both tracks are decided-approved.
+ *  - A replay/illegal transition on a terminal status yields an all-false no-op.
+ *  - `casObjectPresent === false` ⇒ `shouldPromote === false`, even at APPROVED.
+ */
+export declare function decidePromotion(input: PromotionInput): PromotionAction;
+//# sourceMappingURL=promote-decision.d.ts.map

package/dist/lib/media/promote-decision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promote-decision.d.ts","sourceRoot":"","sources":["../../../src/lib/media/promote-decision.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACtB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,gBAAgB,CAAC;IACzC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CAiCtE"}