@jini-ai/cms 0.3.11 → 0.4.0

package/dist/media/html-attributes.d.ts

@@ -1,17 +1,17 @@
 /**
  * @file Server-side allowlist for `MediaRecord.htmlAttributes` (2026-09-07) — the enforcement half
  * of a validator that ALSO has a browser-side copy in the consuming product's admin
- * (`apps/admin/src/features/media/rules.ts`, `parseMediaHtmlAttributes` and friends).
+ * (its attribute parser and related rules).
  *
  * Deliberately duplicated, not shared via one imported module, for the same reason this codebase
  * already hand-copies `DEFAULT_ALLOWED_MIME_TYPES` into that admin's `FILE_HANDLER_ALLOWED_MIME_TYPES`/
  * `IMPORTABLE_CONTENT_TYPES`: `@jini-ai/cms/media`'s barrel (`index.ts`) re-exports files that
  * import real Node built-ins (`node:crypto` in `media-service.ts`, `node:fs` in
  * `blob-store.fs.ts`, native `sharp` bindings in `image-transformer.sharp.ts`) — importing this
- * subpath from a browser-bundled Vite app (that product's `apps/admin`) risks pulling those into the admin
+ * subpath from a browser-bundled admin app risks pulling those into the admin
  * SPA's bundle even if only this one pure function is actually used, and this admin's own copy
  * already exists, tested, with no such risk. This file is the copy every Node-side consumer
- * (`media-service.ts`'s own `updateMediaMetadata`, and that product's `apps/website` render path, both pure
+ * (`media-service.ts`'s own `updateMediaMetadata`, and the host's render path, both pure
  * backend code) can safely import from `@jini-ai/cms/media` instead of re-deriving the rules a
  * third time.
  *
@@ -45,7 +45,9 @@ export declare const MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES: readonly ["loading", "d
  * @complexity O(n) in the name's length (one anchored regex test), then O(1) — one prefix check,
  * one fixed-length array lookup.
  */
-export declare function isAllowedMediaHtmlAttributeName(name: string): boolean;
+export declare function isAllowedMediaHtmlAttributeName(requiredArgs: {
+    name: string;
+}, optionalArgs?: Record<string, never>): boolean;
 /** Why one parsed attribute token was rejected — see {@link parseMediaHtmlAttributes}'s own doc for
  *  why `event-handler`/`javascript-url` are checked, and reported, ahead of plain allowlist
  *  membership. */
