dsh-wsl-desktop 0.7.1 → 0.7.3

package/README.en.md

@@ -157,6 +157,7 @@ These are real boundaries, not a disclaimer list. Each one tells you where to re
 - [Distro support matrix](docs/DISTRO-SUPPORT.md) — which distros were verified, and what each one needs
 - [Compatibility and upgrades](docs/COMPATIBILITY.md) — plugin/desktop version relation, upgrade order, rollback steps
 - [Upstream API proposals](docs/UPSTREAM-PROPOSALS.md) — the two proposals to the harness upstream
+- [Upstream defect reports](issues/README.md) — the harness issues filed, their measured evidence, and how the local workarounds relate
 - [Architecture and flow diagrams](docs/diagrams.md) — interactive architecture, sequence and lifecycle diagrams
 
 Three of the linked documents — the distro support matrix, the upstream proposals and the diagram

package/README.md

@@ -130,6 +130,7 @@ plugin_manager install_bundle dsh-wsl-desktop@<version>
 - [发行版支持矩阵](docs/DISTRO-SUPPORT.md) — 哪些发行版验证过，每种缺什么
 - [兼容性与升级](docs/COMPATIBILITY.md) — 插件与桌面的版本关系、升级顺序、回退步骤
 - [上游 API 提案](docs/UPSTREAM-PROPOSALS.md) — 对 harness 上游的两项提案
+- [上游缺陷记录](issues/README.md) — 已上报 harness 的问题、实测证据与本地规避的关系
 - [架构与流程图](docs/diagrams.md) — 可交互的架构、时序与生命周期图
 
 其中三份——发行版支持矩阵、上游 API 提案、架构与流程图索引——**只有中文版**，因为目前没有对应的

package/lib/client.js

