@jini-ai/cms 0.3.11 → 0.4.0

package/dist/media/media-service.js

@@ -1,3 +1,5 @@
+import { createSystemClock } from "@jini-ai/core/primitives";
+import { nowIso as kernelNowIso } from "@jini-ai/core/primitives";
 /**
  * @file `media` write/read service — walking-skeleton build.
  *
@@ -62,7 +64,7 @@ export const DEFAULT_MAX_UPLOAD_BYTES = 10 * 1024 * 1024; // 10 MiB
 /**
  * Renders a byte count as a human-readable MB figure for the size-cap rejection below (2026-09-21).
  * Every real caller passes a MiB-scale `maxUploadBytes` (10 MiB default, or a host override such as
- * Tovu's 50 MiB), so one decimal place is enough precision without ever showing a raw byte count —
+ * a host's 50 MiB), so one decimal place is enough precision without ever showing a raw byte count —
  * the whole point of this fix (see `uploadMedia`'s size-cap check, and `agent-tools.ts`'s file header
  * for why the catalog description can no longer state a specific number either). `toFixed(1)`'s
  * trailing `.0` is trimmed so a clean multiple of 1 MB (the common case) reads as `10 MB`, not `10.0
@@ -127,7 +129,7 @@ export const DEFAULT_ALLOWED_MIME_TYPES = new Set([
 export function resolveWriteOnceSource(required, _optional = {}) {
     const { existing, requestedSha256 } = required;
     if (existing && existing.sha256 !== requestedSha256) {
-        throw new MediaSourceImmutableError(`source.sha256 is write-once: cannot change '${existing.sha256}' to '${requestedSha256}'`);
+        throw new MediaSourceImmutableError({ message: `source.sha256 is write-once: cannot change '${existing.sha256}' to '${requestedSha256}'` });
     }
     return { sha256: requestedSha256 };
 }
@@ -167,7 +169,8 @@ const MEDIA_SLUG_UUID_SHAPE_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9
  *  human for a shorter value — silently truncating an internally-derived value is the same
  *  "coerce, don't fail" convention `deriveTitleFromFilename`/`slugifyMediaTitle` already use. */
 const MEDIA_MAX_SLUG_LENGTH = 120;
