dsh-memu-memory 1.1.1 → 1.1.3

package/scripts/check-doc-drift.mjs

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+// Anti-drift gates for documented counts and tracked test files.
+//
+// Gate 1 - RPC method count:
+//   Count the top-level case labels inside the dispatch() function in lib/rpc.js.
+//   Other switch statements in that file must not contribute. Then require every
+//   <!-- rpc-method-count: N --> marker in README*.md, AGENTS.md and docs/*.md
+//   to exist and carry that same measured value.
+//
+// Gate 2 - test tracking:
+//   Compare every tests/**/*.mjs on disk with git ls-files tests/. Files present
+//   on disk but not in the index are untracked or never staged, and fail.
+//   Only active in a development Git checkout; an npm package install directory
+//   has no .git, so the gate is explicitly skipped / not applicable there.
+//
+// Gate 3 - loader and stub completeness:
+//   tests/loader-register.mjs, tests/loader.mjs and the three host stubs must
+//   exist and be non-empty; tests/ must contain at least one *.test.mjs.
+//
+// Run directly with: node scripts/check-doc-drift.mjs [--root <dir>]
+
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const DEFAULT_ROOT = path.resolve(import.meta.dirname, '..')
+const RPC_FILE = 'lib/rpc.js'
+const MARKER_RE = /<!--\s*rpc-method-count\s*:\s*(\d+)\s*-->/g
+const REQUIRED_FILES = [
+  'tests/loader-register.mjs',
+  'tests/loader.mjs',
+  'tests/stubs/dsh-llm.js',
+  'tests/stubs/dsh-session.js',
+  'tests/stubs/dsh-tools.js',
+]
+
+const outcome = (label, status, summary, details = []) => ({ label, status, summary, details })
+const firstLine = (value) => String(value || '').trim().split(/\r?\n/)[0] || ''
+
+// Extract only the top-level case labels of async function dispatch(...).
+// The scanner walks the function body with quote/comment awareness and records
+// case labels at depth 2: function body depth 1, dispatch switch body depth 2.
+// Nested switches inside a case body sit deeper and are ignored.
+export function extractDispatchMethods(source) {
+  const head = /\basync\s+function\s+dispatch\s*\(/.exec(source)
+  if (!head) throw new Error('async function dispatch(...) not found in ' + RPC_FILE)
+  let index = head.index + head[0].length
+  let parens = 1
+  let quote = null
+  for (; index < source.length; index++) {
+    const ch = source[index]
+    if (quote) {
+      if (ch === '\\') { index++; continue }
+      if (ch === quote) quote = null
+      continue
+    }
+    if (ch === "'" || ch === '"' || ch === '\u0060') { quote = ch; continue }
+    if (ch === '(') parens++
+    else if (ch === ')') { parens--; if (parens === 0) { index++; break } }
+  }
+  while (index < source.length && /\s/.test(source[index])) index++
+  if (source[index] !== '{') throw new Error('dispatch() parameter list is not followed by a body')
+  const names = []
+  let depth = 0
+  quote = null
+  for (; index < source.length; index++) {
+    const ch = source[index]
+    if (quote) {
+      if (ch === '\\') { index++; continue }
+      if (ch === quote) quote = null
+      continue
+    }
+    if (ch === '/' && source[index + 1] === '/') {
+      const newline = source.indexOf('\n', index)
+      index = newline < 0 ? source.length : newline
+      continue
+    }
+    if (ch === '/' && source[index + 1] === '*') {
+      const close = source.indexOf('*/', index + 2)
+      index = close < 0 ? source.length : close + 1
+      continue
+    }
+    if (ch === "'" || ch === '"' || ch === '\u0060') { quote = ch; continue }
+    if (ch === '{') { depth++; continue }
+    if (ch === '}') {
+      depth--
+      if (depth === 0) break
+      continue
+    }
+    if (depth !== 2 || !source.startsWith('case', index)) continue
+    const before = source[index - 1]
+    const after = source[index + 4]
+    if ((before && /[\w$]/.test(before)) || (after && /[\w$]/.test(after))) continue
+    const label = /^case\s+(['"])([^'"]+)\1\s*:/.exec(source.slice(index))
+    if (!label) {
+      const line = source.slice(0, index).split('\n').length
+      throw new Error('unparseable case label at ' + RPC_FILE + ':' + line)
+    }
+    names.push(label[2])
+  }
+  const unique = [...new Set(names)]
+  if (unique.length === 0) throw new Error('no top-level case labels found in dispatch() (' + RPC_FILE + ')')
+  return unique
+}
+
+// Root README*.md, AGENTS.md and docs/*.md are the only docs allowed to carry
+// the marker. Keeping the list narrow means a stray marker in another doc
+// cannot silently satisfy the gate.
+export function docFiles(root) {
+  const files = []
+  let rootEntries = []
+  try {
+    rootEntries = fs.readdirSync(root)
+  } catch {
+    rootEntries = []
+  }
+  for (const name of rootEntries) {
+    if (/^README.*\.md$/.test(name)) files.push(name)
+  }
+  if (rootEntries.includes('AGENTS.md')) files.push('AGENTS.md')
+  try {
+    const docsDir = path.join(root, 'docs')
+    for (const name of fs.readdirSync(docsDir)) {
+      if (name.endsWith('.md')) files.push('docs/' + name)
+    }
+  } catch {
+    // No docs/ directory is not this gate's failure; the marker scan below
+    // simply has fewer files and will report the missing marker.
+  }
+  return [...new Set(files)].sort()
+}
+
+export function collectTestFiles(root) {
+  const testsDir = path.join(root, 'tests')
+  try {
+    if (!fs.statSync(testsDir).isDirectory()) return null
+  } catch {
+    return null
+  }
+  const out = []
+  const walk = (dir, rel) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const nextRel = rel + '/' + entry.name
+      const abs = path.join(dir, entry.name)
+      if (entry.isDirectory()) walk(abs, nextRel)
+      else if (entry.isFile() && entry.name.endsWith('.mjs')) out.push(nextRel)
+    }
+  }
+  walk(testsDir, 'tests')
+  return out.sort()
+}
+
+export function checkRpcMethodCount(root) {
+  const label = 'rpc-method-count'
+  let methods = []
+  try {
+    methods = extractDispatchMethods(fs.readFileSync(path.join(root, RPC_FILE), 'utf8'))
+  } catch (error) {
+    return outcome(label, 'fail', 'cannot measure the RPC dispatch surface', [
+      String(error && error.message ? error.message : error),
+      'expected: parse ' + RPC_FILE + ' dispatch()',
+    ])
+  }
+  const expected = methods.length
+  const docs = docFiles(root)
+  const markers = []
+  for (const rel of docs) {
+    let text = ''
+    try {
+      text = fs.readFileSync(path.join(root, rel), 'utf8')
+    } catch (error) {
+      return outcome(label, 'fail', 'cannot read doc file ' + rel, [firstLine(error.message)])
+    }
+    for (const match of text.matchAll(new RegExp(MARKER_RE.source, 'g'))) {
+      markers.push({ file: rel, value: Number(match[1]) })
+    }
+  }
+  if (markers.length === 0) {
+    return outcome(label, 'fail', 'no rpc-method-count marker found', [
+      'marker: (none)',
+      'expected: ' + expected + ' methods (dispatch in ' + RPC_FILE + ')',
+      'scanned: ' + (docs.length > 0 ? docs.join(', ') : '(no docs)'),
+      'add the marker with the measured value; doc content is owned by the W2 docs work',
+    ])
+  }
+  const values = [...new Set(markers.map((entry) => entry.value))]
+  if (values.length === 1 && values[0] === expected) {
+    const docCount = new Set(markers.map((entry) => entry.file)).size
+    return outcome(label, 'ok', markers.length + ' marker(s) in ' + docCount + ' doc(s) agree on ' + expected + ' RPC methods', [])
+  }
+  const details = ['expected: ' + expected + ' methods (dispatch in ' + RPC_FILE + ')']
+  for (const entry of markers) {
+    details.push(entry.file + ': marker ' + entry.value + (entry.value === expected ? ' (agrees)' : ' != expected ' + expected))
+  }
+  if (values.length > 1) details.push('markers disagree: ' + values.join(', ') + '; all markers must share one value')
+  return outcome(label, 'fail', 'rpc-method-count marker drift', details)
+}
+
+function gitWorkTree(root) {
+  const dotGit = path.join(root, '.git')
+  let present = false
+  try {
+    const stat = fs.statSync(dotGit)
+    present = stat.isDirectory() || stat.isFile()
+  } catch {
+    present = false
+  }
+  if (!present) return { active: false, reason: 'no .git at repository root' }
+  try {
+    const output = execFileSync('git', ['rev-parse', '--is-inside-work-tree'], {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim()
+    if (output !== 'true') return { active: false, reason: 'git rev-parse --is-inside-work-tree returned ' + (output || '(empty)') }
+    return { active: true }
+  } catch (error) {
+    return { active: false, reason: 'git rev-parse --is-inside-work-tree failed: ' + firstLine(error.stderr || error.message) }
+  }
+}
+
+export function checkTestTracking(root) {
+  const label = 'test-tracking'
+  const git = gitWorkTree(root)
+  if (!git.active) {
+    return outcome(label, 'skipped', git.reason + ' - skipped, not applicable (npm package install directory)', [
+      'test tracking is enforced only in a development Git checkout',
+      'this location is neither passed nor failed; stage the tests before they can be checked',
+    ])
+  }
+  const disk = collectTestFiles(root)
+  if (disk === null) return outcome(label, 'fail', 'tests/ directory not found', ['cannot compare disk tests with git ls-files tests/'])
+  let tracked = new Set()
+  try {
+    const raw = execFileSync('git', ['ls-files', '-z', '--', 'tests/'], {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      maxBuffer: 16 * 1024 * 1024,
+    })
+    tracked = new Set(raw.split('\0').filter(Boolean).map((file) => file.split('\\').join('/')))
+  } catch (error) {
+    return outcome(label, 'fail', 'git ls-files tests/ failed', [firstLine(error.stderr || error.message)])
+  }
+  const untracked = disk.filter((file) => !tracked.has(file))
+  if (untracked.length > 0) {
+    const details = untracked.map((file) => 'untracked/unstaged: ' + file)
+    details.push('git ls-files tests/ reports ' + tracked.size + ' tracked file(s)')
+    return outcome(label, 'fail', untracked.length + ' of ' + disk.length + ' test .mjs file(s) are not tracked or staged', details)
+  }
+  return outcome(label, 'ok', disk.length + ' test .mjs file(s) tracked and staged', [])
+}
+
+export function checkLoaderStubs(root) {
+  const label = 'loader-stubs'
+  const problems = []
+  for (const rel of REQUIRED_FILES) {
+    const abs = path.join(root, rel)
+    let stat = null
+    try {
+      stat = fs.statSync(abs)
+    } catch {
+      stat = null
+    }
+    if (!stat) {
+      problems.push(rel + ': missing')
+      continue
+    }
+    if (!stat.isFile()) {
+      problems.push(rel + ': not a regular file')
+      continue
+    }
+    let text = ''
+    try {
+      text = fs.readFileSync(abs, 'utf8')
+    } catch (error) {
+      problems.push(rel + ': unreadable (' + firstLine(error.message) + ')')
+      continue
+    }
+    if (text.trim().length === 0) problems.push(rel + ': empty (' + stat.size + ' bytes)')
+  }
+  const tests = collectTestFiles(root)
+  if (tests === null) problems.push('tests/: directory missing')
+  else if (!tests.some((file) => file.endsWith('.test.mjs'))) problems.push('tests/: no *.test.mjs file')
+  if (problems.length > 0) return outcome(label, 'fail', 'loader/stub completeness check failed', problems)
+  const testCount = tests.filter((file) => file.endsWith('.test.mjs')).length
+  return outcome(label, 'ok', REQUIRED_FILES.length + ' required loader/stub file(s) present; ' + testCount + ' *.test.mjs file(s)', [])
+}
+
+export function runChecks(root = DEFAULT_ROOT) {
+  const checks = [
+    ['rpc-method-count', checkRpcMethodCount],
+    ['test-tracking', checkTestTracking],
+    ['loader-stubs', checkLoaderStubs],
+  ]
+  return checks.map(([label, run]) => {
+    try {
+      return run(root)
+    } catch (error) {
+      return outcome(label, 'fail', 'check crashed', [firstLine(error && error.stack ? error.stack : error)])
+    }
+  })
+}
+
+export function formatCheck(check) {
+  if (check.status === 'ok') return 'ok   ' + check.label + ': ' + check.summary
+  if (check.status === 'skipped') return 'skip ' + check.label + ': ' + check.summary
+  const lines = ['FAIL ' + check.label + ': ' + check.summary]
+  for (const detail of check.details || []) lines.push('     ' + detail)
+  return lines.join('\n')
+}
+
+function main() {
+  const argv = process.argv.slice(2)
+  let root = DEFAULT_ROOT
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--help' || arg === '-h') {
+      console.log('usage: node scripts/check-doc-drift.mjs [--root <dir>]')
+      return
+    }
+    if (arg === '--root') {
+      const value = argv[++i]
+      if (!value) {
+        console.error('--root requires a directory')
+        process.exitCode = 2
+        return
+      }
+      root = path.resolve(value)
+      continue
+    }
+    if (arg.startsWith('--root=')) {
+      root = path.resolve(arg.slice('--root='.length))
+      continue
+    }
+    console.error('unknown argument: ' + arg)
+    process.exitCode = 2
+    return
+  }
+  const checks = runChecks(root)
+  for (const check of checks) console.log(formatCheck(check))
+  const failed = checks.filter((check) => check.status === 'fail')
+  if (failed.length > 0) {
+    console.log('\n' + failed.length + ' doc-drift check(s) failed: ' + failed.map((check) => check.label).join(', '))
+    process.exitCode = 1
+    return
+  }
+  console.log('\nall doc-drift checks passed')
+}
+
+const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (invokedDirectly) main()

package/scripts/diagnose-bindings.mjs

@@ -0,0 +1,176 @@
+#! /usr/bin/env node
+// Read-only binding lifecycle CLI (W9).
+//
+// It prints a diagnostic report and refuses every write: no delete, no unbind, no library
+// creation, no state rewrite, no timestamp bump. The only side effect is stdout/stderr.
+//
+// Exit codes are about the report, never about "fixing" anything:
+//   0  report produced, nothing filed for inspection
+//   1  report produced, inspection candidates present (a to-do list for a human, not a queue)
+//   2  usage error (unknown flag, unreadable --now)
+//   3  no report: state.json is missing, corrupt or unreadable
+
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { diagnoseBindings, defaultStateFile, INSPECTION_DAYS, SCHEMA } from '../lib/binding-diagnostics.js'
+
+export const EXIT = Object.freeze({ clean: 0, candidates: 1, usage: 2, unreadable: 3 })
+
+const USAGE = [
+  'usage: node scripts/diagnose-bindings.mjs [options]',
+  '',
+  'Read-only binding lifecycle report. Reads state.json once, never writes, never creates',
+  'a directory, never unbinds or deletes anything, and re-hashes the file afterwards so the',
+  'report can prove it left the bytes and the mtime alone.',
+  '',
+  'options:',
+  '  --state <file>   state.json to read (default: the plugin data directory)',
+  '  --json           print the machine-readable report instead of the summary',
+  '  --redact         pseudonymise session ids (titles and paths are never printed either way)',
+  '  --now <iso>      evaluate the ' + INSPECTION_DAYS + '-day inspection threshold at an instant, for tests',
+  '  --help, -h       print this text',
+  '',
+  'exit codes:',
+  '  0  report produced, no inspection candidates',
+  '  1  report produced, inspection candidates present (inspection only, nothing was changed)',
+  '  2  usage error',
+  '  3  state.json missing, corrupt or unreadable — nothing was created or repaired',
+  '',
+  'The ' + INSPECTION_DAYS + '-day mark is a threshold for looking, never an age at which a binding, a',
+  'library or a message is dropped. There is no --delete, --gc or --unbind flag, by design.',
+].join('\n')
+
+function usage (message) {
+  if (message) process.stderr.write('error: ' + message + '\n\n')
+  process.stderr.write(USAGE + '\n')
+  process.exitCode = EXIT.usage
+}
+
+export function parseArgs (argv) {
+  const options = { json: false, redact: false, stateFile: null, now: null, help: false }
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--help' || arg === '-h') { options.help = true; continue }
+    if (arg === '--json') { options.json = true; continue }
+    if (arg === '--redact') { options.redact = true; continue }
+    if (arg === '--state' || arg.startsWith('--state=')) {
+      const value = arg === '--state' ? argv[++index] : arg.slice('--state='.length)
+      if (!value) return { error: '--state requires a file' }
+      options.stateFile = path.resolve(value)
+      continue
+    }
+    if (arg === '--now' || arg.startsWith('--now=')) {
+      const value = arg === '--now' ? argv[++index] : arg.slice('--now='.length)
+      const parsed = Date.parse(String(value || ''))
+      if (!value || !Number.isFinite(parsed)) return { error: '--now requires an ISO timestamp' }
+      options.now = parsed
+      continue
+    }
+    return { error: 'unknown argument: ' + arg }
+  }
+  return { options }
+}
+
+function short (hash) {
+  return typeof hash === 'string' && hash.length > 12 ? hash.slice(0, 12) + '…' : String(hash || '-')
+}
+
+function render (report) {
+  const lines = []
+  lines.push('dsh-memu-memory binding diagnostic — read-only (' + SCHEMA + ')')
+  lines.push('state: ' + report.state.file)
+  if (report.state.status === 'ok') {
+    lines.push('       ' + report.state.bytes + ' bytes, sha256 ' + short(report.state.sha256) + ', mtime ' + new Date(report.state.mtimeMs).toISOString())
+  } else {
+    lines.push('       status: ' + report.state.status)
+  }
+  lines.push('generated: ' + report.generatedAt)
+  if (report.readOnlyProof) {
+    lines.push('read-only proof: ' + (report.readOnlyProof.unchanged
+      ? 'bytes and mtime identical before/after (' + short(report.readOnlyProof.sha256Before) + ')'
+      : 'CHANGED during the report — investigate, this tool does not write'))
+  }
+  if (!report.analysis) {
+    lines.push('')
+    lines.push('no analysis: the state file could not be read. Nothing was created, renamed or repaired.')
+    for (const unknown of report.unknowns) lines.push('  unknown ' + unknown.code + ': ' + unknown.detail)
+    return lines.join('\n')
+  }
+  const summary = report.analysis.summary
+  lines.push('')
+  lines.push('bindings: ' + summary.bindings + ' persistent binding(s)')
+  lines.push('host: ' + summary.host.status + ' / ' + summary.host.source + ' / ' + summary.host.sessions + ' session(s)' + (summary.host.complete ? ' (complete)' : ' (incomplete — absence is not inferred)'))
+  lines.push('candidates: ' + summary.candidates.total + (summary.candidates.total ? ' — ' + Object.entries(summary.candidates.byKind).map(([kind, count]) => kind + ' ' + count).join(', ') : ''))
+  lines.push('unfinished: ' + summary.unfinished.pendingMessages + ' pending message(s) in ' + summary.unfinished.pendingSessions + ' session(s), ' +
+    summary.unfinished.reinjectPending + ' reinject, ' + summary.unfinished.sleepRetryDue + ' sleep retry due, ' + summary.unfinished.sessionGone + ' session gone')
+  lines.push('switches: ' + summary.switches.libraryDisabled + ' library off, ' + summary.switches.globalDisabled + ' global off, ' +
+    summary.switches.folderBlockedLibrary + ' folder-blocked library, ' + summary.switches.folderBlockedGlobal + ' folder-blocked global')
+  lines.push('libraries: ' + summary.libraries.bound + ' bound, ' + summary.libraries.enabledButUnbound + ' enabled-but-unbound, ' +
+    summary.libraries.missing + ' missing, ' + summary.libraries.archived + ' archived')
+  if (report.analysis.candidates.length > 0) {
+    lines.push('')
+    lines.push('inspection candidates (a prompt to look, never a deletion queue):')
+    for (const candidate of report.analysis.candidates.slice(0, 20)) {
+      lines.push('  ' + candidate.kind.padEnd(28) + ' ' + candidate.sessionId)
+    }
+    if (report.analysis.candidates.length > 20) lines.push('  … ' + (report.analysis.candidates.length - 20) + ' more (use --json)')
+  }
+  if (report.unknowns.length > 0) {
+    lines.push('')
+    lines.push('unknowns (kept, not assumed away):')
+    for (const unknown of report.unknowns) lines.push('  ' + unknown.code + ': ' + unknown.detail)
+  }
+  lines.push('')
+  const runtime = report.analysis.runtime || { status: 'unknown', layers: [] }
+  const runtimeLabel = runtime.status === 'provided'
+    ? 'runtime layers supplied in-process: '
+    : 'runtime layers not readable from this process: '
+  lines.push(runtimeLabel + runtime.layers.length + ' declared (' + runtime.status + ')')
+  lines.push('threshold: ' + INSPECTION_DAYS + ' days marks what to inspect; it never triggers deletion. No gc, no unbind, no write.')
+  return lines.join('\n')
+}
+
+function main () {
+  const parsed = parseArgs(process.argv.slice(2))
+  if (parsed.error) {
+    usage(parsed.error)
+    return
+  }
+  const options = parsed.options
+  if (options.help) {
+    process.stdout.write(USAGE + '\n')
+    return
+  }
+  let report
+  try {
+    report = diagnoseBindings({
+      stateFile: options.stateFile || defaultStateFile(),
+      now: options.now === null ? undefined : options.now,
+      redactIds: options.redact,
+    })
+  } catch (error) {
+    process.stderr.write('error: the diagnostic failed without touching the state file: ' + String((error && error.message) || error) + '\n')
+    process.exitCode = EXIT.unreadable
+    return
+  }
+  try {
+    if (options.json) {
+      process.stdout.write(JSON.stringify(report, null, 2) + '\n')
+    } else {
+      process.stdout.write(render(report) + '\n')
+    }
+  } catch (error) {
+    // A rendering bug must not masquerade as exit 1 ("candidates present"): no report was produced.
+    process.stderr.write('error: the report could not be rendered: ' + String((error && error.message) || error) + '\n')
+    process.exitCode = EXIT.unreadable
+    return
+  }
+  if (!report.analysis) {
+    process.exitCode = EXIT.unreadable
+    return
+  }
+  process.exitCode = report.analysis.candidates.length > 0 ? EXIT.candidates : EXIT.clean
+}
+
+const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (invokedDirectly) main()

