dsh-all-usage 1.2.2 → 1.2.4

package/lib/http.js

@@ -159,7 +159,7 @@ export function registerRoutes(host) {
   const { runBaseline } = host.sessionSync
   const { fetchBalance } = host.balance
   const { setAlias } = host.aliases
-  const { drainLedgerWrites } = host.ledger
+  const { drainLedgerWrites, archiveLedger } = host.ledger
 
   // ---------- HTTP data routes for the client half ----------
   if (webServer !== undefined) {
@@ -275,6 +275,32 @@ export function registerRoutes(host) {
         sendJson(res, result.ok ? 200 : 502, result)
       },
     }))
+    ctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: '/api/all-usage/archive',
+      // The only route that deletes ledger documents, so it takes the same write
+      // capability as the pricing writes and a body it does not otherwise need.
+      handler: async (req, res) => {
+        if (req.method !== 'POST') { res.statusCode = 405; res.end(); return }
+        if (!isTrustedLocalApiRequest(req, false) || !hasWriteToken(req, state.requestToken)) { rejectRequest(res); return }
+        const body = await readBody(req, 8 * 1024)
+        if (body.tooLarge) { sendJson(res, 413, { ok: false, message: 'request-too-large' }); return }
+        let args = null
+        try { args = JSON.parse(body.text) } catch (err) { /* invalid json */ }
+        if (args === null || typeof args !== 'object' || Array.isArray(args)) { sendJson(res, 400, { ok: false, message: 'invalid-json' }); return }
+        const days = args.days === undefined ? 90 : Number(args.days)
+        if (!Number.isInteger(days) || days < 1 || days > 3650) { sendJson(res, 400, { ok: false, message: 'invalid-days' }); return }
+        // Only an explicit false writes: the panel's first request has to show the
+        // plan, and a client that forgets the flag must not delete anything.
+        const dryRun = args.dryRun !== false
+        await state.ledgerReady
+        const result = await archiveLedger({ days, dryRun })
+        // The body is the ledger's own answer, so the panel can show the plan (or
+        // the reason there is none) without a second shape to keep in sync.
+        const status = result.ok === true ? 200 : ({ busy: 409, 'no-root': 400, 'ledger-unavailable': 503 })[result.message] ?? 500
+        sendJson(res, status, result)
+      },
+    }))
     ctx.effect(() => webServer.register({
       kind: 'exact',
       path: '/api/all-usage/status',

package/lib/ledger.js

@@ -1,5 +1,7 @@
-import { readdir, readFile, stat, unlink, writeFile } from 'node:fs/promises'
+import { mkdir, readdir, readFile, rmdir, stat, unlink, writeFile } from 'node:fs/promises'
+import { hostname } from 'node:os'
 import { join } from 'node:path'
+import { archiveRecords, createArchiveReader } from './archive.js'
 import { recordKeyHash, recordKeyLocator } from './records-cache.js'
 import { calculateCost, normalizeCostSnapshot } from './pricing.js'
 import { billingInstantOf, contextTimeKey, extractUsageEvent, normalizeUsageValues as usageValues, pickPricingTime, touchContextTimes, upsertUsageSample as upsertUsageSampleState, usageStepKey } from './usage-core.js'
@@ -38,6 +40,13 @@ const LEDGER_SHARD_COUNT = 32
 const LEDGER_UNIT_NAME = 'all_usage_ledger'
 const LEDGER_META_KEY = '__all_usage_ledger_meta__'
 const LEDGER_WRITE_DEBOUNCE_MS = 25
+// A second DSH process can share this data root, and maintenance deletes files
+// the other one may still be reading. One lock guards every step that does: the
+// first migration and every retirement. Record writes never take it.
+const LEDGER_LOCK_OWNER_FILE = 'owner.json'
+// A holder silent for this long is treated as killed. The threshold has to exceed
+// the slowest honest migration, or a slow copy would be reclaimed while it runs.
+const LEDGER_LOCK_STALE_MS = 30000
 
 // DSH 0.1.5 replaced the Session `events` getter with `snapshotEvents()` while
 // 0.1.1 exposed `events`; both return the log in seq order. Read whichever the
@@ -101,11 +110,189 @@ function uniqueUnits(units) {
   return Array.from(new Set(units.filter((unit) => unit !== null && unit !== undefined)))
 }
 
-function createLedgerUnitStore(legacyUnit, shardUnits, root = '') {
+// The maintenance lock is a directory: mkdir is atomic, so exactly one process can
+// create it, and the owner document inside tells later readers who holds it and
+// since when. It is never taken around a record write.
+function ledgerMaintenanceLockDir(root) {
+  return join(root, LEDGER_UNIT_NAME + '.lock')
+}
+
+async function ledgerMaintenanceLockIsStale(dir, ownerFile) {
+  let startedAt = null
+  try {
+    const owner = JSON.parse(await readFile(ownerFile, 'utf8'))
+    if (owner !== null && typeof owner === 'object' && Number.isFinite(owner.startedAt)) startedAt = owner.startedAt
+  } catch (error) {
+    startedAt = null
+  }
+  if (startedAt !== null) return Date.now() - startedAt > LEDGER_LOCK_STALE_MS
+  // The owner document is written right after the directory is created, so a lock
+  // without one is either mid-acquisition or half-removed. Only the age of the
+  // directory tells those apart from a holder that never got to write it.
+  const info = await stat(dir).catch(() => null)
+  return info === null || Date.now() - info.mtimeMs > LEDGER_LOCK_STALE_MS
+}
+
+/**
+ * Take the maintenance lock for one root. Returns a handle, or null: null means
+ * another process holds the lock, or something unexpected happened, and either way
+ * the caller must not run maintenance.
+ */
+async function acquireMaintenanceLock(root) {
+  if (typeof root !== 'string' || root === '') return null
+  const dir = ledgerMaintenanceLockDir(root)
+  const ownerFile = join(dir, LEDGER_LOCK_OWNER_FILE)
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      await mkdir(dir, { mode: 0o700 })
+      // No reader could ever date a lock without an owner document, so a failed
+      // write releases the directory again instead of leaving it behind.
+      const owner = { pid: process.pid, startedAt: Date.now(), host: hostname() }
+      try {
+        await writeFile(ownerFile, JSON.stringify(owner), { encoding: 'utf8', mode: 0o600 })
+      } catch (error) {
+        await rmdir(dir).catch(() => {})
+        return null
+      }
+      return { dir, ownerFile, owner }
+    } catch (error) {
+      if (error === null || typeof error !== 'object' || error.code !== 'EEXIST') return null
+      if (attempt > 0 || !(await ledgerMaintenanceLockIsStale(dir, ownerFile))) return null
+      // Reclaim one lock left behind by a killed holder: its owner document and its
+      // now empty directory, never anything else.
+      await unlink(ownerFile).catch(() => {})
+      if (!(await rmdir(dir).then(() => true, () => false))) return null
+    }
+  }
+  return null
+}
+
+async function releaseMaintenanceLock(handle) {
+  if (handle === null || handle === undefined) return
+  const { dir, ownerFile, owner } = handle
+  try {
+    // A lock another process reclaimed belongs to that process now, and removing
+    // its owner document would let a third one in while it works.
+    const current = JSON.parse(await readFile(ownerFile, 'utf8'))
+    if (current === null || typeof current !== 'object' || current.pid !== owner.pid || current.startedAt !== owner.startedAt) return
+  } catch (error) {
+    // A missing owner document leaves nothing of this handle to remove.
+    return
+  }
+  await unlink(ownerFile).catch(() => {})
+  await rmdir(dir).catch(() => {})
+}
+
+/**
+ * Run fn while this process holds the maintenance lock of one root, and hand it the
+ * lock handle so the step can pass it on instead of taking a second one. Returns
+ * { acquired: true, value } when fn ran, or { acquired: false } when another process
+ * owns the lock (or the root has none to take), in which case fn was never called:
+ * a maintenance step that cannot prove it is alone must not delete or rewrite
+ * anything. The migration and the archive command both go through here, so every
+ * path that removes ledger files shares one lock and one release.
+ */
+async function withLedgerMaintenanceLock(root, fn) {
+  const lock = await acquireMaintenanceLock(root)
+  if (lock === null) return { acquired: false }
+  try {
+    return { acquired: true, value: await fn(lock) }
+  } finally {
+    await releaseMaintenanceLock(lock)
+  }
+}
+
+// legacyFallbackRows carries the rows of a legacy whole-unit document that the
+// trees have not received yet, so read-only maintenance can still answer for them.
+// archive is the cold half of the ledger (lib/archive.js): its session ids join
+// listKeys() and its rows answer a read the trees cannot, never the other way round.
+function createLedgerUnitStore(legacyUnit, shardUnits, root = '', legacyFallbackRows = undefined, archive = null) {
   const shards = uniqueUnits(shardUnits)
   const allUnits = uniqueUnits([legacyUnit, ...shards])
-  return {
-
+  // Mutable on purpose: a live archive run removes the tree documents it just
+  // filed, so the reader built at start stops answering for exactly those records.
+  // attachArchive() swaps in the reader of the month files that run wrote.
+  let archiveReader = archive
+  // Every session key the trees hold, without parsing a single record: the
+  // per-record layout is a directory of documents, so the filenames are the index
+  // and a record is read later, on demand, with readRecord().
+  async function listTreeKeys() {
+    const keys = []
+    const known = new Set()
+    for (const unit of shards) {
+      let dir = ''
+      try {
+        dir = unit.tableDir('sessions')
+      } catch (err) {
+        continue
+      }
+      const entries = await readdir(dir, { withFileTypes: true }).catch(() => [])
+      for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.json') || entry.name.startsWith('__')) continue
+        const key = entry.name.slice(0, -'.json'.length)
+        if (key === LEDGER_META_KEY || known.has(key)) continue
+        known.add(key)
+        keys.push(key)
+      }
+    }
+    return keys
+  }
+  // One document, parsed the way the storage unit parses it when it loads. A tree
+  // that does not answer for a record yet is the archive's business.
+  async function readTreeRecord(key) {
+    const unit = shardUnits[ledgerShardIndex(key)]
+    if (unit === undefined) return undefined
+    let path = ''
+    try {
+      path = join(unit.tableDir('sessions'), key + '.json')
+    } catch (err) {
+      return undefined
+    }
+    try {
+      const doc = JSON.parse(await readFile(path, 'utf8'))
+      if (doc !== null && typeof doc === 'object' && doc.version === 0 && doc.record !== undefined) return doc.record
+    } catch (err) {
+      // A missing or unreadable document is the archive's and the legacy
+      // fallback's business.
+    }
+    return undefined
+  }
+  /**
+   * Remove one tree document, which is what archiving does once a record's month
+   * file, key index and the manifest are all on disk. Best effort by contract: a
+   * document left behind is a duplicate the read path already prefers, never a
+   * lost record.
+   *
+   * expected is the compact row that was archived. Runtime writes do not hold the
+   * maintenance lock, so between planning a key and deleting it the session may
+   * have published a newer revision; the document is then re-read and left alone
+   * unless it still holds exactly that row, because deleting it would throw away
+   * a revision nothing else has a copy of yet.
+   */
+  async function deleteTreeRecord(key, expected) {
+    const unit = shardUnits[ledgerShardIndex(key)]
+    if (unit === undefined) return false
+    let path = ''
+    try {
+      path = join(unit.tableDir('sessions'), key + '.json')
+    } catch (err) {
+      return false
+    }
+    if (expected !== undefined) {
+      if (expected === null || typeof expected !== 'object') return false
+      const text = await readFile(path, 'utf8').catch(() => null)
+      if (text === null) return false
+      let doc = null
+      try { doc = JSON.parse(text) } catch (err) { return false }
+      if (doc === null || typeof doc !== 'object' || doc.record === null || typeof doc.record !== 'object') return false
+      // updatedAt is the revision stamp; the serialized row is the belt and braces
+      // that keeps a same-stamp rewrite in the tree too.
+      if (doc.record.updatedAt !== expected.updatedAt) return false
+      if (JSON.stringify(doc.record) !== JSON.stringify(expected)) return false
+    }
+    return unlink(path).then(() => true, () => false)
+  }
+  const store = {
     async loadAll() {
       const snapshots = await Promise.all(shards.map((unit) => unit.loadAll()))
       const rows = Object.create(null)
@@ -122,39 +309,58 @@ function createLedgerUnitStore(legacyUnit, shardUnits, root = '') {
      * index and a record is read later, on demand, with readRecord().
      */
     async listKeys() {
-      const keys = []
-      for (const unit of shards) {
-        let dir = ''
-        try {
-          dir = unit.tableDir('sessions')
-        } catch (err) {
-          continue
-        }
-        const entries = await readdir(dir, { withFileTypes: true }).catch(() => [])
-        for (const entry of entries) {
-          if (!entry.isFile() || !entry.name.endsWith('.json') || entry.name.startsWith('__')) continue
-          keys.push(entry.name.slice(0, -'.json'.length))
-        }
+      const keys = await listTreeKeys()
+      const known = new Set(keys)
+      const remember = (key) => {
+        if (key === LEDGER_META_KEY || known.has(key)) return
+        known.add(key)
+        keys.push(key)
       }
+      // A legacy row that a concurrent migration has not copied into the trees
+      // yet is still a record of this ledger.
+      if (legacyFallbackRows !== undefined) for (const key of Object.keys(legacyFallbackRows)) remember(key)
+      // Cold records are records of this ledger too, and their ids are what lets
+      // recordFor() know that reading one is worth a month decompression.
+      if (archiveReader !== null) for (const key of archiveReader.keys()) remember(key)
       return keys
     },
-    /** One document, parsed the way the storage unit parses it when it loads. */
+    /**
+     * One document, parsed the way the storage unit parses it when it loads. A tree
+     * that does not answer for a record yet falls back to the cold archive and then
+     * to the legacy rows that read-only maintenance keeps in memory.
+     */
     async readRecord(key) {
-      const unit = shardUnits[ledgerShardIndex(key)]
-      if (unit === undefined) return undefined
-      let path = ''
-      try {
-        path = join(unit.tableDir('sessions'), key + '.json')
-      } catch (err) {
-        return undefined
-      }
-      try {
-        const doc = JSON.parse(await readFile(path, 'utf8'))
-        if (doc === null || typeof doc !== 'object' || doc.version !== 0 || doc.record === undefined) return undefined
-        return doc.record
-      } catch (err) {
-        return undefined
+      // The tree is the newer copy whenever it holds one, so a record that is both
+      // archived and still in its tree is read once, from the tree: a failed
+      // archive run leaves duplicates that must not be counted twice.
+      const tree = await readTreeRecord(key)
+      if (tree !== undefined) return tree
+      if (archiveReader !== null) {
+        const archived = await archiveReader.readRecord(key).catch(() => undefined)
+        if (archived !== undefined) return archived
       }
+      if (legacyFallbackRows === undefined || !Object.hasOwn(legacyFallbackRows, key)) return undefined
+      return legacyFallbackRows[key]
+    },
+    /** See deleteTreeRecord(): archiving is the only caller that removes documents. */
+    deleteRecord: deleteTreeRecord,
+    /**
+     * Swap the cold reader, or drop it with null. A run that just deleted tree
+     * documents must re-attach the reader of the month files it wrote, or every read
+     * of a record it filed would answer 'missing' until the next DSH start.
+     */
+    attachArchive(reader) {
+      archiveReader = reader === undefined ? null : reader
+      return store
+    },
+    /**
+     * The trees alone: no archive ids, no legacy rows. archiveRecords() must get this
+     * view rather than the store, because the store answers from the month files it
+     * is about to merge into - it would plan every already-archived record again and
+     * count it a second time.
+     */
+    treeStore() {
+      return { listKeys: listTreeKeys, readRecord: readTreeRecord, deleteRecord: deleteTreeRecord }
     },
     async hasMigrationMarker() {
       if (shardUnits[0] === undefined) return false
@@ -172,6 +378,19 @@ function createLedgerUnitStore(legacyUnit, shardUnits, root = '') {
     },
     shardCount: LEDGER_SHARD_COUNT,
   }
+  return store
+}
+
+// The archive is optional and never fatal: a root that cannot provide a readable
+// archive simply opens as a tree-only ledger (lib/archive.js already treats a
+// damaged month as missing), and the error is reported once at start.
+async function openLedgerArchive(root) {
+  try {
+    return await createArchiveReader(root)
+  } catch (error) {
+    console.warn('[all-usage] usage ledger archive is unavailable:', error && error.message)
+    return null
+  }
 }
 
 async function openLedgerUnitStore(backend) {
@@ -186,7 +405,11 @@ async function openLedgerUnitStore(backend) {
       shardUnits.push(await backend.kv.open({ name: ledgerShardName(index), version: 0, tables: ['sessions'], hasGlobal: false, layout: 'per-record' }))
     }
     const root = typeof backend.root === 'string' ? backend.root : ''
-    const shardStore = createLedgerUnitStore(undefined, shardUnits, root)
+    // Cold records live in <root>/archive. The reader is built only when that
+    // directory holds a month file, so a ledger that never archives pays one failed
+    // directory listing per start and reads nothing else.
+    const archive = root === '' ? null : await openLedgerArchive(root)
+    const shardStore = createLedgerUnitStore(undefined, shardUnits, root, undefined, archive)
     // A per-record unit exposes tableDir(), so its documents can be listed and read
     // one at a time. Older or fake units cannot, and there the whole table is read
     // once (and stays resident) exactly as it always was.
@@ -200,23 +423,52 @@ async function openLedgerUnitStore(backend) {
       return { store: shardStore, rows: shardRows, retired, streaming }
     }
 
-    // Read the legacy monolith only during the one-time migration. Once shard 00
-    // carries the marker, startup never parses the old multi-megabyte file again.
-    legacyUnit = await backend.kv.open({ name: LEDGER_UNIT_NAME, version: 0, tables: ['sessions'], hasGlobal: false })
-    const store = createLedgerUnitStore(legacyUnit, shardUnits)
-    const rows = Object.assign(Object.create(null), shardRows)
-    const legacyRows = sessionRows(await legacyUnit.loadAll())
-    for (const [key, value] of Object.entries(legacyRows)) {
-      if (key === LEDGER_META_KEY || Object.hasOwn(rows, key)) continue
-      await store.putRecord('sessions', key, value)
-      rows[key] = value
-    }
-    await store.putRecord('sessions', LEDGER_META_KEY, { version: 1, migratedAt: Date.now() })
-    // Its records now live in the per-record trees (written above), so the
-    // legacy document is retired. A failure here leaves the file in place and
-    // simply tries again on the next start.
-    const retired = await retireLegacyLedgerFiles(backend, shardUnits).catch((error) => { console.error('[all-usage] usage ledger legacy retirement failed:', error && error.message); return [] })
-    return { store, rows, retired, streaming: false }
+    // The first migration writes the marker and then retires the legacy files, so
+    // the whole section is one critical section under the maintenance lock: a
+    // second process must never delete a file this one is still reading. An empty
+    // root has nothing to retire, so it keeps the unlocked behaviour.
+    const readLegacyRows = async () => {
+      // Read the legacy monolith only during the one-time migration. Once shard 00
+      // carries the marker, startup never parses the old multi-megabyte file again.
+      legacyUnit = await backend.kv.open({ name: LEDGER_UNIT_NAME, version: 0, tables: ['sessions'], hasGlobal: false })
+      return sessionRows(await legacyUnit.loadAll())
+    }
+    const mergedRows = (legacyRows) => {
+      const rows = Object.assign(Object.create(null), shardRows)
+      for (const [key, value] of Object.entries(legacyRows)) {
+        if (key === LEDGER_META_KEY || Object.hasOwn(rows, key)) continue
+        rows[key] = value
+      }
+      return rows
+    }
+    const migrate = async (lock) => {
+      const legacyRows = await readLegacyRows()
+      const rows = mergedRows(legacyRows)
+      const store = createLedgerUnitStore(legacyUnit, shardUnits, '', undefined, archive)
+      // A row the tree already holds is the newer one (a previous migration may have
+      // been interrupted after copying it), so only the missing rows are copied. A
+      // streaming backend keeps its trees on disk, so there it copies every row
+      // exactly as before.
+      for (const [key, value] of Object.entries(legacyRows)) {
+        if (key === LEDGER_META_KEY || Object.hasOwn(shardRows, key)) continue
+        await store.putRecord('sessions', key, value)
+      }
+      await store.putRecord('sessions', LEDGER_META_KEY, { version: 1, migratedAt: Date.now() })
+      // Those rows now live in the per-record trees (written above), so the legacy
+      // document is retired. A failure here leaves the file in place and simply
+      // tries again on the next start.
+      const retired = await retireLegacyLedgerFiles(backend, shardUnits, lock).catch((error) => { console.error('[all-usage] usage ledger legacy retirement failed:', error && error.message); return [] })
+      return { store, rows, retired, streaming: false }
+    }
+    if (root === '') return await migrate(undefined)
+    const outcome = await withLedgerMaintenanceLock(root, migrate)
+    if (outcome.acquired) return outcome.value
+    // Another process owns the maintenance section: merge what it has not copied
+    // into the trees yet (the trees win) and write nothing at all. The legacy
+    // document stays where it is, and its rows stay readable through the store
+    // until a start that holds the lock finishes the migration.
+    const legacyRows = await readLegacyRows()
+    return { store: createLedgerUnitStore(legacyUnit, shardUnits, root, legacyRows, archive), rows: mergedRows(legacyRows), retired: [], streaming }
   } catch (error) {
     await Promise.all(uniqueUnits([legacyUnit, ...shardUnits]).map((unit) => unit.close().catch(() => {})))
     throw error
@@ -227,14 +479,29 @@ async function openLedgerUnitStore(backend) {
 // is dead weight: every record lives in the tree now, while the old document
 // keeps a full copy (155.9 MB across the 32 shards plus a 22.4 MB monolith on
 // this machine). DSH's storage layer never removes it, so the ledger retires it
-// itself — only after the tree is non-empty, only for files it owns, and never
-// more than once per unit (a marker keeps a failed run from looping).
-async function retireLegacyLedgerFiles(backend, shardUnits) {
+// itself — only after the tree is non-empty, only for files it owns, never more
+// than once per unit (a marker keeps a failed run from looping), and never
+// without the maintenance lock: deleting a whole-unit file another process is
+// still loading would lose the rows it has not copied yet.
+async function retireLegacyLedgerFiles(backend, shardUnits, heldLock = undefined) {
   if (process.env.DSH_ALL_USAGE_KEEP_LEGACY === '1') return []
   const root = typeof backend.root === 'string' ? backend.root : ''
   if (root === '') return []
   const marker = join(root, LEDGER_UNIT_NAME + '.retired')
   if (await stat(marker).then(() => true, () => false)) return []
+  // The migration already holds the lock and hands its handle over, so one
+  // critical section covers the copy and the retirement.
+  const lock = heldLock === undefined ? await acquireMaintenanceLock(root) : heldLock
+  if (lock === null) return []
+  try {
+    return await collectLegacyRetirement(root, shardUnits, marker)
+  } finally {
+    if (heldLock === undefined) await releaseMaintenanceLock(lock)
+  }
+}
+
+// The retirement proper, only ever entered while holding the maintenance lock.
+async function collectLegacyRetirement(root, shardUnits, marker) {
   const retired = []
   const candidates = []
   for (let index = 0; index < LEDGER_SHARD_COUNT; index += 1) {
@@ -664,6 +931,46 @@ function buildLedgerRecord(session, workspaceId, source = 'scan', revision, prev
       if (!state.ledgerPending.has(sid)) resolveLedgerWaiters(sid)
     }
   }
+  /**
+   * Cold-archive the ledger from the running host: fold every record older than
+   * days days into <root>/archive/<YYYY-MM>.jsonl.gz, and only then remove the tree
+   * documents that are durable there. The panel asks for the plan first (dryRun)
+   * and only a second, explicit request writes. Either way the run is one
+   * maintenance step behind the same lock the CLI and the migration take, so two
+   * processes never archive the same root at once.
+   *
+   * Returns { ok: true, months, archived, bytes, compressed, dryRun, errors }, or
+   * { ok: false, message } with message no-root | ledger-unavailable | busy |
+   * archive-failed.
+   */
+  async function archiveLedger({ days = 90, dryRun = true } = {}) {
+    try {
+      const backend = storage === undefined || storage === null || storage.backend === undefined || storage.backend === null ? undefined : storage.backend.get('json')
+      const root = backend !== undefined && backend !== null && typeof backend.root === 'string' ? backend.root : ''
+      if (root === '') return { ok: false, message: 'no-root' }
+      // A record still queued for its tree would be planned from the revision before
+      // the last write; the plan reads the documents the delete will remove.
+      await drainLedgerWrites()
+      const unit = state.ledgerUnit
+      if (unit === null || unit === undefined || typeof unit.treeStore !== 'function') return { ok: false, message: 'ledger-unavailable' }
+      const cutoffMs = Date.now() - days * 86400000
+      // treeStore(), never the unit itself: the unit answers from the archive, so a
+      // second run would plan the records the first one filed all over again.
+      const outcome = await withLedgerMaintenanceLock(root, () => archiveRecords({ root, store: unit.treeStore(), cutoffMs, dryRun: dryRun === true }))
+      if (!outcome.acquired) return { ok: false, message: 'busy' }
+      if (dryRun !== true) {
+        // The month files are on disk and their tree documents are gone: the reader
+        // this process opened at start knows neither. attachArchive() answers for
+        // those records now instead of after the next DSH start.
+        const reader = await openLedgerArchive(root)
+        unit.attachArchive(reader)
+        if (reader === null) console.warn('[all-usage] usage ledger archive holds no readable month; the records it removed read back after the next start')
+      }
+      return { ok: true, ...outcome.value }
+    } catch (error) {
+      return { ok: false, message: 'archive-failed', error: String(error && error.message ? error.message : error) }
+    }
+  }
   function recordCacheLimit() {
     const megabytes = Number(process.env.DSH_ALL_USAGE_RECORD_CACHE_MB)
     return Number.isFinite(megabytes) && megabytes >= 0 ? megabytes * 1024 * 1024 : 16 * 1024 * 1024
@@ -982,6 +1289,7 @@ function buildLedgerRecord(session, workspaceId, source = 'scan', revision, prev
     storeLedgerRecord,
     persistLedgerRecord,
     drainLedgerWrites,
+    archiveLedger,
     // Exposed for the round-trip test: the on-disk shape is private otherwise.
     serializeLedgerRecordForTest: serializeLedgerRecord,
     expandLedgerRecordForTest: expandLedgerRecord,
@@ -997,4 +1305,4 @@ function buildLedgerRecord(session, workspaceId, source = 'scan', revision, prev
   }
 }
 
-export { LEDGER_VERSION, PREVIOUS_LEDGER_VERSION, LEGACY_LEDGER_VERSION, LEDGER_SHARD_COUNT, RETIRED_WORKSPACE_ID, ledgerShardIndex, retargetLedgerRecord, serializeLedgerRecord }
+export { LEDGER_VERSION, PREVIOUS_LEDGER_VERSION, LEGACY_LEDGER_VERSION, LEDGER_SHARD_COUNT, RETIRED_WORKSPACE_ID, ledgerShardIndex, retargetLedgerRecord, serializeLedgerRecord, withLedgerMaintenanceLock }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-all-usage",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "DeepSeek Harness usage dashboard with model, provider, workspace, cache, balance, and CSV insights",
   "repository": {
     "type": "git",
@@ -17,6 +17,7 @@
     "fixture:check": "node scripts/replay-fixture.mjs fixtures/usage-events.json",
     "test:runtime": "node --test test/dsh-runtime.test.js",
     "check:pack": "node scripts/check-package.mjs",
+    "ledger:archive": "node scripts/archive-ledger.mjs",
     "prepack": "npm run build:client"
   },
   "main": "lib/index.js",
@@ -50,6 +51,7 @@
     "lib/index.js",
     "lib/plugin.js",
     "lib/aggregation.js",
+    "lib/archive.js",
     "lib/records-cache.js",
     "lib/ledger.js",
     "lib/session-sync.js",
@@ -64,10 +66,17 @@
     "CHANGELOG.md",
     "README.md",
     "README.en.md",
+    "README.ja.md",
+    "README.es.md",
+    "README.fr.md",
+    "README.de.md",
+    "README.ru.md",
+    "README.pt.md",
     "cordis.patch.yml",
     "screenshots.json",
     "fixtures/usage-events.json",
     "scripts/replay-fixture.mjs",
+    "scripts/archive-ledger.mjs",
     "assets"
   ],
   "keywords": [

package/screenshots.json

@@ -1,12 +1,10 @@
 [
+  "assets/cover-zh.png",
   "assets/screenshots/zh/01-overview.png",
-  "assets/screenshots/zh/02-heatmap.png",
-  "assets/screenshots/zh/03-model-usage.png",
-  "assets/screenshots/zh/04-request-logs.png",
-  "assets/screenshots/zh/05-cost-settings.png",
-  "assets/screenshots/en/01-overview.png",
-  "assets/screenshots/en/02-heatmap.png",
-  "assets/screenshots/en/03-model-usage.png",
-  "assets/screenshots/en/04-request-logs.png",
-  "assets/screenshots/en/05-cost-settings.png"
+  "assets/screenshots/zh/02-trend.png",
+  "assets/screenshots/zh/03-heatmap.png",
+  "assets/screenshots/zh/04-model-stats.png",
+  "assets/screenshots/zh/05-request-logs.png",
+  "assets/screenshots/zh/06-cost-settings.png",
+  "assets/screenshots/zh/07-maintenance.png"
 ]