@jini-ai/cms 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.4.2 — 2026-10-04
+
+- Media: optional `BlobStorePort.sizeOf` reports original blob bytes (filesystem store memoizes `stat`); `MediaRecord.createdBy` is stamped at creation and write-once.
+- Navigation: entry targets carry optional `lastKnownHref` and `entryType` hints.
+- Taxonomy: `unassignTerms` returns the removed ids. Trash: a no-op trash/restore does not notify again.
+- Internal `@jini-ai/*` dependencies are caret ranges (`workspace:^`) instead of exact pins, so a host on a newer patch resolves a single copy without an override.
+
 ## Unreleased — Trash host adoption
 
 - Preserve `adapter-unavailable` for absent domains before checking entity policy; selected purge

package/dist/media/blob-store.fs.d.ts

@@ -5,6 +5,7 @@ export interface LocalFsBlobStoreDeps {
 }
 export declare class LocalFsBlobStore implements BlobStorePort {
     private readonly rootDir;
+    private readonly sizesByKey;
     constructor(deps: LocalFsBlobStoreDeps);
     private resolvePath;
     put(input: PutBlobInput): Promise<{
@@ -28,6 +29,9 @@ export declare class LocalFsBlobStore implements BlobStorePort {
     get(input: {
         storageKey: string;
     }): Promise<Uint8Array>;
+    sizeOf({ storageKey }: {
+        storageKey: string;
+    }, _optional?: Record<string, never>): Promise<number | null>;
     /**
      * `ENOENT` (the path genuinely does not exist) resolves to `false`. Any other `stat()` failure
      * (`EACCES` permission denied, `ENOTDIR`, `EIO`, ...) is rethrown raw — same "catch the one

package/dist/media/blob-store.fs.js

@@ -16,6 +16,9 @@ import { dirname, join } from "node:path";
 import { computeBlobStorageKey } from "./blob-key.js";
 export class LocalFsBlobStore {
     rootDir;
+    // Storage keys include workspace + content hash: immutable bytes make successful sizes
+    // reusable for this process. Promises coalesce concurrent reads of the same hash as well.
+    sizesByKey = new Map();
     constructor(deps) {
         this.rootDir = deps.rootDir;
     }
@@ -27,6 +30,7 @@ export class LocalFsBlobStore {
         const path = this.resolvePath(storageKey);
         await mkdir(dirname(path), { recursive: true });
         await writeFile(path, input.bytes);
+        this.sizesByKey.delete(storageKey);
         return { storageKey };
     }
     /**
@@ -46,6 +50,7 @@ export class LocalFsBlobStore {
         await mkdir(dirname(path), { recursive: true });
         try {
             await writeFile(path, input.bytes, { flag: "wx" });
+            this.sizesByKey.delete(storageKey);
             return { storageKey, written: true };
         }
         catch (err) {
@@ -58,6 +63,27 @@ export class LocalFsBlobStore {
     async get(input) {
         return readFile(this.resolvePath(input.storageKey));
     }
+    sizeOf({ storageKey }, _optional = {}) {
+        const cached = this.sizesByKey.get(storageKey);
+        if (cached)
+            return cached;
+        const pending = stat(this.resolvePath(storageKey)).then((info) => info.size).catch((err) => {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        });
+        this.sizesByKey.set(storageKey, pending);
+        // Missing/restored blobs and transient failures must be retried. Identity guards prevent
+        // an older stat from clearing a newer entry after a write/remove invalidated the cache.
+        void pending.then((size) => {
+            if (size === null && this.sizesByKey.get(storageKey) === pending)
+                this.sizesByKey.delete(storageKey);
+        }, () => {
+            if (this.sizesByKey.get(storageKey) === pending)
+                this.sizesByKey.delete(storageKey);
+        });
+        return pending;
+    }
     /**
      * `ENOENT` (the path genuinely does not exist) resolves to `false`. Any other `stat()` failure
      * (`EACCES` permission denied, `ENOTDIR`, `EIO`, ...) is rethrown raw — same "catch the one
@@ -79,6 +105,7 @@ export class LocalFsBlobStore {
     }
     async remove(input) {
         await rm(this.resolvePath(input.storageKey), { force: true });
+        this.sizesByKey.delete(input.storageKey);
     }
 }
 //# sourceMappingURL=blob-store.fs.js.map

package/dist/media/blob-store.memory.d.ts

@@ -24,6 +24,9 @@ export declare class InMemoryBlobStore implements BlobStorePort {
     exists(input: {
         storageKey: string;
     }): Promise<boolean>;
+    sizeOf({ storageKey }: {
+        storageKey: string;
+    }, _optional?: Record<string, never>): Promise<number | null>;
     remove(input: {
         storageKey: string;
     }): Promise<void>;

package/dist/media/blob-store.memory.js

@@ -29,6 +29,9 @@ export class InMemoryBlobStore {
     async exists(input) {
         return this.bytesByKey.has(input.storageKey);
     }
+    async sizeOf({ storageKey }, _optional = {}) {
+        return this.bytesByKey.get(storageKey)?.byteLength ?? null;
+    }
     async remove(input) {
         this.bytesByKey.delete(input.storageKey);
     }

package/dist/media/created-by.d.ts

@@ -0,0 +1,15 @@
+import type { MediaRecord } from "./types.js";
+import type { MediaRepoPort } from "./ports.js";
+/** Bind creation writes to one authenticated caller without shared mutable actor state.
+ * Useful when adapting an older upload service that predates asset-level attribution. */
+export declare function mediaRepoWithCreator(required: {
+    mediaRepo: MediaRepoPort;
+    principalId: string;
+}, _optional?: Record<string, never>): MediaRepoPort;
+/** An update retains creation attribution, even when the original creator is unknown.
+ * Omitting an unknown field preserves compatibility with legacy serialized records. */
+export declare function preserveMediaCreator(required: {
+    record: MediaRecord;
+    original: MediaRecord;
+}, _optional?: Record<string, never>): MediaRecord;
+//# sourceMappingURL=created-by.d.ts.map

package/dist/media/created-by.js

@@ -0,0 +1,20 @@
+/** Bind creation writes to one authenticated caller without shared mutable actor state.
+ * Useful when adapting an older upload service that predates asset-level attribution. */
+export function mediaRepoWithCreator(required, _optional = {}) {
+    const { mediaRepo, principalId } = required;
+    return {
+        findById: input => mediaRepo.findById(input),
+        findBySlug: input => mediaRepo.findBySlug(input),
+        list: input => mediaRepo.list(input),
+        remove: input => mediaRepo.remove(input),
+        save: record => mediaRepo.save({ ...record, createdBy: principalId }),
+    };
+}
+/** An update retains creation attribution, even when the original creator is unknown.
+ * Omitting an unknown field preserves compatibility with legacy serialized records. */
+export function preserveMediaCreator(required, _optional = {}) {
+    const { createdBy: _ignored, ...metadata } = required.record;
+    return { ...metadata, ...(required.original.createdBy !== undefined
+            ? { createdBy: required.original.createdBy } : {}) };
+}
+//# sourceMappingURL=created-by.js.map

package/dist/media/index.d.ts

@@ -15,6 +15,7 @@ export type { MediaStatus, MediaSource, MediaRecord, AssetBlobStatus, AssetBlobR
 export { MediaNotFoundError, MediaValidationError, MediaConflictError, MediaSourceImmutableError, MediaStillReferencedError, } from "./types.js";
 export type { MediaRepoPort, AssetBlobRepoPort, AssetRenditionRepoPort, BlobStorePort, BlobGcJournalRepoPort, PutBlobInput, TransformDefinitionRepoPort, } from "./ports.js";
 export { computeBlobStorageKey } from "./blob-key.js";
+export { preserveMediaCreator, mediaRepoWithCreator } from "./created-by.js";
 export { MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES, isAllowedMediaHtmlAttributeName, parseMediaHtmlAttributes, describeMediaHtmlAttributeError, type MediaHtmlAttributeRejectionReason, type MediaHtmlAttributeError, type ParsedMediaHtmlAttributes, } from "./html-attributes.js";
 export { InMemoryMediaRepo, InMemoryAssetBlobRepo, InMemoryAssetRenditionRepo, InMemoryBlobGcJournalRepo, InMemoryTransformDefinitionRepo, } from "./repo.memory.js";
 export { withSha256Lock } from "./blob-gc-lock.js";

package/dist/media/index.js

@@ -1,5 +1,6 @@
 export { MediaNotFoundError, MediaValidationError, MediaConflictError, MediaSourceImmutableError, MediaStillReferencedError, } from "./types.js";
 export { computeBlobStorageKey } from "./blob-key.js";
+export { preserveMediaCreator, mediaRepoWithCreator } from "./created-by.js";
 export { MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES, isAllowedMediaHtmlAttributeName, parseMediaHtmlAttributes, describeMediaHtmlAttributeError, } from "./html-attributes.js";
 export { InMemoryMediaRepo, InMemoryAssetBlobRepo, InMemoryAssetRenditionRepo, InMemoryBlobGcJournalRepo, InMemoryTransformDefinitionRepo, } from "./repo.memory.js";
 export { withSha256Lock } from "./blob-gc-lock.js";

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

@@ -60,7 +60,7 @@ export interface UploadMediaInput {
     alt?: string | undefined;
     caption?: string | undefined;
     credit?: string | undefined;
-    /** Attributed on the `asset_blobs` row (required attribution). */
+    /** Acting principal, stamped on each media row and on a newly created asset_blobs row. */
     createdByPrincipal: string;
 }
 export interface UploadMediaDeps {

package/dist/media/media-service.js

@@ -304,6 +304,7 @@ export async function uploadMedia(required, optional = {}) {
     const media = {
         id: deps.idGen.newId(),
         workspaceId: input.workspaceId,
+        createdBy: input.createdByPrincipal,
         title,
         slug,
         alt: input.alt?.trim() ?? "",

package/dist/media/ports.d.ts

@@ -13,13 +13,15 @@
  *
  * `BlobStorePort`'s surface is deliberately narrower than the full
  * design: no `capabilities()`/`createPresignedUpload()` (the presign surface is
- * explicitly deferred by this task's scope). It has one method beyond the
- * task's stated minimal 3 (`put`/`get`/`exists`): `remove()`. That addition is
+ * explicitly deferred by this task's scope). It extends the original minimal
+ * 3 (`put`/`get`/`exists`) with `remove()`. That addition is
  * necessary to implement `purgeMedia`'s explicitly-requested "best-effort blob
  * unlink" (see `media-service.ts`) — without a way to delete bytes, purge could
  * only ever delete rows, never reclaim storage. This is disclosed here, not
  * silently smuggled in: it is still far short of the real journaled
  * GC protocol (no epochs, no `BEGIN IMMEDIATE`, no crash-safety guarantee).
+ * `putIfAbsent` adds atomic create-only writes; optional `sizeOf` reports original bytes
+ * without reading payloads (successful filesystem sizes are cached by content-addressed key).
  *
  * Interfaces only — no feature logic.
  */
@@ -162,6 +164,14 @@ export interface BlobStorePort {
     get(input: {
         storageKey: string;
     }): Promise<Uint8Array>;
+    /**
+     * Original byte count without reading the payload; null only when the key is absent.
+     * Other storage failures reject. Optional for older/custom adapters; consumers must report
+     * unknown size when unavailable, never download an entire blob just to count bytes.
+     */
+    sizeOf?(required: {
+        storageKey: string;
+    }, optional?: Record<string, never>): Promise<number | null>;
     exists(input: {
         storageKey: string;
     }): Promise<boolean>;

package/dist/media/repo.memory.js

@@ -1,3 +1,4 @@
+import { preserveMediaCreator } from "./created-by.js";
 export class InMemoryMediaRepo {
     rows;
     constructor(requiredArgs, optionalArgs = {}) {
@@ -19,7 +20,7 @@ export class InMemoryMediaRepo {
             this.rows.push(record);
             return;
         }
-        this.rows[index] = record;
+        this.rows[index] = preserveMediaCreator({ record, original: this.rows[index] });
     }
     async remove(required) {
         this.rows = this.rows.filter((row) => !(row.workspaceId === required.workspaceId && row.id === required.id));

package/dist/media/tool-registrations.js

@@ -31,6 +31,7 @@ function isMediaShapeRejection({ error }) {
 function toMediaToolView(record) {
     return {
         id: record.id,
+        createdBy: record.createdBy ?? null,
         slug: record.slug,
         title: record.title,
         alt: record.alt,

package/dist/media/types.d.ts

@@ -41,6 +41,10 @@ export interface MediaSource {
 export interface MediaRecord {
     id: UUID;
     workspaceId: UUID;
+    /** Acting principal at asset creation, independent of the producer/model and editable credit.
+     * Optional/null for records written before attribution existed. Never inferred from a shared
+     * blob's owner: identical bytes may have been uploaded by different principals. */
+    createdBy?: string | null | undefined;
     title: string;
     /**
      * Human-memorable, unique-per-workspace lookup key (owner-directed, 2026-09-07) — an ADDITIONAL

package/dist/navigation/menu-service.js

@@ -241,6 +241,12 @@ function validateTarget(target) {
     if (!VALID_TARGET_KINDS.has(kind)) {
         throw new MenuValidationError({ message: `unknown target kind '${kind}'` });
     }
+    if (kind === "entryRef" && target.lastKnownHref !== undefined) {
+        const rawHref = target.lastKnownHref;
+        if (typeof rawHref !== "string" || !rawHref.trim() || !isAllowedHref({ rawHref })) {
+            throw new MenuValidationError({ message: `entryRef lastKnownHref must be ${ALLOWED_HREF_SHAPES_DESCRIPTION}.` });
+        }
+    }
     if (kind === "url") {
         const rawHref = target.href;
         if (typeof rawHref !== "string" || !rawHref.trim()) {

package/dist/navigation/types.d.ts

@@ -49,6 +49,11 @@ export type ReservedNavTargetKind = "dynamicQuery" | "content";
 /** A link to another content entry (page/post/media/…). Integrity-tracked. */
 export interface NavEntryTarget {
     readonly kind: "entryRef";
+    /** Optional content-type hint for editors; reference integrity and routing still use entryId. */
+    readonly entryType?: string;
+    /** Author's last known URL, retained for exports and routing misses. A known unavailable
+     * entry must remain hidden; this snapshot never overrides an availability decision. */
+    readonly lastKnownHref?: string;
     /** Target entry id. Extracted to `entry_refs` at the write chokepoint. */
     readonly entryId: UUID;
 }

package/dist/settings/agent-value-write-tools.js

@@ -103,7 +103,7 @@ function rethrowWriteError(error, toolId, target, permission) {
  * @complexity O(value size + rule count) plus bounded repository calls and a human wait.
  * @throws ToolInputError for invalid input, denied keys, absent/declined/stale confirmation. */
 export function buildSettingsValueWriteHandler(deps, toolId) {
-    return async (ctx) => {
+    return async (ctx, options) => {
         const target = parseTarget(toolId, ctx.input);
         const permission = deriveRequiredPermission({ scope: target.scope, callerPrincipalId: ctx.principal.id });
         const isSet = toolId === "settings_set_value";
@@ -124,7 +124,7 @@ export function buildSettingsValueWriteHandler(deps, toolId) {
             if (rule) {
                 if (!deps.confirmWrite)
                     throw new ToolInputError({ message: `${toolId}: '${rule.namespace}.${rule.key}' requires a human confirmation card: ${rule.reason}. The owner can change it in Settings.` });
-                const confirmed = await deps.confirmWrite({ ctx, toolId, namespace: rule.namespace, key: rule.key, scope: target.scope, previous: structuredClone(previous), ...(isSet ? { value: structuredClone(target.value) } : {}), reason: rule.reason });
+                const confirmed = await deps.confirmWrite({ ctx, toolId, namespace: rule.namespace, key: rule.key, scope: target.scope, previous: structuredClone(previous), ...(isSet ? { value: structuredClone(target.value) } : {}), reason: rule.reason }, options);
                 if (confirmed !== true)
                     throw new ToolInputError({ message: `${toolId}: the human did not confirm the change. Nothing was changed.` });
                 const current = await resolveTarget(deps, target, isSet);

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

@@ -11,7 +11,7 @@ import type { Clock } from "@jini-ai/core/primitives";
 import type { AuthorizeFn } from "../core/commands/command.js";
 import { type SettingsWriteConfirmation } from "./agent-value-write-tools.js";
 import { type AgentSettingWriteRule } from "./agent-write-denylist.js";
-import { type DerivedRiskByToolId, type ToolRegistration } from "@jini-ai/core";
+import { type DerivedRiskByToolId, type ToolExecutionOptions, type ToolRegistration } from "@jini-ai/core";
 import type { SettingsPrincipalLookupPort } from "./principal-lookup.js";
 import type { SettingsRepoPort } from "./ports.js";
 import { set as setSettingValue } from "./write-service.js";
@@ -33,8 +33,10 @@ export interface SettingsToolDeps {
     /** Host extensions: explicit deny or human-confirmation rules, never agent inputs. */
     extraDeniedSettings?: readonly AgentSettingWriteRule[];
     extraConfirmationSettings?: readonly AgentSettingWriteRule[];
-    /** Must obtain an authenticated human card decision; absent means protected keys fail closed. */
-    confirmWrite?: (request: SettingsWriteConfirmation) => Promise<boolean>;
+    /** Must obtain an authenticated human card decision; absent means protected keys fail closed.
+     * `options` is the invoking transport's execution options (its `emitSurface`), forwarded from the
+     * tool handler's second argument: the card can only reach a human through that seam. */
+    confirmWrite?: (request: SettingsWriteConfirmation, options?: ToolExecutionOptions) => Promise<boolean>;
     /** Host's validation wrapper; defaults to the package's existing set chokepoint. */
     setValue?: typeof setSettingValue;
 }

package/dist/taxonomy/write-service.d.ts

@@ -352,12 +352,14 @@ export interface UnassignTermsRequired {
  * authorize -> validateAssignmentTarget -> write -> stamp -> outbox chokepoint as `assignTerms`,
  * and — like `assignTerms` — never produces a `taxonomy_revisions` row ( disclosed
  * narrowing applies equally to removal). Idempotent: unassigning a row that isn't there is a no-op,
- * not an error (`remove`'s 0-vs-1 return is intentionally not surfaced to the caller). Chosen over
+ * not an error. Only removed ids are returned, stamped, and emitted; an entirely absent set is a no-op. Chosen over
  * a "set terms" replace call — see the taxonomy plan's "What the docs settle" #3 for why replace
  * risks silently erasing a concurrent assignment.
  * See docs/decisions/DR-005-ordered-taxonomy-validation.md.
  */
-export declare function unassignTerms(required: UnassignTermsRequired, _optional?: Record<string, never>): Promise<void>;
+export declare function unassignTerms(required: UnassignTermsRequired, _optional?: Record<string, never>): Promise<{
+    removedTermIds: string[];
+}>;
 export interface EntryTermsCleanupPort {
     deleteByContent(params: {
         workspaceId: string;

package/dist/taxonomy/write-service.js

@@ -408,7 +408,7 @@ export async function assignTerms(required, _optional = {}) {
  * authorize -> validateAssignmentTarget -> write -> stamp -> outbox chokepoint as `assignTerms`,
  * and — like `assignTerms` — never produces a `taxonomy_revisions` row ( disclosed
  * narrowing applies equally to removal). Idempotent: unassigning a row that isn't there is a no-op,
- * not an error (`remove`'s 0-vs-1 return is intentionally not surfaced to the caller). Chosen over
+ * not an error. Only removed ids are returned, stamped, and emitted; an entirely absent set is a no-op. Chosen over
  * a "set terms" replace call — see the taxonomy plan's "What the docs settle" #3 for why replace
  * risks silently erasing a concurrent assignment.
  * See docs/decisions/DR-005-ordered-taxonomy-validation.md.
@@ -417,19 +417,24 @@ export async function unassignTerms(required, _optional = {}) {
     const { deps, principalId, contentType, contentId, termIds } = required;
     await authorizeTaxonomyManage(deps, principalId);
     await validateAssignmentTarget(deps, contentType, contentId, termIds);
+    const removedTermIds = [];
     for (const termId of termIds) {
-        await deps.entryTerms.remove({ contentType, contentId, termId });
+        if (await deps.entryTerms.remove({ contentType, contentId, termId }) > 0)
+            removedTermIds.push(termId);
     }
+    if (removedTermIds.length === 0)
+        return { removedTermIds };
     const now = kernelNowIso({ clock: deps.clock });
     await deps.stampWatermark({});
     await deps.outbox.enqueue({ event: {
             name: "taxonomy.terms_unassigned",
             contentType,
             contentId,
-            termIds,
+            termIds: removedTermIds,
             actorId: principalId,
             occurredAt: now,
         } });
+    return { removedTermIds };
 }
 /** Content-deletion event subscriber. Best-effort (a missed event leaves an orphaned
  * `entry_terms` row that is inert on read; a periodic/boot reconciliation sweep — modeled by

package/dist/trash/write-service.js

@@ -95,12 +95,16 @@ export function createTrashService(deps, optional = {}) {
                         priorMarker: marker.priorMarker ?? trashOptional.priorMarker ?? null,
                     };
                     await deps.repo.insert({ row });
-                    await notifyChanged(optional, {
-                        workspaceId: required.workspaceId,
-                        entityType: required.entityType,
-                        entityId: required.entityId,
-                        change: "trash",
-                    });
+                    // A successful noop may repair a missing index, but did not change the domain marker.
+                    // Repeated removal must not emit another recovery watermark or outbox event (F1487).
+                    if (!marker.noop) {
+                        await notifyChanged(optional, {
+                            workspaceId: required.workspaceId,
+                            entityType: required.entityType,
+                            entityId: required.entityId,
+                            change: "trash",
+                        });
+                    }
                     return marker;
                 }
             });
@@ -135,12 +139,15 @@ export function createTrashService(deps, optional = {}) {
                     if (!marker.ok)
                         return marker.reason === "not-found" ? "not-found" : "version-changed";
                     await deps.repo.deleteById({ workspaceId: required.workspaceId, id: row.id });
-                    await notifyChanged(optional, {
-                        workspaceId: required.workspaceId,
-                        entityType: required.entityType,
-                        entityId: required.entityId,
-                        change: "restore",
-                    });
+                    // An already-clear marker still needs index cleanup, without a duplicate notification.
+                    if (!marker.noop) {
+                        await notifyChanged(optional, {
+                            workspaceId: required.workspaceId,
+                            entityType: required.entityType,
+                            entityId: required.entityId,
+                            change: "restore",
+                        });
+                    }
                     return "restored";
                 }
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/cms",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Content-model capability for Jini-hosted products: framework-free contracts, ports, and domain services in `/core` and per-domain subpaths; Node-bound adapters in domain-specific subpaths.",
   "license": "Apache-2.0",
   "repository": {
@@ -132,7 +132,7 @@
     "@jini-ai/http-kit": "0.4.0"
   },
   "dependencies": {
-    "@jini-ai/core": "0.4.0"
+    "@jini-ai/core": "^0.4.0"
   },
   "peerDependencies": {
     "sharp": "^0.35.3",