@jini-ai/cms 0.3.11 → 0.4.0

package/dist/http/settings/stream.js

@@ -0,0 +1,147 @@
+/** Starts after HTTP authorization. All scheduling and storage are injected. */
+/** Poll with bounded pages, tenant-scoped ids and retryable reads; close cancels all schedules.
+ * O(page size) per tick and O(1) connection state; repository effects live behind the feed port.
+ * Invalid scheduler intervals/page sizes throw RangeError before opening; initial read errors propagate.
+ */
+export async function openSettingsChangeStream(required, optional = {}) {
+    const { request, response, workspaceId, principalId, changeFeed, scheduler } = required;
+    const pageSize = optional.revisionPageSize ?? 200;
+    const intervals = [optional.pollIntervalMs ?? 1_000, optional.keepaliveIntervalMs ?? 25_000, optional.reauthorizeIntervalMs ?? 30_000];
+    if (!Number.isSafeInteger(pageSize) || pageSize <= 0 || intervals.some((n) => !Number.isFinite(n) || n <= 0)) {
+        throw new RangeError("settings feed page size and intervals must be positive");
+    }
+    let closed = false;
+    let ticking = false;
+    let checkingAuthorization = false;
+    const cancellations = [];
+    const reportError = (operation, error) => {
+        // Reporting is best-effort: a host hook must never turn recovery into an unhandled rejection.
+        try {
+            if (optional.onError)
+                optional.onError({ operation, error });
+            else
+                console.error(`[settings] change feed ${operation} failed`, error);
+        }
+        catch { /* Diagnostic failures cannot interrupt stream cleanup or retries. */ }
+    };
+    const recover = (operation, effect) => {
+        try {
+            effect();
+        }
+        catch (error) {
+            reportError(operation, error);
+        }
+    };
+    const release = () => {
+        // Every resource gets its own recovery boundary so one failing cancellation cannot leak others.
+        for (const cancel of cancellations.splice(0))
+            recover("cancel", cancel);
+        recover("request-listener", () => { request.off("close", close); });
+        recover("response-listener", () => { response.off("close", close); });
+    };
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        release();
+        recover("close", () => { required.onClose({ close }); });
+        if (!response.writableEnded && !response.destroyed)
+            recover("end", () => { response.end(); });
+    };
+    request.on("close", close);
+    response.on("close", close);
+    try {
+        const head = await changeFeed.head({});
+        if (closed || required.isDisposed() || response.destroyed || response.writableEnded) {
+            close();
+            return close;
+        }
+        const resumeFrom = Number(request.headers["last-event-id"]);
+        let cursor = Number.isFinite(resumeFrom) && resumeFrom >= 0 ? Math.min(resumeFrom, head) : head;
+        let lastEmittedId = cursor;
+        const viewer = { workspaceId, principalId };
+        response.writeHead(200, {
+            "Content-Type": "text/event-stream", "Cache-Control": "no-cache, no-transform",
+            ...(request.httpVersionMajor < 2 ? { Connection: "keep-alive" } : {}), "X-Accel-Buffering": "no",
+        });
+        const tick = async () => {
+            if (closed || ticking)
+                return;
+            ticking = true;
+            try {
+                // Snapshot head before the page: concurrent writes must never be skipped.
+                const ledgerHead = await changeFeed.head({});
+                if (closed)
+                    return;
+                const batch = await changeFeed.collect({ sinceSeq: cursor, limit: pageSize, viewer });
+                if (closed)
+                    return;
+                const examined = batch.examinedCount < pageSize ? ledgerHead : batch.cursor;
+                cursor = Math.max(cursor, examined, batch.cursor);
+                if (!batch.namespaces.length)
+                    return;
+                // The internal global head is never disclosed as an event id.
+                lastEmittedId = Math.max(lastEmittedId, batch.cursor);
+                response.write(`id: ${lastEmittedId}\nevent: settings-changed\ndata: ${JSON.stringify({ namespaces: batch.namespaces })}\n\n`);
+            }
+            catch (error) {
+                if (!closed)
+                    reportError("poll", error);
+            }
+            finally {
+                ticking = false;
+            }
+        };
+        const reauthorize = async () => {
+            if (closed || checkingAuthorization)
+                return;
+            checkingAuthorization = true;
+            try {
+                const result = await required.authorize({ principalId, workspaceId, permission: required.permission, entityType: "setting-value" });
+                if (!closed && !result.allowed)
+                    close();
+            }
+            catch (error) {
+                if (!closed)
+                    reportError("re-authorization", error);
+            }
+            finally {
+                checkingAuthorization = false;
+            }
+        };
+        const schedule = (intervalMs, callback) => {
+            const cancel = scheduler.every({ intervalMs, callback });
+            if (closed)
+                recover("cancel", cancel);
+            else
+                cancellations.push(cancel);
+        };
+        schedule(intervals[0], () => { void tick(); });
+        schedule(intervals[1], () => {
+            if (closed)
+                return;
+            try {
+                response.write(": keepalive\n\n");
+            }
+            catch (error) {
+                reportError("keepalive", error);
+                close();
+            }
+        });
+        schedule(intervals[2], () => { void reauthorize(); });
+        if (!closed)
+            response.write(": connected\n\n");
+        return close;
+    }
+    catch (error) {
+        // Cancel schedules even when opening a feed fails. Let the HTTP wrapper map the error.
+        if (response.headersSent)
+            close();
+        else {
+            closed = true;
+            release();
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=stream.js.map

package/dist/media/agent-tools.d.ts

@@ -1,69 +1,4 @@
-/**
- * @file The Media agent-tool catalog — this domain's instance of the per-domain
- * `agent-tools.ts` convention Forms/Identity already use.
- *
- * Purpose:
- * A static, in-process catalog describing every agent-callable tool this domain exposes and the
- * permission each carries. Every entry maps 1:1 onto a real exported function of
- * `media/media-service.ts` — this catalog never names an operation the domain cannot perform.
- *
- * Deliberate absences (the point of a catalog, not an oversight):
- * - There is NO `media_purge_asset`. `purgeMedia` is a HARD delete: it removes the `MediaRecord`
- *   row permanently and triggers the blob-GC tombstone pass (`tombstoneBlobIfUnreferenced`,
- *   `blob-gc.ts`) that can eventually reclaim the underlying bytes. It is gated behind
- *   `media.delete.force` — a separate, narrower permission a human admin UI itself treats as a
- *   distinct escalation tier from ordinary `media.delete` (mirrors `admin.menus.delete` vs
- *   `admin.menus.delete.force`). An assistant is reachable by prompt injection through ordinary
- *   operator content (a comment, a form submission) in a way a human clicking the admin "purge"
- *   button is not, so an irreversible, storage-reclaiming delete is left human-UI-only — the same
- *   discipline `identity/agent-tools.ts` applies to `resetUserPassword`.
- * - There is NO named-transform-registry tool (`registerTransform`, `media/transform-registry.ts`).
- *   No admin HTTP route needs to expose it at all — it is a core-declared, boot-time/operational
- *   concept, not a human admin-UI operation. Wrapping it here would invent agent capability beyond
- *   what a host's admin surface itself exposes, which this catalog's own discipline forbids.
- *
- * How it relates to a host:
- * A host's tool-registration layer maps these entries into `ToolRegistration`s (see
- * `tool-registrations.ts`). Unlike Forms/Identity, `media-service.ts`'s functions perform NO
- * internal `authorize()` call of their own (confirmed: none of `UploadMediaDeps`/
- * `UpdateMediaMetadataDeps`/`TrashMediaDeps` carry an `authorize` field) — a host's admin HTTP
- * routes check authorization inline, before calling the service function. `tool-registrations.ts`
- * therefore performs that SAME inline authorize check itself (the identical permission string and
- * `entityType: "media"` a host route would use) rather than relying on a domain-layer gate that
- * does not exist for this library — a disclosed, deliberate divergence from the Forms/Identity/
- * content-types pass-through-`ToolPolicy` reasoning, not an oversight.
- *
- * Architectural role:
- * `media` domain declaration. Imports only the constant its own domain already enforces
- * (`DEFAULT_ALLOWED_MIME_TYPES` from `media-service.ts`), so the published JSON Schema's allowed
- * content types cannot drift from the validator.
- *
- * `media_upload_asset`'s size-cap wording (2026-09-21): this catalog is a module-load-time constant
- * shared by every host (see this file's own module doc above), but a host can now override
- * `uploadMedia`'s cap per-call via `MediaToolDeps.maxUploadBytes` (`tool-registrations.ts`). Stating
- * `DEFAULT_MAX_UPLOAD_BYTES` (10 MiB) here would be an outright lie for a host that raised its own
- * cap (e.g. Tovu's 50 MiB) — the model would be told a wrong, lower number than what the tool
- * actually accepts. The description and schema below therefore describe the cap generically instead
- * of stating a figure; the size-rejection error itself (`uploadMedia`'s `MediaValidationError`,
- * `media-service.ts`) states the ACTUAL configured limit in MB, which is the one place that can be
- * host-accurate.
- */
-export type AgentToolSideEffect = "none" | "mutates-durable-state" | "mints-token";
-export type AgentToolActorClassRule = "confirmer-must-equal-own-delegatedBy" | "user-only" | "none";
-export interface AgentToolDefinition {
-    name: string;
-    description: string;
-    sideEffects: AgentToolSideEffect;
-    authorization: {
-        permission: string;
-    };
-    actorClassRule?: AgentToolActorClassRule;
-    /**
-     * JSON Schema for this tool's `input`, published to the model via `ToolDescriptor.inputSchema`
-     * (a host's tool-registration layer refuses to wire any tool lacking one).
-     */
-    inputSchema?: Readonly<Record<string, unknown>>;
-}
+import type { AgentToolDefinition } from "@jini-ai/core";
 /**
  * The Media domain's fixed agent-tool catalog — the 4 operations a host's admin HTTP surface
  * exposes that are safe to wrap, out of its 5 total (see file header for why `purge` is excluded).

package/dist/media/agent-tools.js

@@ -42,7 +42,7 @@
  * shared by every host (see this file's own module doc above), but a host can now override
  * `uploadMedia`'s cap per-call via `MediaToolDeps.maxUploadBytes` (`tool-registrations.ts`). Stating
  * `DEFAULT_MAX_UPLOAD_BYTES` (10 MiB) here would be an outright lie for a host that raised its own
- * cap (e.g. Tovu's 50 MiB) — the model would be told a wrong, lower number than what the tool
+ * cap (e.g. a host's 50 MiB) — the model would be told a wrong, lower number than what the tool
  * actually accepts. The description and schema below therefore describe the cap generically instead
  * of stating a figure; the size-rejection error itself (`uploadMedia`'s `MediaValidationError`,
  * `media-service.ts`) states the ACTUAL configured limit in MB, which is the one place that can be
@@ -50,6 +50,10 @@
  */
 import { MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES } from "./html-attributes.js";
 import { DEFAULT_ALLOWED_MIME_TYPES } from "./media-service.js";
+/**
+   * JSON Schema for this tool's `input`, published to the model via `ToolDescriptor.inputSchema`
+   * (a host's tool-registration layer refuses to wire any tool lacking one).
+   */
 const MEDIA_ID_SCHEMA = {
     type: "string",
     description: "The media asset's id, as returned by media_upload_asset or media_list_assets.",

package/dist/media/blob-gc-lock.d.ts

@@ -1,6 +1,6 @@
 /**
  * @file In-process, per-sha256 mutex for the blob-GC protocol
- * (INV-1's "Serialization" clause).
+ * ("Serialization" clause).
  *
  * Purpose:
  * The real protocol serializes every `asset_blobs` state transition
@@ -20,6 +20,7 @@
  * decorative comment. See `blob-gc.ts`'s file header for what this does NOT
  * cover (cross-process safety, which needs a real DB transaction — a host's
  * own SQLite adapter would supply that).
+ * See docs/decisions/DR-004-journaled-blob-gc.md.
  */
 /**
  * Runs `criticalSection` exclusively with respect to any other call
@@ -33,5 +34,8 @@
  * by the number of other calls currently queued for the same key.
  * @overallScore 100
  */
-export declare function withSha256Lock<T>(key: string, criticalSection: () => Promise<T>): Promise<T>;
+export declare function withSha256Lock<T>(requiredArgs: {
+    key: string;
+    criticalSection: () => Promise<T>;
+}, optionalArgs?: Record<string, never>): Promise<T>;
 //# sourceMappingURL=blob-gc-lock.d.ts.map

package/dist/media/blob-gc-lock.js

@@ -1,6 +1,6 @@
 /**
  * @file In-process, per-sha256 mutex for the blob-GC protocol
- * (INV-1's "Serialization" clause).
+ * ("Serialization" clause).
  *
  * Purpose:
  * The real protocol serializes every `asset_blobs` state transition
@@ -20,6 +20,7 @@
  * decorative comment. See `blob-gc.ts`'s file header for what this does NOT
  * cover (cross-process safety, which needs a real DB transaction — a host's
  * own SQLite adapter would supply that).
+ * See docs/decisions/DR-004-journaled-blob-gc.md.
  */
 /**
  * Tracks the tail of the promise chain for each in-flight/queued key. An
@@ -40,7 +41,8 @@ const lockTails = new Map();
  * by the number of other calls currently queued for the same key.
  * @overallScore 100
  */
-export function withSha256Lock(key, criticalSection) {
+export function withSha256Lock(requiredArgs, optionalArgs = {}) {
+    const { key, criticalSection } = requiredArgs;
     const priorTail = lockTails.get(key) ?? Promise.resolve();
     const run = priorTail.then(criticalSection, criticalSection);
     const settledTail = run.then(() => undefined, () => undefined);

package/dist/media/blob-gc.d.ts

@@ -1,52 +1,53 @@
 /**
  * @file Blob-GC protocol ("References, deletion, and GC
- * (never-brick)", INV-1) — the audited tombstone -> delete-pass -> unlink-pass
+ * (never-brick)") — the audited tombstone -> delete-pass -> unlink-pass
  * design, scoped to what an in-memory-repo build can actually run today.
  *
  * Built in this pass:
- *  - The real "unreferenced" predicate's sha256-uniqueness-across-non-purged-
- *    media-entries conjunct ({@link isBlobUnreferenced}), backed by the actual
- *    `mediaRepo` data `purgeMedia` already has.
- *  - Ordering (INV-1a): {@link runBlobGcDeletePass} deletes the `asset_blobs`
- *    row and writes the `blob_gc_journal` entry together, before any bytes are
- *    touched; {@link runBlobGcUnlinkPass} only ever unlinks bytes for a row
- *    whose deletion has already happened. `uploadMedia` (see
- *    `media-service.ts`) already writes bytes before the row.
- *  - Serialization: every transition below runs inside {@link withSha256Lock}
- *    (`blob-gc-lock.ts`) — this build's substitute for `BEGIN IMMEDIATE`
- *    against an in-memory table (see that file's header for why).
- *  - The two-phase, journaled shape: {@link tombstoneBlobIfUnreferenced} ->
- *    {@link runBlobGcDeletePass} (re-checks the predicate + `gc_grace`,
- *    journals, deletes the row) -> {@link runBlobGcUnlinkPass} (drains the
- *    journal, removes bytes). {@link runBlobGcCycle} is a convenience batch
- *    wrapper around the last two for tests/manual operation; nothing calls it
- *    on a schedule.
- *  - `gc_grace = max(30d default, retained-snapshot age)`, with the snapshot
- *    input wired as a stub (see below) so a real value slots in later without
- *    reworking callers.
+ * - The real "unreferenced" predicate's sha256-uniqueness-across-non-purged-
+ * media-entries conjunct ({@link isBlobUnreferenced}), backed by the actual
+ * `mediaRepo` data `purgeMedia` already has.
+ * - Ordering : {@link runBlobGcDeletePass} first writes the `blob_gc_journal`
+ * entry, then deletes the `asset_blobs` row in separate awaited operations, before any bytes are
+ * touched; {@link runBlobGcUnlinkPass} only ever unlinks bytes for a row
+ * whose deletion has already happened. `uploadMedia` (see
+ * `media-service.ts`) already writes bytes before the row.
+ * - Serialization: every transition below runs inside {@link withSha256Lock}
+ * (`blob-gc-lock.ts`) — this build's substitute for `BEGIN IMMEDIATE`
+ * against an in-memory table (see that file's header for why).
+ * - The two-phase, journaled shape: {@link tombstoneBlobIfUnreferenced} ->
+ * {@link runBlobGcDeletePass} (re-checks the predicate + `gc_grace`,
+ * journals, deletes the row) -> {@link runBlobGcUnlinkPass} (drains the
+ * journal, removes bytes). {@link runBlobGcCycle} is a convenience batch
+ * wrapper around the last two for tests/manual operation; nothing calls it
+ * on a schedule.
+ * - `gc_grace = max(30d default, retained-snapshot age)`, with the snapshot
+ * input wired as a stub (see below) so a real value slots in later without
+ * reworking callers.
  *
  * Deliberately NOT built (disclosed, matches this task's explicit scope):
- *  - **`entry_refs` where-used index** ({@link hasLiveEntryRefs}) — belongs to
- *    the generic entries model, which is accepted design only, not
- *    running code yet (see `types.ts`'s file header on `MediaRecord` being a
- *    bespoke table for the same reason). Stubbed to always return `false`
- *    ("no live refs found").
- *  - **Retained-snapshot conjunct** ({@link getOldestRetainedSnapshotAgeMs}) —
- *    owned by a pending Storage/Backups snapshot primitive, which doesn't
- *    exist yet either. Stubbed to always
- *    return `undefined` ("no retained snapshot").
- *  - **Monthly orphan sweep** ({@link runMonthlyOrphanSweepStub}) — the fourth
- *    protocol phase, reconciling bytes on disk with no `asset_blobs` row at
- *    all (e.g. a crash before any GC protocol existed). Needs a scheduler
- *    this library doesn't provide. Named so the seam exists; performs no work
- *    and is never called.
- *  - **Cross-process safety** — `withSha256Lock` only serializes within one
- *    Node process. A real multi-instance deployment needs the real DB
- *    transaction the original design specifies, which a host's own persistence adapter
- *    would supply; this build has no multi-writer story for media at all yet
- *    (in-memory repo), so that gap is inherited, not new.
+ * - **`entry_refs` where-used index** ({@link hasLiveEntryRefs}) — belongs to
+ * the generic entries model, which is accepted design only, not
+ * running code yet (see `types.ts`'s file header on `MediaRecord` being a
+ * bespoke table for the same reason). Stubbed to always return `false`
+ * ("no live refs found").
+ * - **Retained-snapshot conjunct** ({@link getOldestRetainedSnapshotAgeMs}) —
+ * owned by a pending Storage/Backups snapshot primitive, which doesn't
+ * exist yet either. Stubbed to always
+ * return `undefined` ("no retained snapshot").
+ * - **Monthly orphan sweep** ({@link runMonthlyOrphanSweepStub}) — the fourth
+ * protocol phase, reconciling bytes on disk with no `asset_blobs` row at
+ * all (e.g. a crash before any GC protocol existed). Needs a scheduler
+ * this library doesn't provide. Named so the seam exists; performs no work
+ * and is never called.
+ * - **Cross-process safety** — `withSha256Lock` only serializes within one
+ * Node process. A real multi-instance deployment needs the real DB
+ * transaction the original design specifies, which a host's own persistence adapter
+ * would supply; this build has no multi-writer story for media at all yet
+ * (in-memory repo), so that gap is inherited, not new.
+ * See docs/decisions/DR-004-journaled-blob-gc.md.
  */
-import type { ClockPort, IdGeneratorPort, UUID } from "../core/ports.js";
+import type { Clock, IdGenerator, UUID } from "@jini-ai/core/primitives";
 import type { AssetBlobRepoPort, BlobGcJournalRepoPort, BlobStorePort, MediaRepoPort } from "./ports.js";
 /** Default retention window before a tombstoned blob's delete-pass may run. */
 export declare const DEFAULT_GC_GRACE_MS: number;
@@ -100,7 +101,7 @@ export declare function isBlobUnreferenced(required: IsBlobUnreferencedRequired)
 export interface TombstoneBlobDeps {
     mediaRepo: MediaRepoPort;
     blobRepo: AssetBlobRepoPort;
-    clock: ClockPort;
+    clock: Clock;
 }
 export interface TombstoneBlobRequired {
     deps: TombstoneBlobDeps;
@@ -128,8 +129,8 @@ export interface RunBlobGcDeletePassDeps {
     mediaRepo: MediaRepoPort;
     blobRepo: AssetBlobRepoPort;
     journalRepo: BlobGcJournalRepoPort;
-    clock: ClockPort;
-    idGen: IdGeneratorPort;
+    clock: Clock;
+    idGen: IdGenerator;
 }
 export interface RunBlobGcDeletePassRequired {
     deps: RunBlobGcDeletePassDeps;
@@ -147,11 +148,20 @@ export interface RunBlobGcDeletePassRequired {
  * re-check is what the protocol calls for and is what future non-stub
  * entry_refs/snapshot conjuncts would need). On success: writes the
  * `blob_gc_journal` entry and removes the `asset_blobs` row, in that order,
- * inside the same locked section — INV-1a's "unlinked only after the row
+ * inside the same locked section — "unlinked only after the row
  * deletion commits" half depends on nothing touching bytes here at all.
+ * These operations are ordered, not atomic. A journal-save rejection leaves the row alone;
+ * a row-delete rejection leaves a pending entry plus the row. The unlink-pass rechecks ANY
+ * row (including a tombstone), skips its bytes and drains that stale entry, so a later delete
+ * retry can journal again. If row deletion succeeded before interruption, the pending entry
+ * lets unlink resume; unlink failure retains the entry, and byte removal must be idempotent.
+ * Durable recovery requires the journal save to commit before row deletion on the same store;
+ * the in-memory adapters survive neither a process crash nor restart. Across processes the
+ * host must additionally serialize row ownership checks, uploads and unlinking (see header).
  *
  * @complexity O(n) — dominated by the re-check's `isBlobUnreferenced` scan.
  * @overallScore 100
+ * See docs/decisions/DR-004-journaled-blob-gc.md.
  */
 export declare function runBlobGcDeletePass(required: RunBlobGcDeletePassRequired): Promise<{
     deleted: boolean;
@@ -235,12 +245,15 @@ export declare function runBlobGcCycle(required: RunBlobGcCycleRequired): Promis
  * @complexity O(1) (stub — does nothing).
  * @overallScore 100
  */
-export declare function runMonthlyOrphanSweepStub(_deps: {
-    blobStore: BlobStorePort;
-    blobRepo: AssetBlobRepoPort;
-}, _input: {
-    workspaceId: UUID;
-}): Promise<{
+export declare function runMonthlyOrphanSweepStub(_required: {
+    deps: {
+        blobStore: BlobStorePort;
+        blobRepo: AssetBlobRepoPort;
+    };
+    input: {
+        workspaceId: UUID;
+    };
+}, _optional?: Record<string, never>): Promise<{
     implemented: false;
 }>;
 //# sourceMappingURL=blob-gc.d.ts.map

package/dist/media/blob-gc.js

@@ -1,3 +1,4 @@
+import { nowIso as kernelNowIso } from "@jini-ai/core/primitives";
 import { withSha256Lock } from "./blob-gc-lock.js";
 /** Default retention window before a tombstoned blob's delete-pass may run. */
 export const DEFAULT_GC_GRACE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
@@ -104,18 +105,18 @@ export async function isBlobUnreferenced(required) {
  */
 export async function tombstoneBlobIfUnreferenced(required) {
     const { deps, input } = required;
-    return withSha256Lock(input.sha256, async () => {
-        const row = await deps.blobRepo.findByHash(input);
-        if (!row)
-            return { tombstoned: false, reason: "no-blob-row" };
-        if (row.status === "tombstoned")
-            return { tombstoned: true, reason: "already-tombstoned" };
-        const unreferenced = await isBlobUnreferenced({ deps, input });
-        if (!unreferenced)
-            return { tombstoned: false, reason: "still-referenced" };
-        await deps.blobRepo.save({ ...row, status: "tombstoned", tombstonedAt: deps.clock.nowIso() });
-        return { tombstoned: true, reason: "tombstoned" };
-    });
+    return withSha256Lock({ key: input.sha256, criticalSection: async () => {
+            const row = await deps.blobRepo.findByHash(input);
+            if (!row)
+                return { tombstoned: false, reason: "no-blob-row" };
+            if (row.status === "tombstoned")
+                return { tombstoned: true, reason: "already-tombstoned" };
+            const unreferenced = await isBlobUnreferenced({ deps, input });
+            if (!unreferenced)
+                return { tombstoned: false, reason: "still-referenced" };
+            await deps.blobRepo.save({ ...row, status: "tombstoned", tombstonedAt: kernelNowIso({ clock: deps.clock }) });
+            return { tombstoned: true, reason: "tombstoned" };
+        } });
 }
 /**
  * Delete-pass. Gated on the row being `tombstoned` AND `gc_grace` having
@@ -126,38 +127,47 @@ export async function tombstoneBlobIfUnreferenced(required) {
  * re-check is what the protocol calls for and is what future non-stub
  * entry_refs/snapshot conjuncts would need). On success: writes the
  * `blob_gc_journal` entry and removes the `asset_blobs` row, in that order,
- * inside the same locked section — INV-1a's "unlinked only after the row
+ * inside the same locked section — "unlinked only after the row
  * deletion commits" half depends on nothing touching bytes here at all.
+ * These operations are ordered, not atomic. A journal-save rejection leaves the row alone;
+ * a row-delete rejection leaves a pending entry plus the row. The unlink-pass rechecks ANY
+ * row (including a tombstone), skips its bytes and drains that stale entry, so a later delete
+ * retry can journal again. If row deletion succeeded before interruption, the pending entry
+ * lets unlink resume; unlink failure retains the entry, and byte removal must be idempotent.
+ * Durable recovery requires the journal save to commit before row deletion on the same store;
+ * the in-memory adapters survive neither a process crash nor restart. Across processes the
+ * host must additionally serialize row ownership checks, uploads and unlinking (see header).
  *
  * @complexity O(n) — dominated by the re-check's `isBlobUnreferenced` scan.
  * @overallScore 100
+ * See docs/decisions/DR-004-journaled-blob-gc.md.
  */
 export async function runBlobGcDeletePass(required) {
     const { deps, input } = required;
-    return withSha256Lock(input.sha256, async () => {
-        const row = await deps.blobRepo.findByHash(input);
-        if (!row)
-            return { deleted: false, reason: "no-blob-row" };
-        if (row.status !== "tombstoned" || !row.tombstonedAt) {
-            return { deleted: false, reason: "not-tombstoned" };
-        }
-        const graceMs = resolveGcGraceMs(input);
-        const elapsedMs = new Date(deps.clock.nowIso()).getTime() - new Date(row.tombstonedAt).getTime();
-        if (elapsedMs < graceMs)
-            return { deleted: false, reason: "grace-period-not-elapsed" };
-        const stillUnreferenced = await isBlobUnreferenced({ deps, input });
-        if (!stillUnreferenced)
-            return { deleted: false, reason: "resurrected" };
-        await deps.journalRepo.save({
-            id: deps.idGen.newId(),
-            workspaceId: input.workspaceId,
-            sha256: input.sha256,
-            storageKey: row.storageKey,
-            journaledAt: deps.clock.nowIso(),
-        });
-        await deps.blobRepo.remove(input);
-        return { deleted: true, reason: "deleted" };
-    });
+    return withSha256Lock({ key: input.sha256, criticalSection: async () => {
+            const row = await deps.blobRepo.findByHash(input);
+            if (!row)
+                return { deleted: false, reason: "no-blob-row" };
+            if (row.status !== "tombstoned" || !row.tombstonedAt) {
+                return { deleted: false, reason: "not-tombstoned" };
+            }
+            const graceMs = resolveGcGraceMs(input);
+            const elapsedMs = new Date(kernelNowIso({ clock: deps.clock })).getTime() - new Date(row.tombstonedAt).getTime();
+            if (elapsedMs < graceMs)
+                return { deleted: false, reason: "grace-period-not-elapsed" };
+            const stillUnreferenced = await isBlobUnreferenced({ deps, input });
+            if (!stillUnreferenced)
+                return { deleted: false, reason: "resurrected" };
+            await deps.journalRepo.save({
+                id: deps.idGen.newId(),
+                workspaceId: input.workspaceId,
+                sha256: input.sha256,
+                storageKey: row.storageKey,
+                journaledAt: kernelNowIso({ clock: deps.clock }),
+            });
+            await deps.blobRepo.remove(input);
+            return { deleted: true, reason: "deleted" };
+        } });
 }
 /**
  * Unlink-pass. Drains every journal entry for the workspace; for each, under
@@ -188,20 +198,20 @@ export async function runBlobGcUnlinkPass(required) {
     const unlinked = [];
     const skipped = [];
     for (const entry of entries) {
-        await withSha256Lock(entry.sha256, async () => {
-            const liveRow = await deps.blobRepo.findByHash({
-                workspaceId: entry.workspaceId,
-                sha256: entry.sha256,
-            });
-            if (liveRow) {
-                skipped.push(entry.sha256);
-            }
-            else {
-                await deps.blobStore.remove({ storageKey: entry.storageKey });
-                unlinked.push(entry.sha256);
-            }
-            await deps.journalRepo.remove({ workspaceId: entry.workspaceId, id: entry.id });
-        });
+        await withSha256Lock({ key: entry.sha256, criticalSection: async () => {
+                const liveRow = await deps.blobRepo.findByHash({
+                    workspaceId: entry.workspaceId,
+                    sha256: entry.sha256,
+                });
+                if (liveRow) {
+                    skipped.push(entry.sha256);
+                }
+                else {
+                    await deps.blobStore.remove({ storageKey: entry.storageKey });
+                    unlinked.push(entry.sha256);
+                }
+                await deps.journalRepo.remove({ workspaceId: entry.workspaceId, id: entry.id });
+            } });
     }
     return { unlinked, skipped };
 }
@@ -248,7 +258,7 @@ export async function runBlobGcCycle(required) {
  * @complexity O(1) (stub — does nothing).
  * @overallScore 100
  */
-export async function runMonthlyOrphanSweepStub(_deps, _input) {
+export async function runMonthlyOrphanSweepStub(_required, _optional = {}) {
     return { implemented: false };
 }
 //# sourceMappingURL=blob-gc.js.map

package/dist/media/blob-key.d.ts

@@ -14,7 +14,7 @@
  * `media-service.ts` file header). A future epoch-aware rewrite would change
  * this function's output shape, not its callers' contract.
  */
-import type { UUID } from "../core/ports.js";
+import type { UUID } from "@jini-ai/core/primitives";
 /**
  * Derives `ws/{workspaceId}/blobs/{sha256[0..1]}/{sha256}`.
  *

package/dist/media/content-type-sniffer.d.ts

@@ -45,5 +45,7 @@ export type SniffedContentType = "image/png" | "image/jpeg" | "image/gif" | "ima
  * {@link TEXT_SNIFF_WINDOW} bytes, a fixed constant independent of `bytes.length`.
  * @overallScore 100
  */
-export declare function sniffContentType(bytes: Uint8Array): SniffedContentType;
+export declare function sniffContentType({ bytes }: {
+    bytes: Uint8Array;
+}, _optional?: Record<string, never>): SniffedContentType;
 //# sourceMappingURL=content-type-sniffer.d.ts.map

package/dist/media/content-type-sniffer.js

@@ -162,7 +162,7 @@ function isSvgLike(text) {
  * {@link TEXT_SNIFF_WINDOW} bytes, a fixed constant independent of `bytes.length`.
  * @overallScore 100
  */
-export function sniffContentType(bytes) {
+export function sniffContentType({ bytes }, _optional = {}) {
     if (isPng(bytes))
         return "image/png";
     if (isJpeg(bytes))