@goodandready/dsh-github-ops 0.1.2 → 0.2.1

package/lib/github.js

@@ -96,7 +96,10 @@ export function createGitHubClient({
   userAgent = DEFAULT_USER_AGENT,
   fetchImpl = globalThis.fetch,
   sleepImpl,
+  signalProvider,
   timeoutMs = 30000,
+  cacheTtlMs = 60000,
+  cacheLimit = 200,
   maxRetries = 2,
   retryBaseMs = 500,
   maxRetryDelayMs = 10000,
@@ -108,7 +111,30 @@ export function createGitHubClient({
     ? sleepImpl
     : (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 
-  async function attemptOnce({ method, path, query, body, url, accept, redirect }) {
+  // A short TTL cache for reads only: a composed report or a repeated list must not spend
+  // the rate limit twice. Writes always go to the network.
+  let lastScopesValue = ''
+  const cache = new Map()
+  const cacheKey = (method, target) => `${method} ${target}`
+  function cacheGet(key) {
+    const hit = cache.get(key)
+    if (!hit) return null
+    if (hit.expiresAt <= Date.now()) {
+      cache.delete(key)
+      return null
+    }
+    return hit.value
+  }
+  function cacheSet(key, value) {
+    if (!(cacheTtlMs > 0)) return
+    if (cache.size >= cacheLimit) {
+      const oldest = cache.keys().next().value
+      cache.delete(oldest)
+    }
+    cache.set(key, { value, expiresAt: Date.now() + cacheTtlMs })
+  }
+
+  async function attemptOnce({ method, path, query, body, url, accept, redirect, signal }) {
     const target = url || buildUrl(baseUrl, path, query)
     const headers = {
       accept,
@@ -122,6 +148,16 @@ export function createGitHubClient({
     const timer = controller && timeoutMs > 0
       ? setTimeout(() => controller.abort(), timeoutMs)
       : null
+    // The caller's signal (a cancelled turn) must abort the request too, not just the clock.
+    const combined = (() => {
+      if (!controller) return signal
+      if (!signal) return controller.signal
+      if (typeof AbortSignal !== 'undefined' && typeof AbortSignal.any === 'function') {
+        return AbortSignal.any([controller.signal, signal])
+      }
+      signal.addEventListener('abort', () => controller.abort(), { once: true })
+      return controller.signal
+    })()
 
     let response
     try {
@@ -129,19 +165,29 @@ export function createGitHubClient({
         method,
         headers,
         body: body === undefined ? undefined : JSON.stringify(body),
-        signal: controller ? controller.signal : undefined,
+        signal: combined || undefined,
         ...(redirect ? { redirect } : {}),
       })
     } catch (err) {
       if (timer) clearTimeout(timer)
       const aborted = err && (err.name === 'AbortError' || err.code === 'ABORT_ERR')
-      throw new GitHubError(aborted ? `request timed out after ${timeoutMs}ms` : String((err && err.message) || err), {
-        code: aborted ? 'timeout' : 'network',
-      })
+      // A caller cancellation (the turn was stopped) is not a timeout: saying "timed out"
+      // there sends the model looking for a network problem that does not exist.
+      const cancelled = aborted && signal && signal.aborted
+      const message = cancelled
+        ? 'request cancelled by the caller'
+        : aborted
+          ? `request timed out after ${timeoutMs}ms`
+          : String((err && err.message) || err)
+      throw new GitHubError(message, { code: cancelled ? 'cancelled' : aborted ? 'timeout' : 'network' })
     }
     if (timer) clearTimeout(timer)
 
     const rateLimit = rateLimitFrom(response.headers)
+    if (typeof response.headers.get === 'function') {
+      const scopes = response.headers.get('x-oauth-scopes')
+      if (scopes) lastScopesValue = String(scopes)
+    }
     const text = typeof response.text === 'function' ? await response.text() : ''
     let payload = null
     if (text) {
@@ -154,16 +200,25 @@ export function createGitHubClient({
     return { response, payload, rateLimit }
   }
 
-  async function call({ method = 'GET', path, query, body, url, accept = 'application/vnd.github+json', redirect }) {
+  async function call({ method = 'GET', path, query, body, url, accept = 'application/vnd.github+json', redirect, signal }) {
+    // The signal may come from the caller's turn: the shared client asks the provider, so a
+    // cancelled turn aborts the request in flight instead of waiting for the timeout.
+    const turnSignal = signal || (typeof signalProvider === 'function' ? signalProvider() : undefined)
     const upper = method.toUpperCase()
     const retryable = SAFE_RETRY_METHODS.has(upper)
+    const target = url || buildUrl(baseUrl, path, query)
+    const key = cacheKey(upper, target)
+    if (retryable) {
+      const cached = cacheGet(key)
+      if (cached) return { ...cached, cached: true }
+    }
     const attemptsAllowed = Math.max(1, Number(maxRetries) + 1)
     let lastError = null
 
     for (let attempt = 1; attempt <= attemptsAllowed; attempt += 1) {
       let result
       try {
-        result = await attemptOnce({ method: upper, path, query, body, url, accept, redirect })
+        result = await attemptOnce({ method: upper, path, query, body, url, accept, redirect, signal: turnSignal })
       } catch (err) {
         lastError = err
         if (!retryable || attempt >= attemptsAllowed) {
@@ -176,7 +231,9 @@ export function createGitHubClient({
 
       const { response, payload, rateLimit } = result
       if (response.ok) {
-        return { data: payload, status: response.status, rateLimit, attempts: attempt }
+        const value = { data: payload, status: response.status, rateLimit, attempts: attempt }
+        if (retryable) cacheSet(key, value)
+        return value
       }
 
       const message = (payload && (payload.message || payload.error)) || `HTTP ${response.status}`
@@ -210,6 +267,21 @@ export function createGitHubClient({
       return call({ method: 'GET', path, ...(opts || {}) })
     },
 
+    /** The OAuth scopes GitHub reported on the last answer, when it reported any. */
+    lastScopes() {
+      return lastScopesValue
+    },
+
+    /** Cache counters, for the settings card and for tests. */
+    cacheStats() {
+      return { size: cache.size, ttlMs: cacheTtlMs }
+    },
+
+    /** Drop the cache (a write may have invalidated what a read returned). */
+    cacheClear() {
+      cache.clear()
+    },
+
     post(path, body, opts) {
       return call({ method: 'POST', path, body, ...(opts || {}) })
     },
@@ -298,6 +370,28 @@ export function parseRepoSpec(spec) {
   return { owner: match[1], repo: match[2], number: match[3] ? Number(match[3]) : null }
 }
 
+/**
+ * What a human should try next for a given failure. An error that only says "HTTP 401" makes
+ * the model guess; a named next step makes it act.
+ */
+export function hintFor(err) {
+  if (!err) return ''
+  const status = err.status || 0
+  if (status === 401) return 'the access value is missing or expired: check the credential, the environment variable or `gh auth status`'
+  if (status === 403 && err.rateLimit && err.rateLimit.remaining === 0) {
+    return `the rate limit is spent and resets at ${err.rateLimit.resetAt || 'an unknown time'}: wait, or use a token with a higher limit`
+  }
+  if (status === 403) return 'the access value lacks the scope this call needs'
+  if (status === 404) return 'the repository, tag, issue or release does not exist, or the access value cannot see it (a draft release is only visible by id)'
+  if (status === 422) return 'GitHub rejected the payload: check the required fields'
+  if (status === 409) return 'the state changed under us (a conflict): read the object again and retry'
+  if (err.code === 'cancelled') return 'the turn was cancelled before GitHub answered'
+  if (err.code === 'timeout') return 'the request timed out: raise timeoutMs or retry'
+  if (err.code === 'network') return 'the network failed: retry, and check whether github.com resolves — a wrong /etc/hosts entry for github.com or api.github.com breaks every call'
+  if (err.code === 'rate_limited') return 'the rate limit is spent: wait for the reset before retrying'
+  return ''
+}
+
 /** Human-readable one-liner for a failure, used by every tool renderer. */
 export function describeError(err) {
   if (!err) return 'unknown error'
@@ -309,7 +403,9 @@ export function describeError(err) {
     if (err.rateLimit && err.rateLimit.remaining === 0) {
       parts.push(`rate limit exhausted, resets at ${err.rateLimit.resetAt || 'unknown'}`)
     }
-    return parts.length ? `${err.message} (${parts.join(', ')})` : err.message
+    const base = parts.length ? `${err.message} (${parts.join(', ')})` : err.message
+    const hint = hintFor(err)
+    return hint ? `${base} — ${hint}` : base
   }
   return String(err.message || err)
 }

package/lib/guidance.js

@@ -0,0 +1,26 @@
+// What the model is told about this plugin.
+//
+// A plugin with 50+ tools needs one short paragraph about how to use them, otherwise the
+// model guesses: which tool for which question, when a repository argument may be omitted,
+// and that approvals are the host's business rather than something these tools invent.
+
+/** Section name in the system prompt; unique, so a reload replaces it instead of clashing. */
+export const GUIDANCE_SECTION = 'dsh-github-ops'
+
+/** Placement among the other sections. */
+export const GUIDANCE_ORDER = 60
+
+/** The default text. Keep it short: it is paid for on every turn. */
+export const GUIDANCE_TEXT = [
+  'GitHub (dsh-github-ops):',
+  '- Unsure which tool fits? gh_help lists every one of them, grouped by area.',
+  '- Inside a checkout the repository argument can be omitted: the origin remote decides. Both "owner/repo#12" and a bare "12" are accepted.',
+  '- Prefer one composed call over many plain ones: gh_repo_report (what a repository is), gh_weekly_digest (what happened lately), gh_repo_health (what to fix), gh_review (a pull request as one pack), ci_run (a deterministic verdict).',
+  '- Reads are free. Deleting a file, a branch, a tag, a release, a secret or a ruleset, forcing a ref, and publishing a mirror need confirm: true; approvals themselves belong to the host, not to these tools.',
+  '- A failure states the next step; gh_auth_status says where the access comes from.',
+].join('\n')
+
+/** The text to register: the configured override, or the default. */
+export function guidanceText(configured) {
+  return configured && String(configured).trim() ? String(configured).trim() : GUIDANCE_TEXT
+}

package/lib/index.js

@@ -25,11 +25,22 @@ import { registerCoreTools } from './tools/register-core.js'
 import { registerCollabTools } from './tools/register-collab.js'
 import { registerMirrorTools } from './tools/register-mirror.js'
 import { registerOpsTools } from './tools/register-ops.js'
+import { registerInsightTools } from './tools/register-insights.js'
+import { registerWriteTools } from './tools/register-write.js'
+import { accessFilePath, readAccessFile } from './auth-device.js'
+import { DEFAULT_CLIENT_ID, DEFAULT_SCOPE } from './auth-device.js'
+import { GUIDANCE_SECTION, GUIDANCE_ORDER, guidanceText } from './guidance.js'
+import { registerRoutes, STATUS_PATH, SCM_PATH, PANEL_PATH } from './routes.js'
+import { lossless } from './lossless.js'
+import { AsyncLocalStorage } from 'node:async_hooks'
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 
 const execFileAsync = promisify(execFile)
 
+// Carries the current tool call's cancellation signal to the shared client.
+const callContext = new AsyncLocalStorage()
+
 /** git runner: never throws, always answers with a code and both streams. */
 function makeGitRunner() {
   return async (args, { cwd, env } = {}) => {
@@ -64,6 +75,31 @@ export const OUTPUT_SCHEMA = {
   },
 }
 
+/** Which area a tool belongs to, derived from its name so a new tool lands somewhere sane. */
+export function groupOf(toolName) {
+  const name = String(toolName || '')
+  const rules = [
+    [/^gh_release_/, 'releases'],
+    [/^gh_tag_/, 'tags'],
+    [/^gh_run_/, 'runs'],
+    [/^gh_secret_/, 'secrets'],
+    [/^gh_variable_/, 'variables'],
+    [/^gh_ruleset_/, 'rulesets'],
+    [/^gh_branch_protection_/, 'branch-protection'],
+    [/^gh_mirror_/, 'mirror'],
+    [/^gh_review_job|^gh_review$|^review_post$|^ci_run$|^gh_checks$|^pr_/, 'pull-requests'],
+    [/^issue_|^gh_issue$|^gh_search$/, 'issues'],
+    [/^gh_repo_report|^gh_weekly_digest|^gh_notifications|^gh_repo_health|^gh_compare|^gh_trending|^gh_contributors|^gh_user_repos|^gh_commits/, 'insights'],
+    [/^gh_repo|^gh_file/, 'repositories'],
+    [/^gh_push_|^gh_upload_|^gh_delete_/, 'write-files'],
+    [/^gh_auth_/, 'auth'],
+    [/^gh_api$/, 'api'],
+    [/^gh_help$/, 'meta'],
+  ]
+  for (const [pattern, group] of rules) if (pattern.test(name)) return group
+  return 'other'
+}
+
 const MAX_RENDER_CHARS = 20000
 
 /** Render a tool result for the model: readable text, bounded so one call cannot flood the turn. */
@@ -104,6 +140,22 @@ export const Config = Schema.object({
     .description('Retries for a read (GET/HEAD) on a network failure, a timeout or a 5xx. Writes are never retried automatically.'),
   reviewRulesJson: Schema.string().default('')
     .description('Optional review-rule overrides as JSON: sensitivePaths, sensitiveSeverity, attentionPaths, migrationPaths, testsRequired, sourcePatterns, testPatterns, largeDiffLines.'),
+  oauthClientId: Schema.string().default(DEFAULT_CLIENT_ID)
+    .description('OAuth application id used by gh_auth_login. The default is the public GitHub CLI application.'),
+  oauthScope: Schema.string().default(DEFAULT_SCOPE)
+    .description('OAuth scope requested by gh_auth_login.'),
+  oauthClientSecretRef: Schema.string().role('credential-ref').default('')
+    .description('Optional credential holding the OAuth client secret, for apps that require one.'),
+  accessFile: Schema.string().default('')
+    .description('Where gh_auth_login stores its sign-in (default: $DSH_HOME/github-ops-auth.json, mode 0600).'),
+  interceptLinks: Schema.boolean().default(false)
+    .description('Let a github.com link clicked in the conversation also select that repository for the Source control tab and the sidebar panel. Off by default: the link always opens in the browser either way.'),
+  guidance: Schema.boolean().default(true)
+    .description('Add a short paragraph about this plugin to the system prompt: which tool for which question, when the repository argument can be omitted, and that approvals belong to the host.'),
+  guidanceText: Schema.string().default('')
+    .description('Replace the default guidance paragraph with your own text.'),
+  cacheTtlMs: Schema.number().default(60000)
+    .description('How long a read stays cached, in milliseconds. A composed report then costs one request set instead of many; writes always go to the network.'),
   reviewJobTimeoutMs: Schema.number().default(120000)
     .description('How long a background review job may run before it is cancelled.'),
 })
@@ -142,6 +194,12 @@ export function apply(ctx, rawConfig) {
     }
   }
 
+  /** Where the plugin's own sign-in lives. */
+  function accessPath() {
+    const configured = liveConfig().accessFile
+    return configured && String(configured).trim() ? String(configured).trim() : accessFilePath()
+  }
+
   /** The gh CLI session, when the machine already has `gh auth login` done. */
   async function ghCliAccess() {
     const { stdout } = await execFileAsync('gh', ['auth', 'token'], { timeout: 10000, maxBuffer: 1024 * 1024 })
@@ -152,6 +210,11 @@ export function apply(ctx, rawConfig) {
   async function resolveToken() {
     const cfg = liveConfig()
     return resolveAccess({
+      // the sign-in this plugin stored itself (gh_auth_login) is one of the sources
+      runFile: async () => {
+        const stored = await readAccessFile(accessPath())
+        return stored && stored.token ? stored.token : ''
+      },
       // the credentials service takes a branded reference, not a bare name
       credentials: {
         resolve: async (name) => {
@@ -169,18 +232,40 @@ export function apply(ctx, rawConfig) {
     })
   }
 
+  // One client per configuration: the read cache lives in it, and the signal for the
+  // current tool call arrives through the async context.
+  let sharedClient = null
+  let sharedKey = ''
+
   async function client() {
     const cfg = liveConfig()
     const access = await resolveToken()
     if (!access.value) {
       throw new Error(`GitHub access is not configured: ${access.guidance || NO_ACCESS_GUIDANCE}`)
     }
-    return createGitHubClient({
-      token: access.value,
-      baseUrl: cfg.baseUrl || 'https://api.github.com',
-      timeoutMs: Number(cfg.timeoutMs) || 30000,
-      maxRetries: Number.isFinite(Number(cfg.maxRetries)) ? Number(cfg.maxRetries) : 2,
-    })
+    const key = [
+      access.source,
+      access.value.length,
+      cfg.baseUrl || '',
+      cfg.timeoutMs || '',
+      cfg.cacheTtlMs || '',
+      cfg.maxRetries ?? '',
+    ].join('|')
+    if (!sharedClient || sharedKey !== key) {
+      sharedClient = createGitHubClient({
+        token: access.value,
+        baseUrl: cfg.baseUrl || 'https://api.github.com',
+        timeoutMs: Number(cfg.timeoutMs) || 30000,
+        cacheTtlMs: Number.isFinite(Number(cfg.cacheTtlMs)) ? Number(cfg.cacheTtlMs) : 60000,
+        maxRetries: Number.isFinite(Number(cfg.maxRetries)) ? Number(cfg.maxRetries) : 2,
+        signalProvider: () => {
+          const store = callContext.getStore()
+          return store && store.signal ? store.signal : undefined
+        },
+      })
+      sharedKey = key
+    }
+    return sharedClient
   }
 
   /**
@@ -217,6 +302,10 @@ export function apply(ctx, rawConfig) {
    * plugin must never be the reason a deployment cannot start.
    */
   const skippedTools = []
+  /** Every registered tool, so gh_help never drifts from reality. */
+  const catalog = []
+  const WRITE_PREFIXES = ['pr_', 'issue_', 'review_post', 'gh_api', 'gh_run_rerun', 'gh_run_cancel', 'gh_mirror_publish', 'gh_release_', 'gh_tag_', 'gh_repo_create', 'gh_repo_edit', 'gh_secret_', 'gh_variable_', 'gh_ruleset_', 'gh_branch_protection_set', 'gh_branch_protection_delete', 'gh_push_']
+
   function tool(toolName, description, parameters, run) {
     const definition = defineTool({
       name: toolName,
@@ -227,10 +316,20 @@ export function apply(ctx, rawConfig) {
         render: (_args, value) => renderToolResult(toolName, value),
       },
       ...presentationFor(toolName),
-      execute: async (args) => {
+      execute: async (args, exec) => {
         try {
-          const value = await run(args || {})
-          return { ok: true, data: value }
+          const value = await callContext.run({ signal: exec && exec.signal }, () => run(args || {}))
+          // A write may invalidate what a cached read returned.
+          if (WRITE_PREFIXES.some((prefix) => toolName === prefix || toolName.startsWith(prefix))) {
+            try {
+              sharedClient?.cacheClear?.()
+            } catch {
+              // a cache reset must never fail a successful call
+            }
+          }
+          // One place decides what a result may contain: the harness refuses a value that
+          // cannot be serialised losslessly, and it refuses the whole call for one undefined.
+          return { ok: true, data: lossless(value) }
         } catch (err) {
           const out = { ok: false, error: describeError(err) }
           if (err instanceof GitHubError) {
@@ -238,12 +337,13 @@ export function apply(ctx, rawConfig) {
             if (err.code) out.code = err.code
             if (err.rateLimit) out.rateLimit = err.rateLimit
           }
-          return out
+          return lossless(out)
         }
       },
     })
     try {
       ctx.tools.register(definition)
+      catalog.push({ name: toolName, description, group: groupOf(toolName) })
     } catch (err) {
       if (!/is already registered/.test(String((err && err.message) || err))) throw err
       skippedTools.push(toolName)
@@ -251,10 +351,35 @@ export function apply(ctx, rawConfig) {
     }
   }
 
-  const deps = { tool, asRepo, client, liveConfig, reviewRules }
+  const pendingFlow = { current: null }
+  const authSeam = {
+    config: () => {
+      const cfg = liveConfig()
+      return { clientId: cfg.oauthClientId || DEFAULT_CLIENT_ID, scope: cfg.oauthScope || DEFAULT_SCOPE, secretRef: cfg.oauthClientSecretRef || '' }
+    },
+    path: accessPath,
+    remember: (flow) => { pendingFlow.current = flow },
+    pending: () => pendingFlow.current,
+    forget: () => { pendingFlow.current = null },
+    resolve: resolveToken,
+    secret: async () => {
+      const ref = liveConfig().oauthClientSecretRef
+      if (!ref) return ''
+      try {
+        const resolved = await ctx.credentials.resolve(credentialRef(ref))
+        return (resolved && resolved.value) || ''
+      } catch {
+        return ''
+      }
+    },
+  }
+
+  const deps = { tool, asRepo, client, liveConfig, reviewRules, auth: authSeam }
   registerCoreTools(deps)
   registerCollabTools(deps)
   registerOpsTools(deps)
+  registerInsightTools(deps)
+  registerWriteTools(deps)
   registerMirrorTools({
     tool,
     git: makeGitRunner(),
@@ -283,6 +408,30 @@ export function apply(ctx, rawConfig) {
     },
   })
 
+  registerRoutes(ctx, {
+    resolveToken,
+    client,
+    liveConfig,
+    describeError,
+    makeGitRunner,
+    cacheStats: () => (sharedClient && typeof sharedClient.cacheStats === 'function' ? sharedClient.cacheStats() : null),
+  })
+
+  // One short paragraph in the system prompt: 50+ tools otherwise leave the model guessing.
+  ctx.inject(['systemPrompt'], (sctx) => {
+    try {
+      const cfg = liveConfig()
+      if (cfg.guidance === false) return
+      sctx.systemPrompt.section({
+        name: GUIDANCE_SECTION,
+        order: GUIDANCE_ORDER,
+        text: guidanceText(cfg.guidanceText),
+      })
+    } catch (err) {
+      ctx.logger?.warn?.('[dsh-github-ops] system prompt guidance not registered:', err && err.message)
+    }
+  })
+
   // Slash commands are a fast path for a human: they only hand the model an instruction, so
   // the write still passes through the host approval contour.
   ctx.inject(['commands'], (cctx) => {
@@ -308,6 +457,31 @@ export function apply(ctx, rawConfig) {
   })
 
 
+  // The catalog is built from the registrations above, so it cannot go stale.
+  tool(
+    'gh_help',
+    'Catalog of every tool this plugin provides, grouped by area, with one line each. Call it when unsure which tool fits — it lists what exists instead of guessing.',
+    { group: { type: 'string', description: 'Optional: only this group (repositories, releases, tags, issues, pull-requests, runs, secrets, variables, rulesets, branch-protection, mirror, jobs, api, meta).' } },
+    async (args) => {
+      const groups = {}
+      for (const entry of catalog) {
+        if (entry.name === 'gh_help') continue
+        groups[entry.group] = groups[entry.group] || []
+        groups[entry.group].push({ name: entry.name, description: entry.description })
+      }
+      if (args.group) {
+        const only = groups[args.group]
+        if (!only) return { error: `unknown group "${args.group}"`, groups: Object.keys(groups).sort() }
+        return { group: args.group, count: only.length, tools: only }
+      }
+      return {
+        count: Object.values(groups).reduce((sum, list) => sum + list.length, 0),
+        groups: Object.keys(groups).sort().map((name) => ({ name, count: groups[name].length })),
+        tools: groups,
+      }
+    },
+  )
+
   if (skippedTools.length) {
     ctx.logger?.warn?.(
       `[dsh-github-ops] ${skippedTools.length} tool(s) left to the plugin that already provides them: `

package/lib/lossless.js

@@ -0,0 +1,90 @@
+// Making every tool result survive JSON without losing anything.
+//
+// The harness refuses a tool result that cannot be serialised losslessly, and it refuses the
+// WHOLE call: one `undefined` deep inside a payload drops the answer the caller waited for. That
+// is how a directory entry without a `size` field took down `gh_repo_tree`, and how the same
+// class of defect took down two tools of another plugin.
+//
+// This module is the single place that decides what a result may contain. It is applied to every
+// tool result in one wrapper, so no individual tool has to remember the rule.
+
+const MAX_DEPTH = 40
+
+/**
+ * Return a value that serialises identically in every JSON implementation:
+ * - `undefined` is dropped from objects and becomes `null` inside arrays (JSON has no holes);
+ * - `NaN` and the infinities become `null` (they have no JSON form);
+ * - a `Date` becomes its ISO string; a `Map` an object; a `Set` and a typed array an array; a
+ *   `Buffer` a base64 string;
+ * - functions and symbols are dropped — they cannot be sent anywhere;
+ * - a `BigInt` becomes a string (JSON has no integer that large);
+ * - a cycle becomes the string "[circular]" instead of endless recursion.
+ */
+export function lossless(value, depth = 0, seen = new WeakSet()) {
+  if (value === null) return null
+  const type = typeof value
+  if (type === 'string' || type === 'boolean') return value
+  if (type === 'number') return Number.isFinite(value) ? value : null
+  if (type === 'bigint') return value.toString()
+  if (type === 'undefined' || type === 'function' || type === 'symbol') return undefined
+
+  if (depth > MAX_DEPTH) return '[too deep]'
+  if (value instanceof Date) return Number.isFinite(value.getTime()) ? value.toISOString() : null
+  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value)) return value.toString('base64')
+
+  if (typeof value === 'object') {
+    if (seen.has(value)) return '[circular]'
+    seen.add(value)
+
+    if (Array.isArray(value) || ArrayBuffer.isView(value)) {
+      const out = Array.from(value, (item) => {
+        const converted = lossless(item, depth + 1, seen)
+        return converted === undefined ? null : converted
+      })
+      seen.delete(value)
+      return out
+    }
+    if (value instanceof Map) {
+      const out = {}
+      for (const [key, item] of value.entries()) {
+        const converted = lossless(item, depth + 1, seen)
+        if (converted !== undefined) out[String(key)] = converted
+      }
+      seen.delete(value)
+      return out
+    }
+    if (value instanceof Set) {
+      const out = []
+      for (const item of value.values()) {
+        const converted = lossless(item, depth + 1, seen)
+        out.push(converted === undefined ? null : converted)
+      }
+      seen.delete(value)
+      return out
+    }
+
+    const out = {}
+    for (const key of Object.keys(value)) {
+      const converted = lossless(value[key], depth + 1, seen)
+      if (converted !== undefined) out[key] = converted
+    }
+    seen.delete(value)
+    return out
+  }
+
+  return undefined
+}
+
+/**
+ * Whether a value would pass the harness's check. Kept as a separate, tiny predicate so tests can
+ * assert the rule instead of comparing strings.
+ */
+export function isLossless(value) {
+  try {
+    const once = JSON.stringify(value)
+    if (once === undefined) return false
+    return JSON.stringify(lossless(JSON.parse(once))) === once
+  } catch {
+    return false
+  }
+}