package/scripts/local-runtime-install.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+// 受管本地向量运行时的可复现安装/核验脚本（§14.13）。
+//
+//   node scripts/local-runtime-install.mjs                        # 只读：打印制品计划、当前状态、已装摘要
+//   node scripts/local-runtime-install.mjs --download             # 显式联网安装（等同用户在设置里点确认）
+//   node scripts/local-runtime-install.mjs --download --target <dir> --id <modelId> --platform win32-x64
+//   node scripts/local-runtime-install.mjs --shallow              # 复用判定只比字节数，不重算 sha256
+//   node scripts/local-runtime-install.mjs --download --cache <dir> # 用离线缓存里的同名 tarball 替代联网
+//
+// 边界：只写 --target（默认仓库内 .tmp-* 临时目录）；不写 DSH_MEMU_HOME、不写 active profile、
+// 不读不写真实记忆库；不装 Ollama，也不需要 DSH_MEMU_EMBED_RUNTIME_DIR。
+// --cache 只改「字节从哪来」：大小与 sha256 仍按 catalog pin 逐项校验。
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createEmbeddingRuntimeInstaller, embeddingRuntimePlatform } from '../lib/embedding-runtime.js'
+import { getEmbeddingCatalog, getEmbeddingModel } from '../lib/embedding-catalog.js'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const REPO = path.resolve(HERE, '..')
+
+const argv = process.argv.slice(2)
+const flag = name => argv.includes('--' + name)
+const option = name => {
+  const index = argv.indexOf('--' + name)
+  return index >= 0 ? argv[index + 1] : undefined
+}
+
+const target = path.resolve(option('target') || path.join(REPO, '.tmp-local-vector-20261030', 'runtime-managed'))
+const platform = option('platform') || embeddingRuntimePlatform()
+const modelId = option('id') || null
+const download = flag('download')
+const deep = !flag('shallow')
+const cache = option('cache') ? path.resolve(option('cache')) : null
+
+// 离线缓存：只替换字节来源，不跳过任何校验。tarball 文件名允许几种常见写法。
+function cacheLookup() {
+  const entry = modelId ? getEmbeddingModel(modelId) : getEmbeddingCatalog().find(item => item.availability === 'available')
+  const artifacts = Array.isArray(entry?.runtime?.artifacts) ? entry.runtime.artifacts : []
+  const map = new Map()
+  for (const artifact of artifacts) {
+    const names = []
+    const base = String(artifact.url || '').split('/').pop()
+    if (base) names.push(base)
+    const pkg = String(artifact.name || '')
+    if (pkg) {
+      names.push(pkg + '.tgz', pkg.replace(/[\\/]+/g, '__') + '.tgz', pkg.split('/').pop() + '.tgz')
+      names.push(pkg.replace(/[^A-Za-z0-9._-]+/g, '-') + '.tgz')
+    }
+    for (const name of names) {
+      const candidate = path.join(cache, name)
+      if (fs.existsSync(candidate)) { map.set(artifact.url, candidate); break }
+    }
+  }
+  return map
+}
+
+const cacheFiles = cache ? cacheLookup() : null
+const fetchImpl = cacheFiles
+  ? async url => {
+    const file = cacheFiles.get(url)
+    if (!file) throw new Error('offline cache ' + cache + ' has no tarball for ' + url)
+    const bytes = fs.readFileSync(file)
+    return new Response(bytes, { status: 200, headers: { 'content-length': String(bytes.length) } })
+  }
+  : undefined
+
+const installer = createEmbeddingRuntimeInstaller({
+  root: target,
+  platform,
+  fetchImpl,
+  logger: {
+    info: message => console.error('info ' + message),
+    warn: message => console.error('warn ' + message),
+  },
+})
+
+const summarize = status => ({
+  status: status.status,
+  ready: status.ready,
+  platform: status.platform,
+  key: status.key,
+  path: status.path,
+  engine: status.engine,
+  version: status.version,
+  abi: status.abi,
+  root: status.root,
+  verifiedPlatforms: status.verifiedPlatforms,
+  artifacts: Array.isArray(status.artifacts)
+    ? status.artifacts.map(item => ({ name: item.name, version: item.version, bytes: item.bytes, sha256: item.sha256, license: item.license }))
+    : null,
+  installedAt: status.installedAt ?? null,
+  verifiedAt: status.verifiedAt ?? null,
+  smoke: status.smoke ?? null,
+  checks: Array.isArray(status.checks) ? status.checks : null,
+  progress: status.progress ?? null,
+  inspect: status.inspect ?? null,
+  error: status.error ?? null,
+})
+
+try {
+  const before = installer.getStatus({ deep, modelId })
+  console.log(JSON.stringify({ phase: 'before', deep, download, ...summarize(before) }, null, 2))
+  if (!before.ready && !download) {
+    console.error('\n未安装。加 --download 才会联网下载并安装（有明确确认语义）；本脚本不会自动下载。')
+    process.exit(0)
+  }
+  if (download) {
+    const started = Date.now()
+    const result = await installer.ensure({ modelId, confirmed: true })
+    console.log(JSON.stringify({
+      phase: 'install',
+      elapsedMs: Date.now() - started,
+      status: result.status,
+      ready: result.ready,
+      reused: result.reused,
+      key: result.key,
+      platform: result.platform,
+      path: result.path,
+      engine: result.engine,
+      version: result.version,
+      abi: result.abi,
+      installedAt: result.installedAt,
+      verifiedAt: result.verifiedAt,
+      checks: result.checks,
+      smoke: result.smoke,
+      artifacts: result.artifacts,
+    }, null, 2))
+    const after = installer.getStatus({ deep: true, modelId })
+    console.log(JSON.stringify({ phase: 'after', ...summarize(after) }, null, 2))
+    if (!after.ready) throw new Error('installer reported installed but the runtime is not reusable')
+  }
+} catch (error) {
+  const code = String(error?.code || 'LOCAL_VECTOR_RUNTIME_SCRIPT_FAILED')
+  console.error('FAIL ' + code + ': ' + String(error?.message || error))
+  if (Array.isArray(error?.errors)) for (const item of error.errors) console.error('  - ' + JSON.stringify(item))
+  if (error?.inspect) console.error('  inspect: ' + error.inspect)
+  process.exit(1)
+} finally {
+  installer.dispose()
+}