-export function isValidMediaSlugFormat(slug) {
+export function isValidMediaSlugFormat(requiredArgs, optionalArgs = {}) {
+    const { slug } = requiredArgs;
     return MEDIA_SLUG_FORMAT_PATTERN.test(slug) && !MEDIA_SLUG_UUID_SHAPE_PATTERN.test(slug);
 }
 /** Truncates a slug candidate to `maxLength`, stripping a trailing dash the cut can introduce (so a
@@ -234,7 +237,7 @@ async function deriveUniqueMediaSlug(mediaRepo, workspaceId, title) {
 }
 /**
  * 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.
  *
@@ -253,48 +256,49 @@ async function deriveUniqueMediaSlug(mediaRepo, workspaceId, title) {
  * 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 async function uploadMedia(required, optional = {}) {
     const { deps, input } = required;
     const maxUploadBytes = optional.maxUploadBytes ?? DEFAULT_MAX_UPLOAD_BYTES;
     const allowedMimeTypes = optional.allowedMimeTypes ?? DEFAULT_ALLOWED_MIME_TYPES;
     if (!allowedMimeTypes.has(input.contentType)) {
-        throw new MediaValidationError(`content type '${input.contentType}' is not allowed for upload`);
+        throw new MediaValidationError({ message: `content type '${input.contentType}' is not allowed for upload` });
     }
     if (input.bytes.byteLength === 0) {
-        throw new MediaValidationError("uploaded file is empty");
+        throw new MediaValidationError({ message: "uploaded file is empty" });
     }
     if (input.bytes.byteLength > maxUploadBytes) {
-        throw new MediaValidationError(`uploaded file exceeds the ${formatMaxUploadBytesAsMb(maxUploadBytes)} size cap`);
+        throw new MediaValidationError({ message: `uploaded file exceeds the ${formatMaxUploadBytesAsMb(maxUploadBytes)} size cap` });
     }
     const sha256 = createHash("sha256").update(input.bytes).digest("hex");
-    const nowIso = deps.clock.nowIso();
-    const storageKey = await withSha256Lock(sha256, async () => {
-        const existingBlob = await deps.blobRepo.findByHash({ workspaceId: input.workspaceId, sha256 });
-        if (existingBlob) {
-            if (existingBlob.status === "tombstoned") {
-                // Resurrect: cancel the pending GC in the same locked section rather
-                // than writing a duplicate blob (INV-1 dedup rule).
-                await deps.blobRepo.save({ ...existingBlob, status: "active", tombstonedAt: undefined });
+    const nowIso = kernelNowIso({ clock: deps.clock });
+    const storageKey = await withSha256Lock({ key: sha256, criticalSection: async () => {
+            const existingBlob = await deps.blobRepo.findByHash({ workspaceId: input.workspaceId, sha256 });
+            if (existingBlob) {
+                if (existingBlob.status === "tombstoned") {
+                    // Resurrect: cancel the pending GC in the same locked section rather
+                    // than writing a duplicate blob ( dedup rule). See docs/decisions/DR-004-journaled-blob-gc.md.
+                    await deps.blobRepo.save({ ...existingBlob, status: "active", tombstonedAt: undefined });
+                }
+                return existingBlob.storageKey;
             }
-            return existingBlob.storageKey;
-        }
-        const written = await deps.blobStore.put({
-            workspaceId: input.workspaceId,
-            sha256,
-            bytes: input.bytes,
-        });
-        await deps.blobRepo.save({
-            id: deps.idGen.newId(),
-            workspaceId: input.workspaceId,
-            sha256,
-            storageKey: written.storageKey,
-            status: "active",
-            createdByPrincipal: input.createdByPrincipal,
-            createdAt: nowIso,
-        });
-        return written.storageKey;
-    });
+            const written = await deps.blobStore.put({
+                workspaceId: input.workspaceId,
+                sha256,
+                bytes: input.bytes,
+            });
+            await deps.blobRepo.save({
+                id: deps.idGen.newId(),
+                workspaceId: input.workspaceId,
+                sha256,
+                storageKey: written.storageKey,
+                status: "active",
+                createdByPrincipal: input.createdByPrincipal,
+                createdAt: nowIso,
+            });
+            return written.storageKey;
+        } });
     const title = deriveTitleFromFilename(input.filename);
     const slug = await deriveUniqueMediaSlug(deps.mediaRepo, input.workspaceId, title);
     const media = {
@@ -353,7 +357,7 @@ export async function getMediaById(required, _optional = {}) {
     const { workspaceId, id } = required.input;
     const media = await required.deps.mediaRepo.findById({ workspaceId, id });
     if (!media)
-        throw new MediaNotFoundError(`media '${id}' was not found`);
+        throw new MediaNotFoundError({ message: `media '${id}' was not found` });
     return { media };
 }
 /**
@@ -373,11 +377,12 @@ export async function getMediaById(required, _optional = {}) {
  * 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 async function findMediaByIdOrSlug(required, _optional = {}) {
     const { deps, input } = required;
@@ -402,7 +407,7 @@ export async function findMediaByIdOrSlug(required, _optional = {}) {
  *  `undefined` (leave unchanged) both bypass this — only a real provided number is checked. */
 function assertPositiveIntegerOrThrow(value, field) {
     if (!Number.isInteger(value) || value <= 0) {
-        throw new MediaValidationError(`media.${field} must be a positive integer, got ${value}`);
+        throw new MediaValidationError({ message: `media.${field} must be a positive integer, got ${value}` });
     }
 }
 /**
@@ -418,18 +423,18 @@ function assertPositiveIntegerOrThrow(value, field) {
  */
 async function resolveSlugForUpdate(mediaRepo, workspaceId, id, rawSlug) {
     const slug = rawSlug.trim().toLowerCase();
-    if (!slug || !isValidMediaSlugFormat(slug)) {
-        throw new MediaValidationError("slug must use lowercase letters, numbers, and dashes, and must not be shaped like a UUID");
+    if (!slug || !isValidMediaSlugFormat({ slug: slug })) {
+        throw new MediaValidationError({ message: "slug must use lowercase letters, numbers, and dashes, and must not be shaped like a UUID" });
     }
     // Same bound and rejection style as `post.ts`'s `resolveExplicitSlug` — a human typed this value,
     // so it is refused with a clear reason rather than silently truncated (unlike the derived-on-
     // upload path, see `MEDIA_MAX_SLUG_LENGTH`'s doc).
     if (slug.length > MEDIA_MAX_SLUG_LENGTH) {
-        throw new MediaValidationError(`slug must be ${MEDIA_MAX_SLUG_LENGTH} characters or fewer`);
+        throw new MediaValidationError({ message: `slug must be ${MEDIA_MAX_SLUG_LENGTH} characters or fewer` });
     }
     const duplicate = await mediaRepo.findBySlug({ workspaceId, slug });
     if (duplicate && duplicate.id !== id) {
-        throw new MediaConflictError(`slug '${slug}' is already used by media '${duplicate.id}'`);
+        throw new MediaConflictError({ message: `slug '${slug}' is already used by media '${duplicate.id}'` });
     }
     return slug;
 }
@@ -447,9 +452,9 @@ function resolveHtmlAttributesForUpdate(rawValue) {
     const trimmed = rawValue.trim();
     if (trimmed === "")
         return null;
-    const parsed = parseMediaHtmlAttributes(trimmed);
+    const parsed = parseMediaHtmlAttributes({ text: trimmed });
     if (parsed.error) {
-        throw new MediaValidationError(`media.htmlAttributes: ${describeMediaHtmlAttributeError(parsed.error)}`);
+        throw new MediaValidationError({ message: `media.htmlAttributes: ${describeMediaHtmlAttributeError(parsed.error)}` });
     }
     return trimmed;
 }
@@ -457,7 +462,7 @@ export async function updateMediaMetadata(required, _optional = {}) {
     const { deps, input } = required;
     const existing = await deps.mediaRepo.findById({ workspaceId: input.workspaceId, id: input.id });
     if (!existing)
-        throw new MediaNotFoundError(`media '${input.id}' was not found`);
+        throw new MediaNotFoundError({ message: `media '${input.id}' was not found` });
     assertEntityLive({ entityType: "media", entityId: input.id, state: existing.status === "trashed" ? "trashed" : "live" });
     if (input.width !== undefined && input.width !== null)
         assertPositiveIntegerOrThrow(input.width, "width");
@@ -486,7 +491,7 @@ export async function updateMediaMetadata(required, _optional = {}) {
         height: input.height !== undefined ? input.height : existing.height,
         cssClass: input.cssClass !== undefined ? (input.cssClass === null ? null : input.cssClass.trim() || null) : existing.cssClass,
         htmlAttributes,
-        updatedAt: deps.clock.nowIso(),
+        updatedAt: kernelNowIso({ clock: deps.clock }),
         version: existing.version + 1,
     };
     await deps.mediaRepo.save(media);
@@ -503,13 +508,13 @@ export async function trashMedia(required, _optional = {}) {
     const { deps, input } = required;
     const existing = await deps.mediaRepo.findById(input);
     if (!existing)
-        throw new MediaNotFoundError(`media '${input.id}' was not found`);
+        throw new MediaNotFoundError({ message: `media '${input.id}' was not found` });
     if (existing.status === "trashed")
         return { media: existing };
     const media = {
         ...existing,
         status: "trashed",
-        updatedAt: deps.clock.nowIso(),
+        updatedAt: kernelNowIso({ clock: deps.clock }),
         version: existing.version + 1,
     };
     await deps.mediaRepo.save(media);
@@ -551,12 +556,12 @@ export async function purgeMedia(required, _optional = {}) {
     const { deps, input } = required;
     const existing = await deps.mediaRepo.findById(input);
     if (!existing)
-        throw new MediaNotFoundError(`media '${input.id}' was not found`);
+        throw new MediaNotFoundError({ message: `media '${input.id}' was not found` });
     if (existing.status !== "trashed") {
-        throw new MediaStillReferencedError(`media '${input.id}' must be trashed before it can be purged`, [
-            `media '${input.id}' is still active (stand-in for the real entry_refs ` +
-                `where-used index, which is not implemented — see purgeMedia's doc comment)`,
-        ]);
+        throw new MediaStillReferencedError({ message: `media '${input.id}' must be trashed before it can be purged`, referencing: [
+                `media '${input.id}' is still active (stand-in for the real entry_refs ` +
+                    `where-used index, which is not implemented — see purgeMedia's doc comment)`,
+            ] });
     }
     await removeMediaRowsAndTombstoneBlob(deps, {
         workspaceId: input.workspaceId,
@@ -578,7 +583,7 @@ export async function purgeMedia(required, _optional = {}) {
 async function removeMediaRowsAndTombstoneBlob(deps, input) {
     await deps.renditionRepo.removeByAsset({ workspaceId: input.workspaceId, assetId: input.id });
     await deps.mediaRepo.remove({ workspaceId: input.workspaceId, id: input.id });
-    const clock = deps.clock ?? { nowIso: () => new Date().toISOString() };
+    const clock = deps.clock ?? createSystemClock();
     await tombstoneBlobIfUnreferenced({
         deps: { mediaRepo: deps.mediaRepo, blobRepo: deps.blobRepo, clock },
         input: { workspaceId: input.workspaceId, sha256: input.sha256 },

package/dist/media/ports.d.ts

@@ -23,7 +23,7 @@
  *
  * Interfaces only — no feature logic.
  */
-import type { UUID } from "../core/ports.js";
+import type { UUID } from "@jini-ai/core/primitives";
 import type { AssetBlobRecord, AssetRenditionRecord, BlobGcJournalEntry, MediaRecord } from "./types.js";
 import type { TransformDefinitionRecord } from "./transform-types.js";
 export interface MediaRepoPort {
@@ -64,8 +64,9 @@ export interface AssetBlobRepoPort {
     }): Promise<void>;
 }
 /**
- * `blob_gc_journal` repo (INV-1 two-phase protocol). See
+ * `blob_gc_journal` repo ( two-phase protocol). See
  * {@link BlobGcJournalEntry} for what a row represents.
+ * See docs/decisions/DR-004-journaled-blob-gc.md.
  */
 export interface BlobGcJournalRepoPort {
     save(entry: BlobGcJournalEntry): Promise<void>;

package/dist/media/rendition-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 type { AssetBlobRepoPort, AssetRenditionRepoPort, BlobStorePort, MediaRepoPort, TransformDefinitionRepoPort } from "./ports.js";
 import type { ImageTransformerPort } from "./image-transformer.js";
 export interface ResolveMediaRenditionDeps {
@@ -8,8 +8,8 @@ export interface ResolveMediaRenditionDeps {
     transformRepo: TransformDefinitionRepoPort;
     blobStore: BlobStorePort;
     imageTransformer: ImageTransformerPort;
-    clock: ClockPort;
-    idGen: IdGeneratorPort;
+    clock: Clock;
+    idGen: IdGenerator;
 }
 export interface ResolveMediaRenditionInput {
     workspaceId: UUID;

package/dist/media/rendition-service.js

@@ -1,3 +1,4 @@
+import { nowIso as kernelNowIso } from "@jini-ai/core/primitives";
 /**
  * @file Rendition resolution service — "serve-if-exists +
  * bounded generate-if-defined", the read path behind the frozen public URL
@@ -82,7 +83,7 @@ export async function resolveMediaRendition(required, _optional = {}) {
     });
     if (existing) {
         const bytes = await deps.blobStore.get({ storageKey: existing.storageKey });
-        return { outcome: "ok", bytes, contentType: mimeForTransformFormat(definition.params.format) };
+        return { outcome: "ok", bytes, contentType: mimeForTransformFormat({ format: definition.params.format }) };
     }
     const generationAllowed = isReferencedByPublishedContent({ workspaceId: input.workspaceId, name: input.transformName, version: input.version }) ||
         (await isLatestTransformVersion({
@@ -100,42 +101,42 @@ export async function resolveMediaRendition(required, _optional = {}) {
         throw new Error(`media '${media.id}': source blob for sha256 '${media.source.sha256}' was not found`);
     }
     const lockKey = `${media.source.sha256}:${input.transformName}:${input.version}`;
-    const renditionRow = await withRenditionLock(lockKey, async () => {
-        // Double-checked: another caller may have finished generating this exact rendition while we
-        // were queued for the lock (single-flight) — reuse it instead of calling
-        // `imageTransformer.transform` a second time.
-        const racedExisting = await deps.renditionRepo.findOne({
-            workspaceId: input.workspaceId,
-            assetId,
-            transformName: input.transformName,
-            version: input.version,
-        });
-        if (racedExisting)
-            return racedExisting;
-        const sourceBytes = await deps.blobStore.get({ storageKey: sourceBlob.storageKey });
-        const { bytes: outputBytes } = await deps.imageTransformer.transform({
-            bytes: sourceBytes,
-            params: definition.params,
-        });
-        const outputSha256 = createHash("sha256").update(outputBytes).digest("hex");
-        const { storageKey } = await deps.blobStore.put({
-            workspaceId: input.workspaceId,
-            sha256: outputSha256,
-            bytes: outputBytes,
-        });
-        const row = {
-            id: deps.idGen.newId(),
-            workspaceId: input.workspaceId,
-            assetId,
-            transformName: input.transformName,
-            version: input.version,
-            storageKey,
-            createdAt: deps.clock.nowIso(),
-        };
-        await deps.renditionRepo.save(row);
-        return row;
-    });
+    const renditionRow = await withRenditionLock({ key: lockKey, criticalSection: async () => {
+            // Double-checked: another caller may have finished generating this exact rendition while we
+            // were queued for the lock (single-flight) — reuse it instead of calling
+            // `imageTransformer.transform` a second time.
+            const racedExisting = await deps.renditionRepo.findOne({
+                workspaceId: input.workspaceId,
+                assetId,
+                transformName: input.transformName,
+                version: input.version,
+            });
+            if (racedExisting)
+                return racedExisting;
+            const sourceBytes = await deps.blobStore.get({ storageKey: sourceBlob.storageKey });
+            const { bytes: outputBytes } = await deps.imageTransformer.transform({
+                bytes: sourceBytes,
+                params: definition.params,
+            });
+            const outputSha256 = createHash("sha256").update(outputBytes).digest("hex");
+            const { storageKey } = await deps.blobStore.put({
+                workspaceId: input.workspaceId,
+                sha256: outputSha256,
+                bytes: outputBytes,
+            });
+            const row = {
+                id: deps.idGen.newId(),
+                workspaceId: input.workspaceId,
+                assetId,
+                transformName: input.transformName,
+                version: input.version,
+                storageKey,
+                createdAt: kernelNowIso({ clock: deps.clock }),
+            };
+            await deps.renditionRepo.save(row);
+            return row;
+        } });
     const bytes = await deps.blobStore.get({ storageKey: renditionRow.storageKey });
-    return { outcome: "ok", bytes, contentType: mimeForTransformFormat(definition.params.format) };
+    return { outcome: "ok", bytes, contentType: mimeForTransformFormat({ format: definition.params.format }) };
 }
 //# sourceMappingURL=rendition-service.js.map

package/dist/media/repo.memory.d.ts

@@ -9,13 +9,15 @@
  * Adapters only — dumb collections scoped by `workspaceId`. No
  * validation or business rules live here (that's `media-service.ts`'s job).
  */
-import type { UUID } from "../core/ports.js";
+import type { UUID } from "@jini-ai/core/primitives";
 import type { AssetBlobRepoPort, AssetRenditionRepoPort, BlobGcJournalRepoPort, MediaRepoPort, TransformDefinitionRepoPort } from "./ports.js";
 import type { AssetBlobRecord, AssetRenditionRecord, BlobGcJournalEntry, MediaRecord } from "./types.js";
 import type { TransformDefinitionRecord } from "./transform-types.js";
 export declare class InMemoryMediaRepo implements MediaRepoPort {
     private rows;
-    constructor(initialRows?: MediaRecord[]);
+    constructor(requiredArgs: Record<string, never>, optionalArgs?: {
+        initialRows?: MediaRecord[];
+    });
     findById(required: {
         workspaceId: UUID;
         id: UUID;
@@ -35,7 +37,9 @@ export declare class InMemoryMediaRepo implements MediaRepoPort {
 }
 export declare class InMemoryAssetBlobRepo implements AssetBlobRepoPort {
     private rows;
-    constructor(initialRows?: AssetBlobRecord[]);
+    constructor(requiredArgs: Record<string, never>, optionalArgs?: {
+        initialRows?: AssetBlobRecord[];
+    });
     findByHash(required: {
         workspaceId: UUID;
         sha256: string;
@@ -51,7 +55,9 @@ export declare class InMemoryAssetBlobRepo implements AssetBlobRepoPort {
 }
 export declare class InMemoryAssetRenditionRepo implements AssetRenditionRepoPort {
     private rows;
-    constructor(initialRows?: AssetRenditionRecord[]);
+    constructor(requiredArgs: Record<string, never>, optionalArgs?: {
+        initialRows?: AssetRenditionRecord[];
+    });
     listByAsset(required: {
         workspaceId: UUID;
         assetId: UUID;
@@ -69,15 +75,18 @@ export declare class InMemoryAssetRenditionRepo implements AssetRenditionRepoPor
     }): Promise<void>;
 }
 /**
- * In-memory `blob_gc_journal` adapter (INV-1 two-phase protocol —
+ * In-memory `blob_gc_journal` adapter ( two-phase protocol —
  * see `blob-gc.ts`). Same disclosed limit as every other repo in this file:
  * rows do not survive a process restart, so a real crash between the
  * delete-pass and unlink-pass loses the journal entry in this build (a real
  * database-backed table would not).
+ * See docs/decisions/DR-004-journaled-blob-gc.md.
  */
 export declare class InMemoryBlobGcJournalRepo implements BlobGcJournalRepoPort {
     private rows;
-    constructor(initialRows?: BlobGcJournalEntry[]);
+    constructor(requiredArgs: Record<string, never>, optionalArgs?: {
+        initialRows?: BlobGcJournalEntry[];
+    });
     save(entry: BlobGcJournalEntry): Promise<void>;
     list(required: {
         workspaceId: UUID;
@@ -96,7 +105,9 @@ export declare class InMemoryBlobGcJournalRepo implements BlobGcJournalRepoPort
  */
 export declare class InMemoryTransformDefinitionRepo implements TransformDefinitionRepoPort {
     private rows;
-    constructor(initialRows?: TransformDefinitionRecord[]);
+    constructor(requiredArgs: Record<string, never>, optionalArgs?: {
+        initialRows?: TransformDefinitionRecord[];
+    });
     listByName(required: {
         workspaceId: UUID;
         name: string;

package/dist/media/repo.memory.js

@@ -1,6 +1,7 @@
 export class InMemoryMediaRepo {
     rows;
-    constructor(initialRows = []) {
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { initialRows = [] } = optionalArgs;
         this.rows = [...initialRows];
     }
     async findById(required) {
@@ -26,7 +27,8 @@ export class InMemoryMediaRepo {
 }
 export class InMemoryAssetBlobRepo {
     rows;
-    constructor(initialRows = []) {
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { initialRows = [] } = optionalArgs;
         this.rows = [...initialRows];
     }
     async findByHash(required) {
@@ -49,7 +51,8 @@ export class InMemoryAssetBlobRepo {
 }
 export class InMemoryAssetRenditionRepo {
     rows;
-    constructor(initialRows = []) {
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { initialRows = [] } = optionalArgs;
         this.rows = [...initialRows];
     }
     async listByAsset(required) {
@@ -74,15 +77,17 @@ export class InMemoryAssetRenditionRepo {
     }
 }
 /**
- * In-memory `blob_gc_journal` adapter (INV-1 two-phase protocol —
+ * In-memory `blob_gc_journal` adapter ( two-phase protocol —
  * see `blob-gc.ts`). Same disclosed limit as every other repo in this file:
  * rows do not survive a process restart, so a real crash between the
  * delete-pass and unlink-pass loses the journal entry in this build (a real
  * database-backed table would not).
+ * See docs/decisions/DR-004-journaled-blob-gc.md.
  */
 export class InMemoryBlobGcJournalRepo {
     rows;
-    constructor(initialRows = []) {
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { initialRows = [] } = optionalArgs;
         this.rows = [...initialRows];
     }
     async save(entry) {
@@ -109,7 +114,8 @@ export class InMemoryBlobGcJournalRepo {
  */
 export class InMemoryTransformDefinitionRepo {
     rows;
-    constructor(initialRows = []) {
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { initialRows = [] } = optionalArgs;
         this.rows = [...initialRows];
     }
     async listByName(required) {

package/dist/media/tool-registrations.d.ts

@@ -1,3 +1,5 @@
+import type { IdGenerator } from "@jini-ai/core/primitives";
+import type { Clock } from "@jini-ai/core/primitives";
 /**
  * @file Media's tool-registration wiring: maps `agent-tools.ts`'s four catalog entries onto
  * `media-service.ts`'s list/upload/update/trash operations, as `ToolRegistration`s. The entire
@@ -5,7 +7,7 @@
  * present-but-unwired; see `media/agent-tools.ts`'s own header.
  *
  * Authorization shape: unlike Forms/Identity/Widgets, `media-service.ts`'s functions perform NO
- * internal `authorize()` call of their own — every admin HTTP route a host builds gates inline
+ * internal `authorize` call of their own — every admin HTTP route a host builds gates inline
  * instead. Every handler here does the same via the kit's `requireToolPermission`, which is the
  * single evaluation for these tools, located where a real route would locate it.
  *
@@ -13,7 +15,7 @@
  * own `publicUrl` addition closed there: an agent could upload/list an asset but had no tool-facing
  * way to learn a URL usable to embed it in a post/page). Unlike `post`, this package has no host to
  * resolve a public URL against — the `/m/{assetId}/{transformName}.v{version}/...` contract
- * (ADR-027 §4) is a HOST decision (which URL prefix, which transform pipeline, whether one even
+ *  is a HOST decision (which URL prefix, which transform pipeline, whether one even
  * exists), not a `@jini-ai/cms` one; this package deliberately has zero `/m/`-shaped string
  * literals anywhere. So `publicUrl` is resolved through an OPTIONAL, host-injected
  * {@link MediaToolDeps.resolvePublicUrls}, batch-shaped (one call per `media_list_assets`/
@@ -26,26 +28,23 @@
  * `features/post/tool-registrations.ts`'s identical reasoning for skipping `content_post_update`/
  * `content_post_delete`: those two return the row incidentally, to confirm what was just
  * edited/trashed, not to answer "where does this live".
+ * See docs/decisions/DR-004-journaled-blob-gc.md.
  */
 import type { AuthorizeFn } from "../core/commands/command.js";
-import { type DerivedRiskByToolId, type ToolRegistration } from "../core/tools/registration-kit.js";
+import { type DerivedRiskByToolId, type ToolRegistration } from "@jini-ai/core";
 import type { AssetBlobRepoPort, AssetRenditionRepoPort, BlobStorePort, MediaRepoPort } from "./ports.js";
 import type { MediaRecord } from "./types.js";
 /**
  * The exact slice of a host's route-deps bag Media's tool handlers read. Declared structurally
  * (rather than importing any host's own route-deps type) so this module carries no back-edge into
  * a host's composition root. A host satisfies this structurally by passing its existing route deps
- * object; nothing there needs to change shape.
+ * object after binding the kernel clock/ID contracts.
  */
 export interface MediaToolDeps {
     authorize: AuthorizeFn;
     workspaceId: string;
-    clock: {
-        nowIso(): string;
-    };
-    idGen: {
-        newId(): string;
-    };
+    clock: Clock;
+    idGen: IdGenerator;
     mediaRepo: MediaRepoPort;
     assetBlobRepo: AssetBlobRepoPort;
     assetRenditionRepo: AssetRenditionRepoPort;
@@ -58,7 +57,9 @@ export interface MediaToolDeps {
      * resolution failed soft). Omitted entirely: every response's `publicUrl` is `null`, matching this
      * field's own pre-2026-09-02 absence for every host that has not opted in yet.
      */
-    resolvePublicUrls?: (assets: readonly MediaRecord[]) => Promise<ReadonlyMap<string, string | null>>;
+    resolvePublicUrls?: ((required: {
+        assets: readonly MediaRecord[];
+    }, optional?: Record<string, never>) => Promise<ReadonlyMap<string, string | null>>) | undefined;
     /**
      * Optional hook run once, right after `media_upload_asset`'s own `uploadMedia()` call succeeds —
      * the fix for a defect where a tool-driven upload recorded NO content type anywhere. `uploadMedia`
@@ -88,10 +89,10 @@ export interface MediaToolDeps {
      * matching this field's own pre-fix absence for every host that has not opted in yet — the exact
      * `resolvePublicUrls`-precedent contract.
      */
-    recordUploadContentType?: (params: {
+    recordUploadContentType?: ((params: {
         media: MediaRecord;
         bytes: Uint8Array;
-    }) => Promise<void>;
+    }) => Promise<void>) | undefined;
     /**
      * Optional host-supplied override of `uploadMedia`'s own `DEFAULT_MAX_UPLOAD_BYTES` (10 MiB,
      * `media-service.ts`), forwarded verbatim as `uploadMedia`'s third (`optional`) argument in the
@@ -103,7 +104,7 @@ export interface MediaToolDeps {
      * pre-2026-09-21 absence for every host that has not opted in yet — the same degrade-soft
      * contract {@link resolvePublicUrls} and {@link recordUploadContentType} already established.
      */
-    maxUploadBytes?: number;
+    maxUploadBytes?: number | undefined;
 }
 /**
  * This wiring layer's OWN risk classification, authored from what each handler below actually
@@ -111,5 +112,5 @@ export interface MediaToolDeps {
  * `sideEffects` declaration.
  */
 export declare const mediaDerivedRisk: DerivedRiskByToolId;
-export declare function buildMediaRegistrations(routeDeps: MediaToolDeps): ToolRegistration[];
+export declare function buildMediaRegistrations(required: Omit<MediaToolDeps, "resolvePublicUrls" | "recordUploadContentType" | "maxUploadBytes">, optional?: Pick<MediaToolDeps, "resolvePublicUrls" | "recordUploadContentType" | "maxUploadBytes">): ToolRegistration[];
 //# sourceMappingURL=tool-registrations.d.ts.map