@try-works/dsh-memory 0.1.32 → 0.2.1

package/src/assets/index.js

@@ -0,0 +1,648 @@
+// The asset store: the contract surface the agent tools use.
+//
+// An asset is an ENTRY (metadata + documentation, searchable) plus a BLOB (content-addressed bytes).
+// This module orchestrates the pipeline from docs/asset-store-proposal.md section 5.5:
+//   classify -> toggle -> size -> quota -> sha256/dedupe -> LFS gate -> blob -> entry -> inventory
+//
+// It is a catalogue, not a text index: nothing is extracted from a file, and no query path here
+// walks the blob tree. `list` and `usage` read entries only; `get` touches exactly one blob.
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join, relative } from 'node:path'
+
+import { allocateId, nowIso, parseEntries, scopeIdFor } from '../entry.js'
+import { appendToTopic, layerIndexPath, layerText, readLayerTopics, rebuildLayerIndex } from '../layers.js'
+import { updateIndex } from '../fts.js'
+import { sanitizeKey } from '../workspace-key.js'
+import { record } from '../telemetry.js'
+import { DEFAULT_CONFIG } from '../defaults.js'
+import {
+  ASSET_CLASSES,
+  addQuotaNotice as addQuotaNoticeAt,
+  canonicalMime,
+  classify,
+  extensionForMime,
+  normalizeMime,
+  quotaBytesFor,
+  readPolicy,
+  readQuotaNotices as readQuotaNoticesAt,
+  resolveToggles,
+  toggleRefusal,
+  writePolicy,
+} from './policy.js'
+import {
+  deleteObjectFiles,
+  objectBytesOnDisk,
+  readInventory,
+  readObject,
+  releaseObjectRef,
+  sha256,
+  upsertObjectRef,
+  writeObject,
+} from './objects.js'
+import { parseAssetEntry, renderAssetEntry } from './entry.js'
+import { ensureLfs } from './lfs.js'
+
+// The four policy-facing pieces are re-exported from here: tools import ONE module.
+export { classify, readPolicy, resolveToggles, writePolicy } from './policy.js'
+
+/** Standard error shape. A failure always names a stable code from the contract. */
+function fail(code, message, detail) {
+  return detail === undefined ? { ok: false, code, message } : { ok: false, code, message, detail }
+}
+
+/** A store may be a MemoryStore or its root path; the tools hold one, the tests the other. */
+function rootOf(store) {
+  if (typeof store === 'string' && store !== '') return store
+  if (store !== null && store !== undefined && typeof store.root === 'string' && store.root !== '') return store.root
+  throw new Error('assets: expected a MemoryStore or a store root path')
+}
+
+/**
+ * Read the stored quota notices, newest first. An automatic capture cannot ask a question, so it
+ * records the wall it met here and `memory_status` reads it. Accepts a store or a root path.
+ */
+export function readQuotaNotices(store) {
+  return readQuotaNoticesAt(rootOf(store))
+}
+
+/** Record (and dedupe by scope+key) a quota notice. Accepts a store or a root path. */
+export function addQuotaNotice(store, notice = {}) {
+  return addQuotaNoticeAt(rootOf(store), notice)
+}
+
+function numberOr(value, fallback) {
+  const number = Number(value)
+  return Number.isFinite(number) ? number : fallback
+}
+
+function nowValue(now) {
+  if (typeof now === 'function') now = now()
+  if (now instanceof Date) return Number.isNaN(now.getTime()) ? nowIso() : now.toISOString()
+  if (typeof now === 'string' && now !== '') return now
+  if (typeof now === 'number' && Number.isFinite(now)) return new Date(now).toISOString()
+  return nowIso()
+}
+
+function relPath(root, file) { return relative(root, file).replace(/\\/g, '/') }
+
+/** The workspace directories present in the store. */
+function workspaceKeys(root) {
+  let entries = []
+  try { entries = readdirSync(join(root, 'workspaces'), { withFileTypes: true }) } catch { return [] }
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort()
+}
+
+/**
+ * Selectors for a scope argument: global, one workspace, or both (the default). `null` means the
+ * caller asked for a workspace without a usable key.
+ */
+function selectorsFor(root, scope, key) {
+  if (scope === 'global') return [{ scope: 'global', key: undefined }]
+  if (scope === 'workspace') {
+    const safe = sanitizeKey(key)
+    return safe === undefined ? null : [{ scope: 'workspace', key: safe }]
+  }
+  return [{ scope: 'global', key: undefined }, ...workspaceKeys(root).map((workspaceKey) => ({ scope: 'workspace', key: workspaceKey }))]
+}
+
+/** Asset entries of one scope. Reads entry files only - never an object. */
+function assetsInScope(root, scope, key) {
+  let topics = []
+  try { topics = readLayerTopics(root, scope, key, 'asset') } catch { return [] }
+  const assets = []
+  for (const topic of topics) {
+    const file = relPath(root, topic.file)
+    for (const entry of topic.entries) {
+      const asset = parseAssetEntry(entry)
+      if (asset === undefined) continue
+      assets.push({ ...asset, scope, key, file })
+    }
+  }
+  return assets
+}
+
+function collectAssets(root, selectors) {
+  const assets = []
+  for (const selector of selectors ?? []) assets.push(...assetsInScope(root, selector.scope, selector.key))
+  return assets
+}
+
+function isLive(asset) { return asset.status !== 'superseded' && asset.status !== 'deleted' }
+
+/** The list projection, exactly the fields the contract names. */
+function publicAsset(asset) {
+  return {
+    id: asset.id,
+    name: asset.name,
+    class: asset.class,
+    mime: asset.mime,
+    bytes: asset.bytes,
+    sha256: asset.sha256,
+    date: asset.date,
+    heading: asset.heading,
+    file: asset.file,
+  }
+}
+
+/** The richer metadata `getAsset` returns; the tools may report it verbatim. */
+function assetMetadata(asset) {
+  const metadata = {
+    ...publicAsset(asset),
+    scope: asset.scope,
+    // `key` is undefined for a global asset. Optional fields are OMITTED, never blanked: a tool
+    // result carrying `undefined` is not lossless JSON (the harness rejects it, and
+    // JSON.stringify silently drops the key, so the model would see a different value than the
+    // tool returned). The sweep at the end applies that rule to every field below at once.
+    ...(asset.key === undefined ? {} : { key: asset.key }),
+    status: asset.status,
+    origin: asset.origin,
+    usedFor: asset.usedFor,
+    description: asset.description,
+    whatItIs: asset.whatItIs,
+    whenToRead: asset.whenToRead,
+  }
+  for (const field of Object.keys(metadata)) if (metadata[field] === undefined) delete metadata[field]
+  return metadata
+}
+
+/**
+ * Per-scope byte maps built from the entries and the inventory. The inventory holds BYTES; only the
+ * entries hold SCOPE, so the two are joined here once and reused by usage and the quota gate.
+ */
+function collectUsage(root) {
+  const assets = collectAssets(root, selectorsFor(root, 'all')).filter(isLive)
+  const inventory = readInventory(root)
+  const scopes = new Map([['global', new Map()]])
+  for (const asset of assets) {
+    if (!asset.sha256) continue
+    const scopeKey = asset.scope === 'global' ? 'global' : asset.key
+    let map = scopes.get(scopeKey)
+    if (map === undefined) { map = new Map(); scopes.set(scopeKey, map) }
+    if (!map.has(asset.sha256)) map.set(asset.sha256, asset.bytes)
+  }
+  return { assets, inventory, scopes }
+}
+
+function bytesOfObject(inventory, hash, fallback) {
+  const stored = inventory[hash]
+  const bytes = stored === undefined || stored === null ? NaN : Number(stored.bytes)
+  return Number.isFinite(bytes) && bytes >= 0 ? bytes : numberOr(fallback, 0)
+}
+
+function sumScope(inventory, map) {
+  if (map === undefined) return 0
+  let total = 0
+  for (const [hash, fallback] of map) total += bytesOfObject(inventory, hash, fallback)
+  return total
+}
+
+function largestInScope(root, { scope, key }) {
+  const selectors = selectorsFor(root, scope, key)
+  if (selectors === null) return []
+  return collectAssets(root, selectors)
+    .filter(isLive)
+    .sort((a, b) => b.bytes - a.bytes)
+    .slice(0, 3)
+    .map((asset) => ({ name: asset.name, bytes: asset.bytes, id: asset.id }))
+}
+
+/**
+ * Per-scope byte usage + quotas, read from entries and the inventory only (no blob walk).
+ *
+ * - `global` / `workspaces`: logical bytes stored in each scope. An object deduped into two scopes
+ *   counts in both, because deleting one scope's entry does not free the bytes for the other.
+ * - `totalBytes`: the unique object bytes the store actually holds, for the GitHub LFS ceiling.
+ * - `perClass`: how many live assets each class holds.
+ * - `quota`: the effective quota per scope (the policy override, else the configured value).
+ */
+export function usage(store, cfg = {}) {
+  const root = rootOf(store)
+  const policy = readPolicy(root)
+  const { assets, inventory, scopes } = collectUsage(root)
+  const global = sumScope(inventory, scopes.get('global'))
+  const workspaces = {}
+  for (const [scopeKey, map] of scopes) {
+    if (scopeKey === 'global') continue
+    workspaces[scopeKey] = sumScope(inventory, map)
+  }
+  const quotaWorkspaces = {}
+  const quotaKeys = new Set([...Object.keys(workspaces), ...Object.keys(policy.workspaces ?? {})])
+  for (const workspaceKey of quotaKeys) {
+    quotaWorkspaces[workspaceKey] = quotaBytesFor(cfg, policy, { scope: 'workspace', key: workspaceKey })
+  }
+  const uniqueHashes = new Map()
+  for (const asset of assets) {
+    if (!asset.sha256 || uniqueHashes.has(asset.sha256)) continue
+    uniqueHashes.set(asset.sha256, asset.bytes)
+  }
+  let totalBytes = 0
+  for (const [hash, fallback] of uniqueHashes) totalBytes += bytesOfObject(inventory, hash, fallback)
+  const perClass = { documents: 0, media: 0, data: 0 }
+  for (const asset of assets) {
+    if (Object.hasOwn(perClass, asset.class)) perClass[asset.class] += 1
+  }
+  return {
+    global,
+    workspaces,
+    quota: {
+      global: quotaBytesFor(cfg, policy, { scope: 'global' }),
+      workspaces: quotaWorkspaces,
+    },
+    totalBytes,
+    perClass,
+  }
+}
+
+/**
+ * The numbers `memory_status` needs, without the per-scope detail. A convenience over `usage`.
+ */
+export function assetBytesReport(store, cfg = {}) {
+  const report = usage(store, cfg)
+  return {
+    totalBytes: report.totalBytes,
+    perClass: report.perClass,
+    global: report.global,
+    workspaces: report.workspaces,
+    quota: report.quota,
+  }
+}
+
+// --- capture --------------------------------------------------------------------------------
+
+function toBytes(value) {
+  if (Buffer.isBuffer(value)) return value
+  if (value instanceof Uint8Array) return Buffer.from(value)
+  if (value instanceof ArrayBuffer) return Buffer.from(new Uint8Array(value))
+  if (typeof value === 'string') return Buffer.from(value, 'utf8')
+  return undefined
+}
+
+function loadBytes(input) {
+  if (input.bytes !== undefined && input.bytes !== null) {
+    const bytes = toBytes(input.bytes)
+    if (bytes === undefined) return fail('missing-bytes', 'bytes must be a Buffer, Uint8Array, ArrayBuffer or string')
+    return { ok: true, bytes }
+  }
+  if (input.path !== undefined && input.path !== null && String(input.path) !== '') {
+    const file = String(input.path)
+    if (!existsSync(file)) return fail('missing-bytes', 'no file at ' + file)
+    try { return { ok: true, bytes: readFileSync(file) } } catch (error) {
+      return fail('read-failed', 'could not read ' + file + ': ' + String(error?.message ?? error))
+    }
+  }
+  return fail('missing-bytes', 'putAsset needs bytes or a path')
+}
+
+function firstLine(text, max = 200) {
+  const line = String(text ?? '').split('\n').map((part) => part.trim()).find((part) => part.length > 0)
+  if (line === undefined) return undefined
+  const collapsed = line.replace(/\s+/g, ' ')
+  if (collapsed.length <= max) return collapsed
+  return [...collapsed].slice(0, max - 1).join('') + '…'
+}
+
+function entryHeading(name) {
+  const cleaned = String(name ?? '').replace(/[\r\n]+/g, ' ').trim()
+  if (cleaned === '') return 'asset'
+  const points = [...cleaned]
+  return points.length > 80 ? points.slice(0, 79).join('') + '…' : cleaned
+}
+
+function deterministicUsedFor(context, name) {
+  const message = firstLine(context?.userMessage, 160)
+  if (message !== undefined) return 'Captured while handling: ' + message
+  const task = firstLine(context?.task, 120)
+  if (task !== undefined) return 'Captured while working on: ' + task
+  return 'Stored for later reuse: ' + name
+}
+
+/**
+ * Deterministic documentation from capture context. This is the floor the proposal promises:
+ * capture never fails for want of a description, and the two headings always exist so the entry is
+ * searchable by what it was captured for.
+ */
+function fallbackDocumentation(context, meta) {
+  const message = firstLine(context?.userMessage, 180)
+  const task = firstLine(context?.task, 140)
+  const tool = firstLine(context?.toolCall, 120)
+  const whatItIs = 'A ' + meta.class + ' file named "' + meta.name + '" (' + meta.mime + ', '
+    + meta.bytes + ' bytes).' + (task === undefined ? '' : ' Captured while working on: ' + task + '.')
+  let whenToRead
+  if (message !== undefined) {
+    whenToRead = 'Read this when the user revisits the request it was captured for: "' + message
+      + '". Open it before answering from memory alone.'
+  } else if (tool !== undefined) {
+    whenToRead = 'Read this when following up on "' + tool + '".'
+  } else {
+    whenToRead = 'Read this when the user needs the ' + meta.class + ' file "' + meta.name + '".'
+  }
+  return { whatItIs, whenToRead, notes: undefined }
+}
+
+function cleanText(value) {
+  const text = String(value ?? '').trim()
+  return text === '' ? undefined : text
+}
+
+function normalizeDocumentation(value) {
+  if (value === null || value === undefined || typeof value !== 'object') return undefined
+  const whatItIs = cleanText(value.whatItIs)
+  const whenToRead = cleanText(value.whenToRead)
+  if (whatItIs === undefined && whenToRead === undefined) return undefined
+  return {
+    whatItIs,
+    whenToRead,
+    notes: cleanText(value.notes),
+    description: cleanText(value.description),
+    usedFor: cleanText(value.usedFor),
+  }
+}
+
+/**
+ * Resolve the documentation. Order: explicit `documentation` (or whatItIs/whenToRead), then an
+ * injected `describe` function (await inside putAsset, one entry write), then the deterministic
+ * floor. Any missing section is filled from the floor so both headings always exist.
+ */
+async function resolveDocumentation(input, meta) {
+  const base = fallbackDocumentation(input.context, meta)
+  const supplied = normalizeDocumentation(input.documentation)
+    ?? normalizeDocumentation({ whatItIs: input.whatItIs, whenToRead: input.whenToRead, notes: input.notes })
+  if (supplied !== undefined) {
+    return {
+      whatItIs: supplied.whatItIs ?? base.whatItIs,
+      whenToRead: supplied.whenToRead ?? base.whenToRead,
+      notes: supplied.notes,
+      description: supplied.description,
+      usedFor: supplied.usedFor,
+    }
+  }
+  if (typeof input.describe === 'function') {
+    try {
+      const described = normalizeDocumentation(await input.describe({
+        class: meta.class,
+        mime: meta.mime,
+        name: meta.name,
+        bytes: meta.bytes,
+        context: input.context,
+        llm: input.llm,
+      }))
+      if (described !== undefined) {
+        return {
+          whatItIs: described.whatItIs ?? base.whatItIs,
+          whenToRead: described.whenToRead ?? base.whenToRead,
+          notes: described.notes,
+          description: described.description,
+          usedFor: described.usedFor,
+        }
+      }
+    } catch { /* the deterministic floor is the contract; a model is an enhancement */ }
+  }
+  return base
+}
+
+/**
+ * Store one asset: blob + entry + inventory, after toggles, size and quota checks.
+ * @see docs/asset-api-contract.md for the input/output shape and the stable error codes.
+ */
+export async function putAsset(store, cfg = {}, input = {}) {
+  const root = rootOf(store)
+  const scope = input.scope === 'global' ? 'global' : 'workspace'
+  const key = scope === 'workspace' ? sanitizeKey(input.key) : undefined
+  if (scope === 'workspace' && key === undefined) return fail('write-failed', 'workspace asset capture needs a workspace key')
+
+  const sourcePath = input.path === undefined || input.path === null || String(input.path) === '' ? undefined : String(input.path)
+  const suppliedName = input.name === undefined || input.name === null ? undefined : String(input.name)
+  const name = suppliedName ?? (sourcePath === undefined ? undefined : basename(sourcePath))
+
+  const claimed = input.class === undefined
+    ? classify({ name, mime: input.mime })
+    : (ASSET_CLASSES.includes(String(input.class)) ? String(input.class) : undefined)
+  if (claimed === undefined) {
+    if (input.class !== undefined) {
+      return fail('unsupported-class', 'unsupported asset class "' + String(input.class) + '"; use documents, media or data')
+    }
+    return fail(
+      'unsupported-class',
+      'no asset class claims ' + JSON.stringify(name ?? normalizeMime(input.mime) ?? 'the input')
+        + '; accepted: PDF/DOCX/PPTX/TXT/MD (documents), PNG/JPEG/WebP/GIF (media), CSV/TSV/JSON/XLSX (data)',
+    )
+  }
+  const assetClass = claimed
+
+  const refusal = toggleRefusal(cfg, root, { scope, key, class: assetClass })
+  if (refusal !== undefined) {
+    return fail('toggle-off', refusal.message, { scope, key: key ?? null, class: assetClass, level: refusal.level })
+  }
+
+  const loaded = loadBytes(input)
+  if (loaded.ok !== true) return loaded
+  const bytes = loaded.bytes
+
+  const maxBytes = numberOr(cfg?.assetsMaxBytes, DEFAULT_CONFIG.assetsMaxBytes)
+  if (bytes.length > maxBytes) {
+    return fail('file-too-large', 'asset is ' + bytes.length + ' bytes; the per-file limit is ' + maxBytes + ' bytes', { bytes: bytes.length, limit: maxBytes })
+  }
+
+  const mime = canonicalMime({ name, mime: input.mime })
+  const displayName = name !== undefined && String(name).trim() !== ''
+    ? String(name).trim()
+    : 'asset.' + extensionForMime(mime)
+  const hash = sha256(bytes)
+
+  // Quota: refuse, surface the figures, never prune. The caller asks the user; this function only
+  // reports. `allowOverQuota` is the one-shot "forgive this capture" bypass.
+  const { inventory, scopes } = collectUsage(root)
+  const scopeKey = scope === 'global' ? 'global' : key
+  const usedBytes = sumScope(inventory, scopes.get(scopeKey))
+  const dedupedInScope = scopes.get(scopeKey)?.has(hash) === true
+  const quotaBytes = quotaBytesFor(cfg, readPolicy(root), { scope, key })
+  const projected = usedBytes + (dedupedInScope ? 0 : bytes.length)
+  if (input.allowOverQuota !== true && projected > quotaBytes) {
+    return fail(
+      'quota-exceeded',
+      'asset quota reached for ' + (scope === 'global' ? 'the global scope' : 'workspace ' + key)
+        + ' (' + usedBytes + ' of ' + quotaBytes + ' bytes used)',
+      { scope, key: key ?? null, usedBytes, quotaBytes, largest: largestInScope(root, { scope, key }) },
+    )
+  }
+
+  // Nothing is written until the LFS gate passes, so a machine without Git LFS cannot accumulate
+  // objects that would be committed as raw bytes instead of LFS-tracked content.
+  const lfs = await ensureLfs(root, { run: input.runner })
+  if (lfs.ok !== true) return fail(lfs.code ?? 'lfs-unavailable', lfs.message)
+
+  const deduped = inventory[hash] !== undefined
+  const object = writeObject(root, mime, hash, bytes)
+  if (object.ok !== true) return object
+
+  const documentation = await resolveDocumentation(input, { class: assetClass, mime, name: displayName, bytes: bytes.length })
+  const usedFor = cleanText(input.usedFor) ?? documentation.usedFor ?? deterministicUsedFor(input.context, displayName)
+
+  let id
+  let file
+  try {
+    const scopeId = scopeIdFor(scope, key)
+    id = allocateId(layerText(root, scope, key, 'asset'), scopeId, 'asset')
+    const heading = entryHeading(displayName)
+    const block = renderAssetEntry({
+      id,
+      source: input.source !== undefined && input.source !== null ? String(input.source) : 'agent',
+      date: nowValue(input.now),
+      importance: input.importance ?? 2,
+      status: 'active',
+      heading,
+      asset: {
+        class: assetClass,
+        mime,
+        bytes: bytes.length,
+        sha256: hash,
+        name: displayName,
+        origin: input.origin ?? sourcePath ?? 'inline',
+        usedFor,
+        description: documentation.description,
+      },
+      documentation,
+    })
+    file = appendToTopic(root, scope, key, 'asset', heading, block)
+    rebuildLayerIndex(root, scope, key, 'asset')
+    updateIndex(root, [file, layerIndexPath(root, scope, key, 'asset')])
+  } catch (error) {
+    return fail('write-failed', 'could not write the asset entry: ' + String(error?.message ?? error))
+  }
+
+  upsertObjectRef(root, { sha256: hash, bytes: bytes.length, mime, created: nowValue(input.now) })
+  record(root, 'asset-added', { detail: { class: assetClass, bytes: bytes.length, sha256: hash, dedupe: deduped } })
+  return {
+    ok: true,
+    entryId: id,
+    sha256: hash,
+    bytes: bytes.length,
+    deduped,
+    entryPath: relPath(root, file),
+  }
+}
+
+// --- retrieval ------------------------------------------------------------------------------
+
+/**
+ * Resolve one asset to metadata and optionally copy the bytes out. The only path that reads a blob,
+ * and it reads exactly one. A missing object or an LFS pointer is reported as `missing-bytes` with
+ * the fix, never fabricated.
+ */
+export async function getAsset(store, cfg = {}, { id, sha256: wantedSha, toPath } = {}) {
+  const root = rootOf(store)
+  const wantedId = id === undefined || id === null ? undefined : String(id)
+  const wantedHash = wantedSha === undefined || wantedSha === null ? undefined : String(wantedSha)
+  if (wantedId === undefined && wantedHash === undefined) return fail('not-found', 'getAsset needs an asset id or sha256')
+
+  const candidates = collectAssets(root, selectorsFor(root, 'all'))
+  let hit
+  if (wantedId !== undefined) hit = candidates.find((asset) => asset.id === wantedId)
+  if (hit === undefined && wantedHash !== undefined) hit = candidates.find((asset) => asset.sha256 === wantedHash && isLive(asset))
+  if (hit === undefined) {
+    return fail('not-found', 'no asset ' + (wantedId !== undefined ? 'entry with id ' + wantedId : 'with sha256 ' + wantedHash))
+  }
+
+  const read = readObject(root, hit.mime, hit.sha256)
+  if (read.ok !== true) return fail(read.code, read.message)
+  const metadata = assetMetadata(hit)
+
+  if (toPath === undefined || toPath === null || String(toPath) === '') {
+    return { ok: true, metadata, bytes: read.bytes }
+  }
+  let target = String(toPath)
+  if (target.endsWith('/') || target.endsWith('\\')) target = join(target, hit.name ?? 'asset')
+  else try { if (statSync(target).isDirectory()) target = join(target, hit.name ?? 'asset') } catch { /* path does not exist yet: a file */ }
+  try {
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, read.bytes)
+  } catch (error) {
+    return fail('write-failed', 'could not copy the asset to ' + target + ': ' + String(error?.message ?? error))
+  }
+  return { ok: true, metadata, path: target }
+}
+
+/**
+ * List asset entries in a scope, newest first, bounded. Reads entries only; an object on disk that
+ * is missing, a pointer, or unreadable does not affect the listing.
+ */
+export function listAssets(store, { scope, key, class: assetClass, limit } = {}) {
+  const root = rootOf(store)
+  const selectors = selectorsFor(root, scope === undefined || scope === null ? 'all' : String(scope), key)
+  if (selectors === null) return fail('not-found', 'workspace scope needs a valid workspace key')
+  let assets = collectAssets(root, selectors).filter(isLive)
+  if (assetClass !== undefined && assetClass !== null && String(assetClass) !== '') {
+    assets = assets.filter((asset) => asset.class === String(assetClass))
+  }
+  assets.sort((a, b) => {
+    const byDate = String(b.date ?? '').localeCompare(String(a.date ?? ''))
+    return byDate !== 0 ? byDate : String(b.id ?? '').localeCompare(String(a.id ?? ''))
+  })
+  const bound = limit === undefined || limit === null
+    ? 50
+    : Math.max(1, Math.min(1000, Math.floor(numberOr(limit, 50))))
+  return { ok: true, assets: assets.slice(0, bound).map(publicAsset) }
+}
+
+/**
+ * Remove one entry block from its topic file. The entry is deleted (not superseded): an asset entry
+ * without its blob is a promise the store cannot keep, and the contract says forget deletes.
+ */
+function removeEntryBlock(file, id) {
+  let text
+  try { text = readFileSync(file, 'utf8') } catch { return fail('read-failed', 'could not read ' + file) }
+  const target = parseEntries(text).find((entry) => entry.id === id)
+  if (target === undefined) return fail('not-found', 'entry ' + id + ' is not in ' + file)
+  const lines = text.split('\n')
+  const before = lines.slice(0, target.startLine - 1)
+  const after = lines.slice(target.endLine)
+  while (after.length > 0 && after[0].trim() === '') after.shift()
+  const next = [...before, ...(after.length > 0 ? ['', ...after] : [])].join('\n')
+  try { writeFileSync(file, next, 'utf8') } catch (error) {
+    return fail('write-failed', 'could not rewrite ' + file + ': ' + String(error?.message ?? error))
+  }
+  return { ok: true }
+}
+
+/**
+ * Delete the entry; decrement the object's refcount and delete the blob when it reaches zero. The
+ * logical bytes freed are reported so a caller can explain what changed.
+ */
+export function forgetAsset(store, cfg = {}, { id } = {}) {
+  const root = rootOf(store)
+  const wantedId = id === undefined || id === null ? undefined : String(id)
+  if (wantedId === undefined) return fail('not-found', 'forgetAsset needs an asset id')
+  const hit = collectAssets(root, selectorsFor(root, 'all')).find((asset) => asset.id === wantedId)
+  if (hit === undefined) return fail('not-found', 'no asset entry with id ' + wantedId)
+
+  const file = join(root, ...String(hit.file).split('/'))
+  const removed = removeEntryBlock(file, wantedId)
+  if (removed.ok !== true) return removed
+  try {
+    rebuildLayerIndex(root, hit.scope, hit.key, 'asset')
+    updateIndex(root, [file, layerIndexPath(root, hit.scope, hit.key, 'asset')])
+  } catch (error) {
+    return fail('write-failed', 'could not update the asset index: ' + String(error?.message ?? error))
+  }
+
+  const release = releaseObjectRef(root, hit.sha256)
+  let objectDeleted = false
+  let bytesFreed = 0
+  if (release.found) {
+    if (release.refs === 0) {
+      const deleted = deleteObjectFiles(root, hit.sha256)
+      objectDeleted = deleted > 0
+      bytesFreed = deleted > 0 ? release.bytes : 0
+    }
+  } else {
+    // Inventory drift: fall back to the remaining entries that still reference the object. If none
+    // do, the blob is unreachable and is cleaned up like a normal last-reference delete.
+    const remaining = collectAssets(root, selectorsFor(root, 'all')).filter((asset) => asset.sha256 === hit.sha256)
+    if (remaining.length === 0) {
+      const deleted = deleteObjectFiles(root, hit.sha256)
+      objectDeleted = deleted > 0
+      bytesFreed = deleted > 0 ? objectBytesOnDisk(root, hit.sha256) : 0
+    }
+  }
+  return { ok: true, entryId: wantedId, objectDeleted, bytesFreed }
+}