@@ -76,7 +78,9 @@ export interface ParsedMediaHtmlAttributes {
  * @complexity Time O(n) in `text`'s length (one regex pass over it), space O(k) for k parsed
  *   attributes.
  */
-export declare function parseMediaHtmlAttributes(text: string): ParsedMediaHtmlAttributes;
+export declare function parseMediaHtmlAttributes(requiredArgs: {
+    text: string;
+}, optionalArgs?: Record<string, never>): ParsedMediaHtmlAttributes;
 /** Formats a {@link MediaHtmlAttributeError} into a plain-English message naming the rejected
  *  attribute (owner requirement) — the server-side, non-localized counterpart to the admin's own
  *  `describeMediaHtmlAttributeError` (which additionally runs the message through `MEDIA_DICT` for

package/dist/media/html-attributes.js

@@ -1,17 +1,17 @@
 /**
  * @file Server-side allowlist for `MediaRecord.htmlAttributes` (2026-09-07) — the enforcement half
  * of a validator that ALSO has a browser-side copy in the consuming product's admin
- * (`apps/admin/src/features/media/rules.ts`, `parseMediaHtmlAttributes` and friends).
+ * (its attribute parser and related rules).
  *
  * Deliberately duplicated, not shared via one imported module, for the same reason this codebase
  * already hand-copies `DEFAULT_ALLOWED_MIME_TYPES` into that admin's `FILE_HANDLER_ALLOWED_MIME_TYPES`/
  * `IMPORTABLE_CONTENT_TYPES`: `@jini-ai/cms/media`'s barrel (`index.ts`) re-exports files that
  * import real Node built-ins (`node:crypto` in `media-service.ts`, `node:fs` in
  * `blob-store.fs.ts`, native `sharp` bindings in `image-transformer.sharp.ts`) — importing this
- * subpath from a browser-bundled Vite app (that product's `apps/admin`) risks pulling those into the admin
+ * subpath from a browser-bundled admin app risks pulling those into the admin
  * SPA's bundle even if only this one pure function is actually used, and this admin's own copy
  * already exists, tested, with no such risk. This file is the copy every Node-side consumer
- * (`media-service.ts`'s own `updateMediaMetadata`, and that product's `apps/website` render path, both pure
+ * (`media-service.ts`'s own `updateMediaMetadata`, and the host's render path, both pure
  * backend code) can safely import from `@jini-ai/cms/media` instead of re-deriving the rules a
  * third time.
  *
@@ -72,7 +72,8 @@ const MEDIA_HTML_ATTRIBUTE_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
  * @complexity O(n) in the name's length (one anchored regex test), then O(1) — one prefix check,
  * one fixed-length array lookup.
  */
-export function isAllowedMediaHtmlAttributeName(name) {
+export function isAllowedMediaHtmlAttributeName(requiredArgs, optionalArgs = {}) {
+    const { name } = requiredArgs;
     const lower = name.toLowerCase();
     if (!MEDIA_HTML_ATTRIBUTE_NAME_PATTERN.test(lower))
         return false;
@@ -98,7 +99,7 @@ function classifyMediaHtmlAttributeToken(name, value) {
         return { reason: "event-handler", attribute: name };
     if (value.trim().toLowerCase().startsWith("javascript:"))
         return { reason: "javascript-url", attribute: name };
-    if (!isAllowedMediaHtmlAttributeName(name))
+    if (!isAllowedMediaHtmlAttributeName({ name: name }))
         return { reason: "disallowed-name", attribute: name };
     return null;
 }
@@ -112,7 +113,8 @@ function classifyMediaHtmlAttributeToken(name, value) {
  * @complexity Time O(n) in `text`'s length (one regex pass over it), space O(k) for k parsed
  *   attributes.
  */
-export function parseMediaHtmlAttributes(text) {
+export function parseMediaHtmlAttributes(requiredArgs, optionalArgs = {}) {
+    const { text } = requiredArgs;
     const trimmed = text.trim();
     if (trimmed === "")
         return { attributes: {}, error: null };

package/dist/media/image-transformer.js

@@ -17,7 +17,7 @@ export class InMemoryImageTransformer {
         const output = new Uint8Array(tagBytes.length + input.bytes.length);
         output.set(tagBytes, 0);
         output.set(input.bytes, tagBytes.length);
-        return { bytes: output, contentType: mimeForTransformFormat(input.params.format) };
+        return { bytes: output, contentType: mimeForTransformFormat({ format: input.params.format }) };
     }
 }
 //# sourceMappingURL=image-transformer.js.map

package/dist/media/image-transformer.sharp.d.ts

@@ -1,6 +1,9 @@
 import type { ImageTransformerPort, TransformImageInput, TransformImageOutput } from "./image-transformer.js";
 /** Thrown by {@link SharpImageTransformer.transform} when the `sharp` package cannot be loaded. */
 export declare class ImageTransformUnavailableError extends Error {
+    constructor({ message }: {
+        message: string;
+    }, optionalArgs?: ErrorOptions);
 }
 /**
  * Thrown by {@link SharpImageTransformer.transform} when `sharp` itself rejects the SOURCE bytes —
@@ -17,6 +20,9 @@ export declare class ImageTransformUnavailableError extends Error {
  * states for the sibling `ImageTransformUnavailableError` case.
  */
 export declare class ImageSourceCorruptError extends Error {
+    constructor({ message }: {
+        message: string;
+    }, optionalArgs?: ErrorOptions);
 }
 /**
  * Real `ImageTransformerPort` adapter. Applies `params.width`/`height`

package/dist/media/image-transformer.sharp.js

@@ -32,6 +32,9 @@ import { mimeForTransformFormat } from "./transform-types.js";
 const require = createRequire(import.meta.url);
 /** Thrown by {@link SharpImageTransformer.transform} when the `sharp` package cannot be loaded. */
 export class ImageTransformUnavailableError extends Error {
+    constructor({ message }, optionalArgs = {}) {
+        super(message, optionalArgs);
+    }
 }
 /**
  * Thrown by {@link SharpImageTransformer.transform} when `sharp` itself rejects the SOURCE bytes —
@@ -48,6 +51,9 @@ export class ImageTransformUnavailableError extends Error {
  * states for the sibling `ImageTransformUnavailableError` case.
  */
 export class ImageSourceCorruptError extends Error {
+    constructor({ message }, optionalArgs = {}) {
+        super(message, optionalArgs);
+    }
 }
 /**
  * {@link TransformFormat} values that can actually carry multiple frames on output. GIF and WebP
@@ -70,10 +76,10 @@ function loadSharpFactory() {
         return require("sharp");
     }
     catch (err) {
-        throw new ImageTransformUnavailableError("the 'sharp' npm package is not installed in this environment (run `npm install sharp`) — " +
-            "SharpImageTransformer cannot perform a real pixel transform without it. This is a " +
-            "disclosed, optional-dependency blocker, not a silent stub: no bytes are faked or passed " +
-            "through unmodified.");
+        throw new ImageTransformUnavailableError({ message: "the 'sharp' npm package is not installed in this environment (run `npm install sharp`) — " +
+                "SharpImageTransformer cannot perform a real pixel transform without it. This is a " +
+                "disclosed, optional-dependency blocker, not a silent stub: no bytes are faked or passed " +
+                "through unmodified." });
     }
 }
 /**
@@ -149,12 +155,12 @@ export class SharpImageTransformer {
             const outBuffer = await pipeline.toBuffer();
             return {
                 bytes: new Uint8Array(outBuffer),
-                contentType: mimeForTransformFormat(input.params.format),
+                contentType: mimeForTransformFormat({ format: input.params.format }),
             };
         }
         catch (err) {
             const detail = err instanceof Error ? err.message : String(err);
-            throw new ImageSourceCorruptError(`the source image could not be decoded/re-encoded (target format '${input.params.format}'): ${detail}`);
+            throw new ImageSourceCorruptError({ message: `the source image could not be decoded/re-encoded (target format '${input.params.format}'): ${detail}` });
         }
     }
 }

package/dist/media/import/fetch-image.d.ts

@@ -0,0 +1,24 @@
+/** Binary URL import; the outbound adapter owns per-hop SSRF controls, while this module enforces caller MIME/byte policy and preserves source provenance. */
+import type { FetchImageRequired, FetchImageOptional, ValidateImageBytesRequired } from "./ports.js";
+export declare class MediaImportValidationError extends Error {
+    constructor({ message }: {
+        message: string;
+    });
+}
+export interface FetchedImage {
+    readonly bytes: Uint8Array;
+    readonly contentType: string;
+    readonly url: URL;
+}
+export declare function parseImportUrl({ raw }: {
+    raw: string;
+}): URL;
+export declare function buildImportFilename({ url, contentType }: {
+    url: URL;
+    contentType: string;
+}, { override }?: {
+    override?: string;
+}): string;
+export declare function validateImageBytes({ source, bytes, bytesTruncated, maxBytes, allowedContentTypes, sniffer }: ValidateImageBytesRequired): string;
+export declare function fetchImage(required: FetchImageRequired, { timeoutMs }?: FetchImageOptional): Promise<FetchedImage>;
+//# sourceMappingURL=fetch-image.d.ts.map

package/dist/media/import/fetch-image.js

@@ -0,0 +1,137 @@
+// Request/fetched-content refusal is distinct from an upload validator's already-in-hand byte checks.
+export class MediaImportValidationError extends Error {
+    constructor({ message }) { super(message); }
+}
+// An extension derived from the sniffed type cannot contradict the payload's actual bytes.
+const EXTENSION_BY_CONTENT_TYPE = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/gif": "gif",
+    "image/webp": "webp",
+    "image/avif": "avif",
+    "video/mp4": "mp4",
+    "video/webm": "webm",
+};
+// Early scheme/embedded-credential rejection gives callers actionable errors; it supplements,
+// rather than replaces, the outbound guard's independent connect-time controls.
+export function parseImportUrl({ raw }) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new MediaImportValidationError({ message: `'url' must be an absolute URL including the scheme (for example 'https://example.com/image.png') — got '${raw}'.` });
+    }
+    if (url.protocol !== "https:") {
+        throw new MediaImportValidationError({ message: `'url' must use https — got '${url.protocol.replace(":", "")}'. Only https URLs can be imported.` });
+    }
+    if (url.username || url.password) {
+        throw new MediaImportValidationError({ message: "'url' must not embed credentials (user:password@host)." });
+    }
+    return url;
+}
+// Bound/sanitize path punctuation, controls, and traversal-like names. This labels an upload, not
+// its filesystem location: content-addressed storage must not derive a path from this display name.
+export function buildImportFilename({ url, contentType }, { override } = {}) {
+    const extension = EXTENSION_BY_CONTENT_TYPE[contentType] ?? "bin";
+    const rawName = override ?? decodeLastPathSegment(url);
+    const slug = rawName
+        .replace(/\.[a-zA-Z0-9]{1,5}$/, "")
+        .replace(/[^a-zA-Z0-9\s-]/g, " ")
+        .trim()
+        .replace(/\s+/g, "-")
+        .slice(0, 60)
+        .replace(/^-+|-+$/g, "");
+    return `${slug || "imported-image"}.${extension}`;
+}
+// A malformed escape should not fail an otherwise valid import; the name sanitizer handles it.
+function decodeLastPathSegment(url) {
+    const segment = url.pathname.split("/").filter(Boolean).pop() ?? "";
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+}
+// Distinguish expired signed URLs (often 403/404) from a broken upstream host, so callers request a
+// fresh link instead of repeating a doomed fetch. Keep recovery wording separate from network I/O.
+function buildStatusError(url, status) {
+    const hint = status === 403 || status === 404
+        ? " Signed or time-limited image URLs expire quickly — ask for a fresh URL rather than retrying this one."
+        : "";
+    return new MediaImportValidationError({ message: `fetching '${url.href}' returned HTTP ${status}, not an image.${hint}` });
+}
+// Check clipping BEFORE magic bytes: a truncated image can still sniff as PNG but is a corrupt file,
+// not a smaller image. Never create a successful media row from a silently partial payload.
+// The sniffer and allowlist decide type; remote headers/local filename extensions cannot authorize
+// HTML, PDFs, or unsanitized SVG masquerading as images.
+export function validateImageBytes({ source, bytes, bytesTruncated, maxBytes, allowedContentTypes, sniffer }) {
+    assertMaxBytes(maxBytes);
+    // Keep URL error labels for remote imports while letting local root-relative paths label refusals.
+    const isRemote = source instanceof URL;
+    const label = isRemote ? source.href : source;
+    if (bytesTruncated || bytes.byteLength > maxBytes) {
+        throw new MediaImportValidationError({ message: isRemote
+                ? `the image at '${label}' exceeds the ${maxBytes}-byte import limit. Nothing was saved — a partially downloaded image would be a corrupt file, not a smaller one.`
+                : `file '${label}' exceeds the ${maxBytes}-byte import limit. Nothing was saved.` });
+    }
+    if (bytes.byteLength === 0) {
+        throw new MediaImportValidationError({ message: isRemote
+                ? `'${label}' returned an empty response body — there is nothing to import.`
+                : `file '${label}' is empty — there is nothing to import.` });
+    }
+    const contentType = sniffer.sniff({ bytes });
+    if (!allowedContentTypes.has(contentType)) {
+        throw new MediaImportValidationError({ message: `'${label}' is not an importable file: its actual bytes are '${contentType}'. ` +
+                `Only ${[...allowedContentTypes].join(", ")} can be imported (${isRemote ? 'the served Content-Type header' : 'the file extension'} is deliberately ignored — the bytes decide).` });
+    }
+    return contentType;
+}
+export async function fetchImage(required, { timeoutMs = 20_000 } = {}) {
+    const url = parseImportUrl({ raw: required.url });
+    assertMaxBytes(required.maxBytes);
+    const response = await required.outboundGuard.send({
+        httpClient: required.httpClient,
+        request: {
+            method: "GET",
+            url: url.href,
+            headers: { Accept: [...required.allowedContentTypes].join(", ") },
+            timeoutMs,
+            maxResponseBytes: required.maxBytes,
+        },
+    });
+    if (response.status < 200 || response.status >= 300) {
+        throw buildStatusError(url, response.status);
+    }
+    // Lossy UTF-8 decoding cannot reconstruct binary media. Fail loudly for clients missing raw bytes
+    // rather than store a mangled image and call it success; transport failures retain their own type.
+    const bytes = response.bodyBytes;
+    if (bytes === undefined) {
+        throw new MediaImportValidationError({ message: `the HTTP client returned no raw bytes for '${url.href}' — refusing to reconstruct image data from its lossy text decoding.` });
+    }
+    // A byte-specific verdict wins over truncation of the lossy text representation.
+    // The coarse flag ORs byte and text truncation: honoring it when a precise byte verdict exists
+    // once rejected complete images whose unused UTF-8 decode alone exceeded the cap. A legacy client
+    // with no precise verdict must still fail safe on the coarse flag.
+    const bytesTruncated = response.bodyBytesTruncated ?? response.bodyTruncated === true;
+    const contentType = validateImageBytes({ ...required, source: url, bytes, bytesTruncated });
+    return { bytes, contentType, url: resolveSourceUrl(url, response.finalUrl) };
+}
+// An older adapter may omit finalUrl; a malformed report can come from a hand-written port. Keep
+// the requested URL as a less precise label instead of rejecting good bytes or blanking provenance.
+function resolveSourceUrl(requested, reported) {
+    if (reported === undefined)
+        return requested;
+    try {
+        return new URL(reported);
+    }
+    catch {
+        return requested;
+    }
+}
+function assertMaxBytes(maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
+        throw new MediaImportValidationError({ message: "maxBytes must be a positive safe integer" });
+}
+//# sourceMappingURL=fetch-image.js.map

package/dist/media/import/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./ports.js";
+export * from "./fetch-image.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/media/import/index.js

@@ -0,0 +1,3 @@
+export * from "./ports.js";
+export * from "./fetch-image.js";
+//# sourceMappingURL=index.js.map

package/dist/media/import/ports.d.ts

@@ -0,0 +1,38 @@
+/** Binary requests use the kernel HTTP seam, compatible with the guarded platform client. */
+import type { HttpRequest, HttpResponse, HttpClientPort } from "@jini-ai/core/primitives";
+/**
+ * The only outbound execution path. The adapter must enforce DNS/IP validation, peer pinning,
+ * redirect checks and byte/time ceilings for every hop. Bind a platform guarded client's send:
+ * `{ send: ({ request }) => guardedClient.send({ request }) }`.
+ * A URL preflight alone does not satisfy this port's contract.
+ */
+export interface OutboundGuardPort {
+    send(required: {
+        request: HttpRequest;
+        httpClient: HttpClientPort;
+    }): Promise<HttpResponse>;
+}
+export interface ContentSnifferPort {
+    sniff(required: {
+        bytes: Uint8Array;
+    }): string;
+}
+export interface ImageImportPolicy {
+    maxBytes: number;
+    allowedContentTypes: ReadonlySet<string>;
+    sniffer: ContentSnifferPort;
+}
+export interface ValidateImageBytesRequired extends ImageImportPolicy {
+    source: URL | string;
+    bytes: Uint8Array;
+    bytesTruncated: boolean;
+}
+export interface FetchImageRequired extends ImageImportPolicy {
+    url: string;
+    httpClient: HttpClientPort;
+    outboundGuard: OutboundGuardPort;
+}
+export interface FetchImageOptional {
+    timeoutMs?: number;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/media/index.d.ts

@@ -32,7 +32,7 @@ export { InMemoryImageTransformer } from "./image-transformer.js";
 export { SharpImageTransformer, ImageTransformUnavailableError, ImageSourceCorruptError } from "./image-transformer.sharp.js";
 export { sniffContentType, type SniffedContentType } from "./content-type-sniffer.js";
 /** The agent-tool catalog for this domain (see `agent-tools.ts` for what is deliberately omitted). */
-export { mediaAgentToolCatalog, type AgentToolDefinition as MediaAgentToolDefinition, type AgentToolSideEffect as MediaAgentToolSideEffect, type AgentToolActorClassRule as MediaAgentToolActorClassRule, } from "./agent-tools.js";
+export { mediaAgentToolCatalog, } from "./agent-tools.js";
 /**
  * The agent-tool wiring for this domain.
  *
@@ -41,4 +41,10 @@ export { mediaAgentToolCatalog, type AgentToolDefinition as MediaAgentToolDefini
  * the shape is the contract, so no host type needs to be named here.
  */
 export { buildMediaRegistrations, mediaDerivedRisk, type MediaToolDeps, } from "./tool-registrations.js";
+export type { UploadMediaRequired, UploadMediaOptional, ListMediaRequired, GetMediaByIdRequired, UpdateMediaMetadataRequired, TrashMediaRequired, PurgeMediaRequired, RollbackUploadedMediaRequired } from "./media-service.js";
+export type { ResolveMediaRenditionRequired } from "./rendition-service.js";
+export type { RegisterTransformRequired, GetLatestTransformDefinitionRequired, IsLatestTransformVersionRequired } from "./transform-registry.js";
+export type { IsBlobUnreferencedRequired, TombstoneBlobRequired, RunBlobGcDeletePassRequired, RunBlobGcUnlinkPassRequired, RunBlobGcCycleRequired } from "./blob-gc.js";
+export { rollbackUploadedMedia } from "./media-service.js";
+export type { MediaRowCleanupDeps } from "./media-service.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/media/index.js

@@ -29,4 +29,5 @@ export { mediaAgentToolCatalog, } from "./agent-tools.js";
  * the shape is the contract, so no host type needs to be named here.
  */
 export { buildMediaRegistrations, mediaDerivedRisk, } from "./tool-registrations.js";
+export { rollbackUploadedMedia } from "./media-service.js";
 //# sourceMappingURL=index.js.map

package/dist/media/media-service.d.ts

@@ -1,4 +1,4 @@
-import type { ClockPort, IdGeneratorPort, UUID } from "../core/ports.js";
+import type { Clock, IdGenerator, UUID } from "@jini-ai/core/primitives";
 import { MediaConflictError, MediaNotFoundError, MediaSourceImmutableError, MediaStillReferencedError, MediaValidationError, type MediaRecord, type MediaSource } from "./types.js";
 import type { AssetBlobRepoPort, AssetRenditionRepoPort, BlobStorePort, MediaRepoPort } from "./ports.js";
 export { MediaConflictError, MediaNotFoundError, MediaSourceImmutableError, MediaStillReferencedError, MediaValidationError, };
@@ -49,7 +49,9 @@ export declare function resolveWriteOnceSource(required: {
     existing: MediaSource | undefined;
     requestedSha256: string;
 }, _optional?: Record<string, never>): MediaSource;
-export declare function isValidMediaSlugFormat(slug: string): boolean;
+export declare function isValidMediaSlugFormat(requiredArgs: {
+    slug: string;
+}, optionalArgs?: Record<string, never>): boolean;
 export interface UploadMediaInput {
     workspaceId: UUID;
     bytes: Uint8Array;
@@ -62,8 +64,8 @@ export interface UploadMediaInput {
     createdByPrincipal: string;
 }
 export interface UploadMediaDeps {
-    clock: ClockPort;
-    idGen: IdGeneratorPort;
+    clock: Clock;
+    idGen: IdGenerator;
     mediaRepo: MediaRepoPort;
     blobRepo: AssetBlobRepoPort;
     renditionRepo: AssetRenditionRepoPort;
@@ -79,7 +81,7 @@ export interface UploadMediaOptional {
 }
 /**
  * Validates, hashes, dedups by `(workspaceId, sha256)`, and writes a new media
- * asset. Ordering (INV-1a): bytes are written (or found already
+ * asset. Ordering : bytes are written (or found already
  * present via dedup) BEFORE the media row is saved — a media row never exists
  * without corresponding bytes.
  *
@@ -98,6 +100,7 @@ export interface UploadMediaOptional {
  * overhead, not a scan) — plus {@link deriveUniqueMediaSlug}'s own O(n) in the number of prior
  * same-base-slug collisions (see that function's doc).
  * @overallScore 100
+ * See docs/decisions/DR-004-journaled-blob-gc.md.
  */
 export declare function uploadMedia(required: UploadMediaRequired, optional?: UploadMediaOptional): Promise<{
     media: MediaRecord;
@@ -167,11 +170,12 @@ export interface FindMediaByIdOrSlugRequired {
  * falls through.
  *
  * Never throws (unlike {@link getMediaById}): every call site that needs this (an embed resolver, a
- * public rendition route) already has its own REQ-27-style non-throwing-miss contract, so this
+ * public rendition route) already has its own -style non-throwing-miss contract, so this
  * returns `null` on failure and lets the caller apply its own not-found handling rather than forcing
  * one shape on every caller.
  *
  * @complexity O(1) — at most two indexed repo lookups, short-circuited on the first hit.
+ * See docs/decisions/DR-004-journaled-blob-gc.md.
  */
 export declare function findMediaByIdOrSlug(required: FindMediaByIdOrSlugRequired, _optional?: Record<string, never>): Promise<MediaRecord | null>;
 export interface UpdateMediaMetadataInput {
@@ -214,7 +218,7 @@ export interface UpdateMediaMetadataInput {
     htmlAttributes?: string | null | undefined;
 }
 export interface UpdateMediaMetadataDeps {
-    clock: ClockPort;
+    clock: Clock;
     mediaRepo: MediaRepoPort;
 }
 export interface UpdateMediaMetadataRequired {
@@ -225,7 +229,7 @@ export declare function updateMediaMetadata(required: UpdateMediaMetadataRequire
     media: MediaRecord;
 }>;
 export interface TrashMediaDeps {
-    clock: ClockPort;
+    clock: Clock;
     mediaRepo: MediaRepoPort;
 }
 export interface TrashMediaRequired {
@@ -257,7 +261,7 @@ export interface PurgeMediaDeps {
      * that doesn't wire a clock into `PurgeMediaDeps` keeps compiling and
      * behaving correctly unchanged.
      */
-    clock?: ClockPort | undefined;
+    clock?: Clock | undefined;
 }
 export interface PurgeMediaRequired {
     deps: PurgeMediaDeps;
@@ -309,7 +313,7 @@ export interface MediaRowCleanupDeps {
     blobRepo: AssetBlobRepoPort;
     renditionRepo: AssetRenditionRepoPort;
     /** Optional — see `PurgeMediaDeps.clock`'s identical doc. */
-    clock?: ClockPort | undefined;
+    clock?: Clock | undefined;
 }
 export interface RollbackUploadedMediaRequired {
     deps: MediaRowCleanupDeps;