@summerscar/dsh-mnemon-sync 0.1.1 → 0.1.3

package/README.md

@@ -1,86 +1,43 @@
 # dsh-mnemon-sync
 
-为 [dsh-mnemon](https://github.com/omdsh-dev/dsh-mnemon) 提供备份与恢复：把 Mnemon 的记忆组件打包上传到 S3 兼容存储或 WebDAV，需要时再挑一个包恢复回来。
+为 [dsh-mnemon](https://github.com/omdsh-dev/dsh-mnemon) 提供备份与恢复：把记忆组件打包上传到 S3 兼容存储或 WebDAV，需要时挑一个包恢复回来。安装后在记忆系统里多一个「同步备份」标签页。
 
-在记忆系统里以「同步备份」标签页出现，和「概览」「检索」「内容」并排。
-
-## 能备份什么
-
-按 dsh-mnemon 自己的组件划分，任意组合，多选：
-
-| 组件 | 内容 | 说明 |
-|---|---|---|
-| 记忆空间 | `<MNEMON_DATA_DIR>/data/` | 每个空间的 `mnemon.db` 与空间清单，数据库经 SQLite 在线备份 |
-| 项目档案 | `<MNEMON_DATA_DIR>/documents/` | `index.json` 与全部 Markdown 文档 |
-| 运行时记忆 | `<MNEMON_DATA_DIR>/runtime/` | `memories.json` 与两份投影文件 |
-
-`MNEMON_DATA_DIR` 未设置时取 `~/.mnemon`。
-
-## 为什么不用 litestream
-
-litestream 是很好的工具，但和「目录级、多空间、可配置目标」这个需求是正交的：
+## 安装
 
-- 一个 litestream 实例只盯一个数据库文件，v0.5 起每个数据库只允许一个副本。要备份整个 data 目录就得为每个记忆空间养一个常驻进程，空间增删还得动态改配置。
-- 它接管 WAL checkpoint 并长期持有读锁。实测会让 `mnemon.db-wal` 停在非零字节，而 dsh-mnemon 自己的备份导出有这条检查：
+```sh
+dsh plugin --profile web add @summerscar/dsh-mnemon-sync
+```
 
-  ```js
-  if (existsSync(wal) && statSync(wal).size > 0)
-    throw new Error(`Memory Space ${id} is busy (mnemon.db-wal is not checkpointed)`)
-  ```
+装完重启 DSH 生效。没有 `dsh-mnemon` 时插件仍可运行，只是不显示标签页。
 
-  也就是说上了 litestream，dsh-mnemon 自带的备份会直接报错。
+## 能备份什么
 
-这里改用 `node:sqlite` 的 `backup()`：它走 SQLite 自己的在线备份 API，写入方持有 WAL 也不会把副本撕开，并发写只会让备份重跑当前批次，不产生常驻进程。
+三个组件任意组合，默认全选：
 
-## 一致性
+| 组件 | 内容 |
+|---|---|
+| 记忆空间 | `<MNEMON_DATA_DIR>/data/`，每个空间的 `mnemon.db` 与空间清单 |
+| 项目档案 | `<MNEMON_DATA_DIR>/documents/`，`index.json` 与全部 Markdown |
+| 运行时记忆 | `<MNEMON_DATA_DIR>/runtime/`，`memories.json` 与两份投影 |
 
-- **数据库**：`backup()` 生成事务一致的副本，产物是已 checkpoint 的单文件，不含 `-wal` / `-shm`。
-- **非数据库文件**：JSON 与 Markdown 由存储层原子写入，逐字节复制。
-- **校验**：每个文件在打包前记录 SHA-256，manifest 与内容一起入包；上传前先自校验，恢复前再校验一次。
-- **恢复顺序**：先下载 → 校验全部校验和 → 报告缺失组件 → 只写回确认的组件。不带 `apply` 时是纯预览，不碰磁盘。
-- **覆盖数据库前**会先删除同名的 `-wal` / `-shm`：残留的 WAL 会让 SQLite 重放恢复文件里并不存在的事务。
+`MNEMON_DATA_DIR` 未设置时取 `~/.mnemon`。
 
-## 目标
+## 备份目标
 
-- **S3 兼容**：AWS Signature V4 手写实现，已用 AWS 官方文档的测试向量逐字节校验。适用于 Cloudflare R2、MinIO、Backblaze B2、阿里云 OSS 等。
-- **WebDAV**：`PUT` 上传、`PROPFIND depth:1` 列目录、`DELETE` 清理，Basic 认证。
+- **S3 兼容** — 手写 AWS Signature V4，适用于 Cloudflare R2、MinIO、Backblaze B2 等
+- **WebDAV** — Basic 认证，自动创建远端目录
 
-凭据保存在 `<MNEMON_DATA_DIR>/state/mnemon-sync.json`，权限 `0600`，不进 DSH 配置，也不会被备份包带走（`state/` 不属于任何备份组件）。页面回显密钥时只给掩码，回传掩码表示"不修改"。
+凭据存在 `<MNEMON_DATA_DIR>/state/mnemon-sync.json`，权限 `0600`，不写入 DSH 配置，也不进备份包。页面只回显掩码，回传掩码表示不修改。
 
 ## 自动备份
 
-间隔与 dsh-mnemon 自己的 Git 备份保持一致，两项功能读起来一样：
-
 关闭 · 每小时 · 每 3 / 6 / 12 小时 · 每天 · 每 3 天 · 每 7 天
 
-调度是一个 Host 内唯一的 `setTimeout` 自循环，从 `finally` 里重新排期。每次触发前重新读配置，改间隔不用重启；运行中再次触发会被丢弃而不是排队；失败只记录不抛出。
+## 恢复
 
-## 安装
+从备份列表查看明细，选择要恢复的组件后执行；缺少的组件会明确提示。恢复默认只做预览，确认后才写盘。
 
-```sh
-git clone https://github.com/summerscar/dsh-mnemon-sync.git
-```
-
-在 DSH 里用插件管理器安装这个目录，或直接加入 profile 的依赖：
-
-```sh
-dsh plugin --profile web add /path/to/dsh-mnemon-sync
-```
-
-需要在 profile 里启用，并确保 `mnemon.sync` 这一层出现在 `memoryTopology.layers` 中。插件会注册一个最小 Source 来承载自己的页面 —— dsh-mnemon 只会为真实存在的 Source 渲染标签页，且标签高亮按 `sourceTypeId` 分组，借用别人的类型会导致两个标签同时点亮。
-
-## 目录结构
-
-```
-index.js      Host 入口：HTTP 接口、调度装配、Source 注册
-source.js     承载页面身份的最小 Source（不存记忆）
-snapshot.js   组件识别、数据库在线备份、manifest 与校验
-scheduler.js  定时器与运行历史
-store.js      设置存取（0600）与规范化
-targets.js    S3 SigV4 / WebDAV 的上传、下载、列目录、删除
-zip.js        零依赖 ZIP 读写（node:zlib）
-client.js     浏览器端页面与标签注册
-```
+数据库用 `node:sqlite` 的 `backup()` 在线备份，副本一致；写回前会删掉同名 `-wal` / `-shm`，避免 SQLite 重放不存在的事务。每个文件都有 SHA-256 校验。
 
 ## 许可
 

package/client.js

@@ -40,8 +40,8 @@ window.__ModuleLoader__.load({
 
     const zh = {
       tabLabel: '同步备份',
-      title: '记忆空间同步备份',
-      subtitle: '把 Mnemon 的记忆组件打包上传到 S3 或 WebDAV',
+      title: '同步备份',
+      subtitle: '把选定的记忆组件打包备份到 S3 兼容存储或 WebDAV，并可随时查看备份列表与恢复。',
       config: '备份配置',
       configNote: '以下三项一起保存。',
       scope: '备份范围',
@@ -144,8 +144,8 @@ window.__ModuleLoader__.load({
 
     const en = {
       tabLabel: 'Sync backup',
-      title: 'Memory space sync backup',
-      subtitle: 'Pack Mnemon\u2019s memory components to S3 or WebDAV',
+      title: 'Sync backup',
+      subtitle: 'Back up selected memory components to S3-compatible storage or WebDAV, with an archive list and restore.',
       config: 'Backup settings',
       configNote: 'All three sections below save together.',
       scope: 'Backup scope',

package/cordis.patch.yml

@@ -1,3 +1,11 @@
+# Host entry: HTTP API, scheduler and backup engine. Needs only webServer.
 - insert:
     - id: mnemon-sync
       name: '@summerscar/dsh-mnemon-sync'
+    # Memory Source entry, mounted exactly like the shipped dsh-mnemon-source-*
+    # packages: only id + name here, and the module itself exports
+    # `inject = ['mnemonMemory']` so the Loader waits for that service.
+    # Kept as a separate Entry so a profile without dsh-mnemon still gets a
+    # working backup engine (just no tab).
+    - id: mnemon-sync-source
+      name: '@summerscar/dsh-mnemon-sync/source'

package/index.js

@@ -14,14 +14,13 @@
  * resident process, which is both simpler and compatible with the store.
  *
  * The browser half only ever sees JSON: credentials are masked on the way out
- * and are never echoed back by a read.
+ * and are never echoed back by a read. The memory Source that owns the page is
+ * a separate Cordis entry (./source.js), mounted by the bundle patch.
  */
 
 import { createHash } from 'node:crypto'
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
-import { createRequire } from 'node:module'
 import { dirname, join, resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
 
 import { SyncHistory, SyncScheduler } from './scheduler.js'
 import {
@@ -165,7 +164,6 @@ export function apply(ctx, config = {}) {
   // — not UI contributions. Standing up this minimal Source is what lets the
   // page use its own type instead of borrowing `memory-spaces`, which is the
   // only way its tab can highlight independently.
-  ctx.effect(() => registerSyncSource(ctx, dataRoot), 'mnemon-sync: memory source')
 
   ctx.effect(() => ctx.webServer.register({
     kind: 'prefix',
@@ -582,104 +580,6 @@ function restoreMaskedSecrets(incoming, previous) {
   return incoming
 }
 
-/**
- * Resolve the dsh-mnemon extension SDK.
- *
- * A bare `import('dsh-mnemon/extension-sdk')` is not enough here. Installed
- * from npm the package sits at `<profile>/node_modules/@summerscar/...`, so
- * Node's own ancestor walk would find dsh-mnemon beside it — but a *linked*
- * checkout lives outside the profile with no `node_modules` of its own, and
- * then the walk finds nothing.
- *
- * Both install shapes are therefore covered, cheapest first:
- *   1. From this module's own location, which is right for an npm install.
- *   2. From `DSH_PROFILE_DIR`, which is right for a linked checkout and is set
- *      in every shell and Host process a profile launches.
- *   3. From `DSH_HOME/profiles/web`, for a Host booted without that variable.
- *
- * Returns `undefined` when dsh-mnemon is not installed at all, which is a
- * supported configuration: the backup keeps working without its page.
- */
-async function loadExtensionSdk() {
-  // 1. Ask Node, anchored at this file. Resolves for an npm install.
-  try {
-    const resolver = createRequire(import.meta.url)
-    const resolved = resolver.resolve('dsh-mnemon/lib/extension-sdk.js')
-    return await import(pathToFileURL(resolved).href)
-  } catch {
-    // Not resolvable from here: fall through to the profile-anchored paths.
-  }
-
-  const candidates = []
-  const profileDir = process.env.DSH_PROFILE_DIR?.trim()
-  if (profileDir !== undefined && profileDir !== '') {
-    candidates.push(join(profileDir, 'node_modules', 'dsh-mnemon', 'lib', 'extension-sdk.js'))
-  }
-  // The Host that loads this plugin lives in the installation's own tree.
-  candidates.push(join(process.env.DSH_HOME ?? '', 'profiles', 'web', 'node_modules', 'dsh-mnemon', 'lib', 'extension-sdk.js'))
-  for (const candidate of candidates) {
-    if (candidate === '' || !existsSync(candidate)) continue
-    return import(pathToFileURL(candidate).href)
-  }
-  return undefined
-}
-
-/**
- * Install the sync Source into dsh-mnemon's composable-memory service.
- *
- * Returns a disposer, and does nothing at all when the Host runs without that
- * service (a profile with dsh-mnemon absent).
- */
-function registerSyncSource(ctx, dataRoot) {
-  if (typeof ctx.get !== 'function') return () => {}
-  const service = ctx.get('mnemonMemory')
-  if (service === undefined || service === null || typeof service.installContributions !== 'function') {
-    return () => {}
-  }
-  let disposed = false
-  let uninstall
-  void (async () => {
-    try {
-      const sdk = await loadExtensionSdk()
-      if (sdk === undefined || typeof sdk.defineMemorySource !== 'function') {
-        console.warn('mnemon-sync: dsh-mnemon extension SDK not found; the sync tab stays hidden')
-        return
-      }
-      const { createSyncSource, syncSourceManifest } = await import('./source.js')
-      if (disposed) return
-      // The manifest goes through the SDK validator so a contract drift in
-      // dsh-mnemon fails loudly here instead of at composition time.
-      const definition = sdk.defineMemorySource(createSyncSource({ ...syncSourceManifest }))
-      uninstall = service.installContributions({
-        plugin: {
-          apiVersion: 'dsh-mnemon/plugin/v1',
-          packageName: '@summerscar/dsh-mnemon-sync',
-          label: { en: 'Sync backup', 'zh-CN': '同步备份' },
-          description: {
-            en: 'Archive memory spaces to S3 or WebDAV.',
-            'zh-CN': '把记忆空间备份到 S3 或 WebDAV。',
-          },
-          roles: ['source'],
-          provides: [{ id: 'source' }],
-        },
-        sources: [definition],
-      }, { instanceId: 'mnemon-sync' })
-      if (disposed) {
-        uninstall?.()
-        uninstall = undefined
-      }
-    } catch (error) {
-      // A Host that cannot accept the Source must not take the backup down.
-      console.warn('mnemon-sync: could not register the sync source', error)
-    }
-  })()
-  return () => {
-    disposed = true
-    uninstall?.()
-    uninstall = undefined
-  }
-}
-
 /** Read a staging tree into the flat `{ path, bytes }` entries the ZIP writer takes. */
 function collect(root, prefix = '') {
   const entries = []

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "title": "Memory space sync backup",
-    "description": "Archive the whole Mnemon data directory — every memory space database — to S3-compatible storage or WebDAV, with minute/hour/day/clock scheduling and retention."
+    "title": "Sync backup",
+    "description": "Back up and restore dsh-mnemon memory components (memory spaces, project documents, runtime memory — pick any subset) to S3-compatible storage or WebDAV, with scheduled backups, an archive list and selective restore."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "title": "记忆空间同步备份",
-    "description": "把整个 Mnemon data 目录（含全部记忆空间数据库）打包备份到 S3 兼容存储或 WebDAV，支持按分钟/小时/天/固定时刻调度与保留份数。"
+    "title": "同步备份",
+    "description": "备份与恢复 dsh-mnemon 的记忆组件（记忆空间、项目档案、运行时记忆，可任选）到 S3 兼容存储或 WebDAV，支持定时备份、备份列表与选择性恢复。"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@summerscar/dsh-mnemon-sync",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Back up and restore dsh-mnemon memory components (memory spaces, project documents, runtime memory) to S3-compatible storage or WebDAV.",
   "type": "module",
   "main": "index.js",
@@ -8,7 +8,8 @@
     ".": "./index.js",
     "./client": "./client.js",
     "./locale/*.json": "./locale/*.json",
-    "./icon": "./icon.svg"
+    "./icon": "./icon.svg",
+    "./source": "./source.js"
   },
   "files": [
     "index.js",

package/source.js

@@ -1,34 +1,98 @@
 /**
  * Mnemon Sync — the Source that owns this page.
  *
+ * This module is a standard Cordis plugin entry, written the same way the
+ * shipped dsh-mnemon Source packages are (see dsh-mnemon-source-runtime):
+ * `inject = ['mnemonMemory']` and `installMemory(ctx, ...)` inside `apply`.
+ * The Loader waits for the service, calls apply when it appears, and disposes
+ * the registration when it goes away.
+ *
+ * One concession to being distributable: the SDK is loaded with `createRequire`
+ * instead of a static `import`. A static import resolves fine for an npm
+ * install (the package sits under `<profile>/node_modules/`, with dsh-mnemon
+ * as a sibling ancestor) but fails for a `link:` checkout that lives outside
+ * the profile and has no `node_modules` of its own. `createRequire` with an
+ * explicit `DSH_PROFILE_DIR` fallback covers both shapes.
+ *
  * Why a Source is required at all: dsh-mnemon renders a page tab only when its
- * `sourceTypeId` appears in the live source catalog, and the catalog lists
+ * `sourceTypeId` appears in the live source catalog, and that catalog lists
  * real, running Source implementations. A UI-only contribution can borrow
  * `memory-spaces` and be shown, but the tab bar highlights *every* tab sharing
  * the selected page's type prefix, so borrowing means clicking one lights up
  * the other. Declaring our own type is the only way to get an independent tab.
  *
  * This Source is deliberately honest about what it holds. It is not a memory
- * backend: it stores no insights, so it contributes an empty projection and
- * declares no read routes or write actions. Its role is to be the identity the
- * sync page hangs from, which is why every capability is false and the facts
- * report only what the backup configuration currently is.
- *
- * The alternative — faking routes that answer with nothing — would pollute the
- * model's memory view with an empty source and could make a composition look
- * incomplete. An empty, clearly-labelled source is the smaller lie.
+ * backend: it stores no insights, contributes an empty projection and declares
+ * no read routes or write actions. Its role is to be the identity the sync
+ * page hangs from.
  */
 
 import { createHash } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import { join } from 'node:path'
 
 import { resolveDataRoot } from './index.js'
 import { inspectHome } from './snapshot.js'
 import { readSettings } from './store.js'
 
+const require = createRequire(import.meta.url)
+
 export const SYNC_SOURCE_TYPE_ID = 'mnemon-sync'
 export const SYNC_PACKAGE_NAME = '@summerscar/dsh-mnemon-sync'
 
+export const name = SYNC_PACKAGE_NAME
+// The one dependency the Source needs. The Loader holds this Entry until
+// dsh-mnemon publishes mnemonMemory, then mounts it.
+export const inject = ['mnemonMemory']
+
+/**
+ * Resolve the extension SDK synchronously so `apply` can stay synchronous.
+ * Tries normal package resolution first, then the profile-anchored absolute
+ * path for linked checkouts.
+ */
+function loadSdk() {
+  try {
+    return require('dsh-mnemon/extension-sdk')
+  } catch {
+    // Fall through: linked checkout has no ancestor node_modules.
+  }
+  const profileDir = process.env.DSH_PROFILE_DIR?.trim()
+  const candidates = []
+  if (profileDir !== undefined && profileDir !== '') {
+    candidates.push(join(profileDir, 'node_modules', 'dsh-mnemon', 'lib', 'extension-sdk.js'))
+  }
+  candidates.push(join(process.env.DSH_HOME ?? '', 'profiles', 'web', 'node_modules', 'dsh-mnemon', 'lib', 'extension-sdk.js'))
+  for (const candidate of candidates) {
+    if (candidate === '' || !existsSync(candidate)) continue
+    return require(candidate)
+  }
+  return undefined
+}
+
+const sdk = loadSdk()
+
+/** The plugin descriptor, validated by the SDK when available. */
+export const memoryPlugin = sdk === undefined ? {
+  packageName: SYNC_PACKAGE_NAME,
+  label: { en: 'Sync backup', 'zh-CN': '同步备份' },
+  description: {
+    en: 'Back up and restore dsh-mnemon memory components.',
+    'zh-CN': '备份与恢复 dsh-mnemon 的记忆组件。',
+  },
+  roles: ['source'],
+  provides: [{ id: 'source' }],
+} : sdk.defineMemoryPlugin({
+  packageName: SYNC_PACKAGE_NAME,
+  label: { en: 'Sync backup', 'zh-CN': '同步备份' },
+  description: {
+    en: 'Back up and restore dsh-mnemon memory components.',
+    'zh-CN': '备份与恢复 dsh-mnemon 的记忆组件。',
+  },
+  roles: ['source'],
+  provides: [{ id: 'source' }],
+})
+
 /** The manifest Core validates before this Source may take part in a View. */
 export const syncSourceManifest = {
   apiVersion: 'dsh-mnemon/v1',
@@ -43,30 +107,21 @@ export const syncSourceManifest = {
   consistency: 'exact-snapshot',
   routes: [],
   actions: [],
-  // A management descriptor is not decoration. dsh-mnemon builds its Source
-  // catalog from installed Sources that declare one, and the workbench decides
-  // a layer is "running" by whether its type is in that catalog — so a Source
-  // without `management` is installed but reported as "on yet not running".
-  // Fields stay empty: this page does its own editing.
+  // A management descriptor is required for managementCatalog to list this
+  // Source; without it the Source is installed but reported "on yet not running".
   management: {
     label: 'Sync backup',
-    description: 'Archive memory spaces to S3 or WebDAV.',
+    description: 'Back up and restore dsh-mnemon memory components.',
   },
 }
 
 /**
  * Build the Source definition.
  *
- * `facts()` must return the Host's *facts envelope* — `sourceInstanceKey`,
+ * `facts()` returns the Host's facts envelope — `sourceInstanceKey`,
  * `sourceTypeId`, `role`, `availability`, `revision`, `capabilities`,
- * `routeIds`, `actionIds` (plus optional `hints`). dsh-mnemon rejects anything
- * else: `normalizeFacts()` compares `facts.sourceInstanceKey` against the
- * registry key and throws `memory Source facts instance mismatch` when it is
- * missing, which is exactly what a `{ summary, details }` shape produced.
- *
- * `hints` is the only free-form channel that survives normalization, so the
- * backup configuration a human may want to see travels there. `project()`
- * returns `{ fragments: [] }`: there is no memory content here to contribute.
+ * `routeIds`, `actionIds` (plus optional `hints`). `project()` brings nothing
+ * into a prompt, because there is no memory content here to bring.
  */
 export function createSyncSource(manifest = syncSourceManifest) {
   return {
@@ -81,21 +136,18 @@ export function createSyncSource(manifest = syncSourceManifest) {
       return {
         facts() {
           const settings = safeSettings(home)
-          const inspected = safeInspect(dataRoot)
+          const inspected = safeInspect(home)
           return {
             sourceInstanceKey: context.sourceInstanceKey,
             sourceTypeId: manifest.typeId,
             role: manifest.role,
-            // This Source is a maintenance identity, not a memory backend: it
-            // is always ready and holds nothing a View could select.
             availability: 'ready',
             revision: configurationRevision(settings, inspected),
             capabilities: [],
             routeIds: [],
             actionIds: [],
-            // Facts are JSON only and must stay small: metadata the Host may
-            // surface, never memory content. Only `hints` survives
-            // normalization, so anything worth showing goes here.
+            // Only `hints` survives normalization, so the backup configuration
+            // a human may want to see travels there.
             hints: {
               summary: settings.enabled
                 ? `Sync backup every ${String(settings.autoSyncMinutes)} min to ${describeTarget(settings.target)}`
@@ -114,7 +166,6 @@ export function createSyncSource(manifest = syncSourceManifest) {
           }
         },
         project() {
-          // Nothing to inject: this Source holds no memories to contribute.
           return { fragments: [] }
         },
         dispose() {},
@@ -123,13 +174,23 @@ export function createSyncSource(manifest = syncSourceManifest) {
   }
 }
 
+/** The standard Cordis entry point, identical in shape to the shipped Sources. */
+export function apply(ctx, config = {}) {
+  if (sdk === undefined) {
+    // dsh-mnemon is not installed at all; the backup engine in index.js still
+    // works, only the page is unavailable. Do not fake a registration.
+    console.warn('mnemon-sync: dsh-mnemon extension SDK not found; the sync tab stays hidden')
+    return
+  }
+  sdk.installMemory(ctx, {
+    plugin: memoryPlugin,
+    sources: [sdk.defineMemorySource(createSyncSource({ ...syncSourceManifest }))],
+  }, config?.instanceId === undefined ? undefined : { instanceId: config.instanceId })
+}
+
 /**
- * A stable revision for the current backup configuration.
- *
- * The Host requires a non-empty string and compares it across a turn, so this
- * must change when the configuration changes and stay equal otherwise. It is
- * derived from the facts themselves rather than a clock, which keeps
- * composition deterministic.
+ * A stable revision for the current backup configuration, derived from the
+ * facts themselves rather than a clock so composition stays deterministic.
  */
 function configurationRevision(settings, inspected) {
   const material = JSON.stringify({