@@ -21,8 +21,23 @@ window.__ModuleLoader__.load({
   id: 'dsh-wsl-desktop',
   factory() {
     // MUST stay equal to the host half's Config.routePath default (lib/index.js).
+    /*
+     * Section index. This file is ONE loader module: `window.__ModuleLoader__`
+     * evaluates a single factory, and splitting it across files would need a
+     * loader capability that has not been measured. The boundaries below are
+     * therefore comments, not files — they exist so a reader can hold one
+     * section at a time, and so a future split has its seams already named.
+     *   1. endpoint, trigger geometry and locale
+     *   2. copy, theme and shared node helpers
+     *   3. route calls and failure rendering
+     *   4. the W workspace picker dialog
+     *   5. the companion button and workspace rows
+     *   6. module registration and dispose
+     */
+
     // Nothing derives one from the other: a deployment that mounts the route
     // elsewhere loses the picker silently.
+    // ── 1. endpoint, trigger geometry and locale ─────────────────────────────
     const ENDPOINT = '/wsl-desktop/api'
 
     /**
@@ -38,6 +53,34 @@ window.__ModuleLoader__.load({
       'M5.54492 2.06738',           // post-refactor ProjectAddOutlineArtwork
     ]
 
+    /**
+     * The same trigger, named by sprite symbol instead of path data.
+     *
+     * Desktop 0.2.1-rc3 (ui-primitives `c3eead771d`) moved every product icon
+     * into the document icon sprite: the header button now renders
+     * `<svg data-icon="dsw-icon-project-add-outline-regular"><use href="#…"/></svg>`
+     * with NO `<path>` child anywhere. The geometry scan above therefore matched
+     * nothing, the anchor read as absent, and the W button stood down on every
+     * 0.2.1-rc3 desktop. The glyph name is the locale-independent identity in
+     * that generation, exactly as the path prefix was in the previous one, and a
+     * theme may replace the artwork without renaming the symbol — so the name
+     * survives the change that broke the geometry.
+     */
+    const TRIGGER_ICON_GLYPHS = ['project-add-outline']
+
+    /** Sprite symbol id shape, as `iconSymbolId` composes it: `dsw-icon-<glyph>-<weight>`. */
+    const SPRITE_ICON_ID = /^#?dsw-icon-(.+)-(?:regular|medium)$/
+
+    /**
+     * The row glyphs whose artwork is FILL-only, as sprite names.
+     *
+     * Only the fallback for a sprite symbol that is not in the document yet; the
+     * live read (`isSolidIcon`) prefers the symbol's own geometry. Versions
+     * qualify the id (`symbolId(glyph, weight)`), so the suffix is not part of a
+     * glyph name and the match is on the glyph alone.
+     */
+    const SOLID_GLYPHS = ['folder-open']
+
     /** Namespace of every SVG node this half creates. */
     const SVG_NS = 'http://www.w3.org/2000/svg'
 
@@ -74,6 +117,7 @@ window.__ModuleLoader__.load({
      * The catalog is bilingual, so the dialog can render a host failure in the
      * operator's language without a translation build step.
      */
+    // ── 2. copy, theme and shared node helpers ─────────────────────────────
     const LOCALE = typeof navigator !== 'undefined' && /^zh/i.test(String(navigator.language ?? '')) ? 'zh' : 'en'
 
     /**
@@ -288,6 +332,7 @@ window.__ModuleLoader__.load({
      * @param {object|null} envelope - the route's JSON body, when it parsed.
      * @returns {Error} the failure, with `code` and `params` attached.
      */
+    // ── 3. route calls and failure rendering ─────────────────────────────
     function routeFailure(method, status, envelope) {
       const error = new Error(envelope?.error ?? `${method} failed (HTTP ${status})`)
       error.code = typeof envelope?.code === 'string' ? envelope.code : status === 0 ? 'transport' : 'internal'
@@ -705,6 +750,7 @@ window.__ModuleLoader__.load({
      * so lastIndexOf returned -1 and slice(0, -1) gave 'hom'/'tm' — the host
      * listed /tmp while the "up" button navigated to /tm.
      */
+    // ── 4. the W workspace picker dialog ─────────────────────────────
     function parentOf(path) {
       const absolute = path.startsWith('/') ? path : `/${path}`
       const trimmed = absolute.replace(/\/+$/, '')
@@ -1471,20 +1517,74 @@ window.__ModuleLoader__.load({
     }
 
     /** The injected services the picker and its trigger read. */
+    // ── 5. the companion button and workspace rows ─────────────────────────────
     const companion = { button: null, fallback: null, trigger: null, observer: null, scheduled: false, disposed: false }
 
     /** Whether the missing-workspace-source warning was already printed. */
     let warnedWorkspaceSource = false
 
-    /** Find the shipped "add workspace" trigger by its icon geometry. */
-    function findTrigger() {
+    /**
+     * The sprite glyph one `<use>` reference names, or null.
+     *
+     * Accepts both the bare symbol id and the `#`-prefixed href form, and both
+     * `href` and the legacy `xlink:href` spelling, because an icon may render
+     * either. Returning the GLYPH (not the whole id) lets the trigger list stay
+     * a list of glyph names, which is what a desktop generation actually fixes.
+     * @param {Element} node - a `<use>` element.
+     * @returns {string | null} the glyph name, or null when it is not a sprite ref.
+     */
+    function spriteGlyphOf(node) {
+      const ref = node.getAttribute('href')
+        ?? node.getAttributeNS('http://www.w3.org/1999/xlink', 'href')
+      if (ref === null) return null
+      return SPRITE_ICON_ID.exec(ref)?.[1] ?? null
+    }
+
+    /**
+     * The candidate trigger buttons carrying one generation's icon identity.
+     *
+     * Each generation is ONE document-level selector rather than a walk over
+     * every button: `findTrigger` re-runs on every animation frame whenever the
+     * anchor is missing, so a per-button subtree query would turn a single scan
+     * into N of them exactly when the header is already in trouble.
+     * @param {string} selector - the icon nodes this generation renders.
+     * @param {(node: Element) => boolean} identifies - whether one icon is the trigger's.
+     * @returns {HTMLElement[]} the distinct buttons owning a matching icon.
+     */
+    function triggerCandidates(selector, identifies) {
       const matches = []
-      for (const path of document.querySelectorAll('svg > path[d]')) {
-        const d = path.getAttribute('d')
-        if (!TRIGGER_ICON_PATHS.some((geometry) => d.startsWith(geometry))) continue
-        const trigger = path.closest('button')
+      for (const icon of document.querySelectorAll(selector)) {
+        if (!identifies(icon)) continue
+        const trigger = icon.closest('button')
         if (trigger !== null && !matches.includes(trigger)) matches.push(trigger)
       }
+      return matches
+    }
+
+    /** Whether one inline path carries the add-workspace geometry. */
+    function isTriggerPath(path) {
+      const d = path.getAttribute('d')
+      return TRIGGER_ICON_PATHS.some((geometry) => d.startsWith(geometry))
+    }
+
+    /**
+     * Whether one icon node is the add-workspace artwork, in either generation.
+     *
+     * A sprite icon is identified by `data-icon` (the id the component was
+     * CONSTRUCTED with, which a theme replacement does not change) and, failing
+     * that, by the `<use>` reference it renders.
+     * @param {Element} icon - an inline path or a sprite `<svg>`/`<use>`.
+     * @returns {boolean} true when it is the trigger's artwork.
+     */
+    function isTriggerIcon(icon) {
+      if (icon.tagName === 'path') return isTriggerPath(icon)
+      const declared = icon.tagName === 'svg' ? icon.getAttribute('data-icon') : null
+      const glyph = declared !== null ? SPRITE_ICON_ID.exec(declared)?.[1] : spriteGlyphOf(icon)
+      return glyph !== undefined && glyph !== null && TRIGGER_ICON_GLYPHS.includes(glyph)
+    }
+
+    /** Pick the trigger out of one generation's candidates, or null. */
+    function pickTrigger(matches) {
       if (matches.length <= 1) return matches[0] ?? null
       // More than one control carries the geometry. The shipped trigger is the
       // one inside a `*_headerActions` cluster — the CSS-module local name is
@@ -1494,6 +1594,24 @@ window.__ModuleLoader__.load({
       return matches.find((trigger) => hasHeaderActionsParent(trigger)) ?? null
     }
 
+    /**
+     * Find the shipped "add workspace" trigger in either desktop generation.
+     *
+     * The sprite generation is scanned FIRST because it is the newer one: on a
+     * desktop that renders it, that single scan is the whole cost. Only a
+     * desktop with no sprite icon anywhere falls through to the geometry scan,
+     * which is what every release before 0.2.1-rc3 needed.
+     * @returns {HTMLElement | null} the anchor, or null when this desktop has none.
+     */
+    function findTrigger() {
+      const sprite = triggerCandidates('svg[data-icon], use', isTriggerIcon)
+      // A non-empty sprite result is this desktop's answer even when it is
+      // ambiguous: `pickTrigger` returns null there to mean "stand down", and
+      // falling through would let an unrelated inline icon pick the anchor.
+      if (sprite.length > 0) return pickTrigger(sprite)
+      return pickTrigger(triggerCandidates('svg > path[d]', isTriggerIcon))
+    }
+
     /**
      * Whether one trigger sits in the shipped trailing action cluster.
      * @param {HTMLElement} trigger - a candidate trigger button.
@@ -1637,7 +1755,7 @@ window.__ModuleLoader__.load({
         // artwork fills its paths, the collapsed one strokes them. A rebuild is
         // owed whenever that flips, which is exactly what expanding a workspace
         // does to this span.
-        const solid = shipped !== null && shipped.querySelector('path[stroke]') === null
+        const solid = isSolidIcon(shipped)
         const weight = solid ? 'solid' : 'outline'
         if (mine !== null && mine.dataset.wslCloudWeight !== weight) {
           mine.remove()
@@ -1648,6 +1766,56 @@ window.__ModuleLoader__.load({
       }
     }
 
+    /**
+     * The sprite symbol an icon element references, as a bare symbol id.
+     *
+     * `data-icon` is the id the icon COMPONENT was built with, so it keeps the
+     * shipped symbol even when a theme points the `<use>` href at its own
+     * artwork; the href is the fallback for markup that omits `data-icon`.
+     * @param {Element} icon - one icon `<svg>`.
+     * @returns {string | null} the symbol id without `#`, or null.
+     */
+    function spriteSymbolOf(icon) {
+      const declared = icon.getAttribute('data-icon')
+      if (typeof declared === 'string' && declared !== '') return declared.replace(/^#/, '')
+      for (const use of icon.querySelectorAll('use')) {
+        const ref = use.getAttribute('href')
+          ?? use.getAttributeNS('http://www.w3.org/1999/xlink', 'href')
+        if (typeof ref === 'string' && ref !== '') return ref.replace(/^#/, '')
+      }
+      return null
+    }
+
+    /**
+     * Whether one workspace row icon renders the FILL-only artwork.
+     *
+     * The collapsed row strokes its folder outline and the expanded one fills
+     * it, and the cloud has to match whichever is showing. Up to 0.2.1-rc2 the
+     * artwork was inline, so a stroked `<path>` was the tell. From 0.2.1-rc3 the
+     * icon is a sprite reference with NO path child anywhere: the weight then
+     * belongs to the SYMBOL in the document sprite, not to the `<svg>` naming
+     * it. Reading only the inline shape (as this did) made every sprite row look
+     * fill-only, so a collapsed row got the solid cloud.
+     * @param {Element | null} icon - the shipped folder icon, if the row renders one.
+     * @returns {boolean} true when the icon is the fill-only artwork.
+     */
+    function isSolidIcon(icon) {
+      if (icon === null) return false
+      // Inline generation: the artwork declares its own weight.
+      if (icon.querySelector('path[d]') !== null) return icon.querySelector('path[stroke]') === null
+      const symbolId = spriteSymbolOf(icon)
+      if (symbolId === null) return false
+      const symbol = document.getElementById(symbolId)
+      // Sprite generation, symbol present: judge the artwork the browser paints,
+      // so a theme's own geometry is measured rather than assumed.
+      if (symbol !== null) return symbol.querySelector('path[stroke]') === null
+      // Sprite generation, symbol not in the document (a theme may mount its
+      // own sprite later): fall back to the glyph name, which is the fill-only
+      // identity in the shipped table.
+      const glyph = SPRITE_ICON_ID.exec(`#${symbolId}`)?.[1]
+      return glyph !== undefined && glyph !== null && SOLID_GLYPHS.includes(glyph)
+    }
+
     /**
      * Whether one observed mutation could have changed a workspace row's markup.
      *
@@ -1904,6 +2072,8 @@ window.__ModuleLoader__.load({
       }
     }
 
+
+    // ── 6. module registration and dispose ─────────────────────────────
     return {
       // `remote.session` is the namespace the create request travels through
       // (see `createBoundSession`); the harness's own client plugins inject it

package/lib/host/http.js

@@ -0,0 +1,110 @@
+/**
+ * The route's HTTP seam: reading a JSON body, answering with one, and deciding
+ * whether a caller may reach the development-token surface.
+ *
+ * Extracted verbatim from `lib/index.js` (C3). Nothing in here is new behaviour;
+ * the move exists so the plugin entry file carries wiring and lifecycle rather
+ * than request plumbing.
+ * @module dsh-wsl-desktop/host/http
+ */
+
+import { randomBytes, timingSafeEqual } from 'node:crypto'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { MAX_BODY_BYTES, DEV_TOKEN_HEADER, tokenMatches } from '../http-admission.js'
+
+/**
+ * The harness home that holds the user preset root.
+ * @returns {string} the resolved `$DSH_HOME`.
+ */
+export function dshHome() {
+  return process.env.DSH_HOME ?? join(homedir(), '.dsh')
+}
+
+/**
+ * Read one JSON request body, bounded.
+ * @param {import('node:http').IncomingMessage} req - the request to drain.
+ * @returns {Promise<{ text: string | null, byteLength: number }>} the body, or null past the ceiling.
+ */
+export async function readJsonBody(req) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of req) {
+    size += chunk.byteLength
+    if (size > MAX_BODY_BYTES) {
+      // Drain the remainder so the refusal is a readable response, not a socket cut.
+      req.resume()
+      return { text: null, byteLength: size }
+    }
+    chunks.push(chunk)
+  }
+  return { text: Buffer.concat(chunks, size).toString('utf8'), byteLength: size }
+}
+
+/**
+ * Answer one request with a JSON envelope and an explicit status.
+ * @param {import('node:http').ServerResponse} res - the response to complete.
+ * @param {number} status - the HTTP status.
+ * @param {{ ok: boolean }} payload - the envelope, success or failure.
+ */
+export function sendJson(res, status, payload) {
+  const body = JSON.stringify(payload)
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': Buffer.byteLength(body),
+    'cache-control': 'no-store',
+  })
+  res.end(body)
+}
+
+/**
+ * Answer with one admission rejection.
+ * @param {import('node:http').ServerResponse} res - the response to complete.
+ * @param {import('../http-admission.js').Rejection} rejection - the refusal.
+ */
+export function sendRejection(res, rejection) {
+  sendJson(res, rejection.status, { ok: false, code: rejection.code, error: rejection.message })
+}
+
+/** Trust surface consumed here; the browser-side connection package owns the full type. */
+export function connectionOf(ctx) {
+  return Reflect.get(ctx, 'connection')
+}
+
+/**
+ * This installation's development token, minted on first use.
+ *
+ * The file is owner-only and lives outside the repository. A web page cannot
+ * read it, which is what keeps the acceptance surface unreachable from a
+ * cross-site request even though the route itself is on loopback.
+ * @returns {Promise<string>} the token.
+ */
+export async function devToken() {
+  const path = join(dshHome(), 'wsl-desktop-dev-token')
+  try {
+    const existing = (await readFile(path, 'utf8')).trim()
+    if (existing.length > 0) return existing
+    // An empty file is unusual — treat it like absent and re-mint below.
+  } catch (error) {
+    // ENOENT = first use. Any other read failure (ACL, AV lock, disk) must
+    // fail loud rather than silently rotate the credential and revoke every
+    // scripted caller.
+    if (error?.code !== 'ENOENT') throw error
+  }
+  const minted = randomBytes(32).toString('hex')
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, `${minted}\n`, { mode: 0o600 })
+  return minted
+}
+
+/**
+ * Whether one request may use the acceptance surface.
+ * @param {import('node:http').IncomingMessage} req - the request.
+ * @param {{ developerTools: boolean }} config - resolved plugin config.
+ * @returns {Promise<boolean>} true for a caller presenting this installation's token.
+ */
+export async function isDeveloperCaller(req, config) {
+  if (config.developerTools !== true) return false
+  return tokenMatches(req.headers[DEV_TOKEN_HEADER], await devToken(), timingSafeEqual)
+}

package/lib/host/presets.js

@@ -0,0 +1,97 @@
+/**
+ * Preset derivation helpers: variant ids, base rows, and the shell-spec seam.
+ *
+ * Extracted verbatim from `lib/index.js` (C3). Only the PURE helpers moved: the
+ * two that materialise and refresh presets stay in the entry file because they
+ * read and write the plugin's module-level state (`presetState`, `currentGeneration`,
+ * `hostCtx`, `hostReady`). Moving those would mean shipping that state or injecting
+ * it, which is a rewrite, not a move — see the plan's "Out of Scope".
+ * @module dsh-wsl-desktop/host/presets
+ */
+
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { dshHome } from './http.js'
+
+/**
+ * The prefix every generated variant id carries.
+ *
+ * Not exported from `index.js` by accident: the same literal is what the route
+ * filters on, so a change here is a wire-visible change.
+ */
+export const GENERATED_PREFIX = 'wsl-'
+
+/**
+ * The stable id for one base preset's WSL variant.
+ * @param {{ id: string }} preset - the resolved base preset.
+ * @returns {string} the variant id.
+ */
+export function variantIdFor(preset) {
+  return preset.id.startsWith(GENERATED_PREFIX) ? preset.id : `${GENERATED_PREFIX}${preset.id}`
+}
+
+/**
+ * Locate the directory a preset was discovered under.
+ *
+ * A preset may name a row by a path relative to its own directory, so the
+ * variant needs that base to rewrite the name to something that still resolves
+ * from where the variant lives.
+ *
+ * Both spellings are historical: the package is `@deepseek-ai/dsh-agent-preset`
+ * (singular — the plural name never existed, so this resolve always threw), and
+ * since the presets moved into profile YAML declarations the package ships no
+ * `presets/<id>/agent.cordis.yml` tree at all. Neither branch is expected to
+ * hit on a current desktop; a base preset that DOES use relative row names
+ * therefore has no resolvable source directory, and `buildVariantPlugins`
+ * leaves the name as it found it. This stays a lookup rather than a guess so
+ * the failure mode is unchanged if a deployment ever ships that tree again.
+ * @param {string} id - preset id.
+ * @returns {string | undefined} the directory, or undefined when it cannot be found.
+ */
+export function sourceDirFor(id) {
+  const local = join(dshHome(), '.agent-presets', id)
+  if (existsSync(join(local, 'agent.cordis.yml'))) return local
+  try {
+    const manifest = fileURLToPath(import.meta.resolve('@deepseek-ai/dsh-agent-preset/package.json'))
+    const shipped = join(dirname(manifest), 'presets', id)
+    if (existsSync(join(shipped, 'agent.cordis.yml'))) return shipped
+  } catch {
+    // A deployment without the preset package leaves relative names as they are.
+  }
+  return undefined
+}
+
+/**
+ * Read a base preset's declared plugin rows as OBJECTS.
+ *
+ * 0.1.7 keeps each declaration's `PresetDefinition` — with `plugins` as entry
+ * objects — in a registry map that is TS-private but reachable in-process
+ * (ctx.get returns the service instance). No YAML parser is needed on this
+ * path; the public readDocument only exposes a re-dumped text form.
+ * @param {object} presets - the agentPresets service.
+ * @param {string} id - base preset id.
+ * @returns {readonly object[] | null} the declared rows, or null when unreachable.
+ */
+export function basePluginsOf(presets, id) {
+  const plugins = presets.definitions?.get?.(id)?.config?.plugins
+  return Array.isArray(plugins) ? plugins : null
+}
+
+/**
+ * Run a shell spec through whichever seam the host exposes, and always hand back a
+ * handle whose `result()` is awaitable.
+ *
+ * 0.1.7 hosts expose `execute`, which resolves with a live handle; older ones have
+ * only `run`, whose settled result carries no `result()` projection. Both selftest
+ * steps used to spell that dual dispatch themselves, and the second one called
+ * `.result()` on `run`'s settled result — a TypeError on exactly the hosts that
+ * branch exists to support. One owner, so the two steps cannot drift again.
+ * @param {object} shell - the realm's shell service.
+ * @param {object} spec - the resolved spec to run.
+ * @returns {Promise<{ result: () => Promise<object> }>} a result()-able handle.
+ */
+export function runShellSpec(shell, spec) {
+  if (typeof shell.execute === 'function') return shell.execute(spec)
+  return shell.run(spec).then((settled) => ({ result: async () => settled }))
+}

package/lib/host/state.js

@@ -0,0 +1,58 @@
+/**
+ * The plugin's module-level state, named and grouped.
+ *
+ * The route dispatcher calls `METHODS` without carrying the plugin's config, so
+ * the context, the configured `wsl.exe` path and the preset lifecycle cannot be
+ * parameters. They were loose module-level `let`s in `lib/index.js` (seven of them,
+ * counting the binding log and its cap); this module gives
+ * each group one owner, so a reader can see what is shared and why.
+ *
+ * Nothing here is a getter/setter pair: the objects are mutable, and every call
+ * site reads a field. That keeps the move mechanical — `hostCtx.get(x)` became
+ * `hostSession.ctx.get(x)`.
+ * @module dsh-wsl-desktop/host/state
+ */
+
+/** The plugin context and the config it was applied with, as route methods see them. */
+export const hostSession = {
+  /** @type {import('@deepseek-ai/cordis').Context | undefined} */
+  ctx: undefined,
+  /** The configured `wsl.exe` path; the default a fresh install runs with. */
+  wslPath: 'wsl.exe',
+  /** Whether the preset registry has been reached; `bootstrap` waits briefly for it. */
+  ready: false,
+}
+
+/** The preset registration lifecycle. */
+export const presetRun = {
+  /** @type {{ status: string } & Record<string, unknown>} */
+  state: { status: 'pending' },
+  /** @type {{ disposed: boolean, disposers: Map<string, Function> } | null} */
+  generation: null,
+  /** Serialises refreshes so boot-time and developer-token calls cannot interleave. */
+  mutex: Promise.resolve(),
+}
+
+/** Most binding decisions kept for inspection. */
+export const BINDING_LOG_LIMIT = 50
+
+/** The bounded record of preset-binding decisions, reported through the route. */
+export const bindingTape = (() => {
+  /** @type {object[]} */
+  const log = []
+  return {
+    log,
+    /**
+     * Record one decision, dropping the oldest past the cap.
+     *
+     * The log is captured by the closure rather than read off `this`: a caller that
+     * destructures the method (`const { record } = bindingTape`) would otherwise get
+     * `TypeError: this.log is undefined` at the first write.
+     * @param {object} entry - the decision to record.
+     */
+    record(entry) {
+      log.push(entry)
+      if (log.length > BINDING_LOG_LIMIT) log.splice(0, log.length - BINDING_LOG_LIMIT)
+    },
+  }
+})()