@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/fleet/src/install-adl-package.ts

@@ -0,0 +1,178 @@
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  readlinkSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+} from 'node:fs'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+
+// Exported so tests can pin this list against the packages that actually
+// import cross-package by relative path (STATUS.md 12p, finding C1) — a
+// package added to those imports but not here breaks every managed repo's
+// git hooks with "Cannot find module" the next time reconcile projects this
+// payload.
+export const payloadDirectories = ['packages/agent-skills', 'packages/repo-controls', 'packages/agent-hooks', 'packages/azdo']
+const payloadScripts = ['bin/git', 'bin/git-ado']
+const requiredFiles = [
+  'bin/reconcile',
+  'packages/fleet/manifest.json',
+  'packages/agent-skills/dist/index.js',
+  'packages/repo-controls/bin/adl-repo-controls.ts',
+  'packages/agent-hooks/src/log/writer.ts',
+  // repo-controls, fleet and agent-hooks each import THE one Azure DevOps
+  // identity resolver/minter by relative path (`../../azdo/src/lib/...`,
+  // `../../../../azdo/src/lib/...`) rather than as a package dependency, so
+  // this directory must ship as a sibling of theirs under packages/ or every
+  // managed repo's git hooks break with "Cannot find module" the next time
+  // reconcile projects this payload (STATUS.md 12p, finding C1).
+  'packages/azdo/src/lib/agent-identity.ts',
+  'packages/azdo/src/lib/agent-token.ts',
+]
+const managedScriptMarkers = ['# Managed by adl global-tools.', '# Managed by Enact global-tools.']
+
+export interface InstallAdlPackageOptions {
+  packageRoot: string
+  systemRoot?: string
+}
+
+function isPathInside(parent: string, candidate: string): boolean {
+  const pathFromParent = relative(resolve(parent), resolve(candidate))
+  return pathFromParent === '' || (pathFromParent !== '..' && !pathFromParent.startsWith(`..${sep}`) && !isAbsolute(pathFromParent))
+}
+
+function assertPackageRoot(packageRoot: string): string {
+  const root = realpathSync(packageRoot)
+  const rootStat = lstatSync(root)
+  if (!rootStat.isDirectory()) throw new Error(`Adl platform package root is not a directory: ${packageRoot}`)
+
+  for (const relative of [...payloadDirectories, ...payloadScripts, ...requiredFiles]) {
+    const source = join(root, relative)
+    if (!existsSync(source)) throw new Error(`required package payload missing: ${relative}`)
+    const stat = lstatSync(source)
+    if (stat.isSymbolicLink()) throw new Error(`package payload must not be a symlink: ${relative}`)
+    if (payloadDirectories.includes(relative)) {
+      if (!stat.isDirectory()) throw new Error(`package payload must be a directory: ${relative}`)
+      continue
+    }
+    if (!stat.isFile()) throw new Error(`required package file is not a regular file: ${relative}`)
+    if (payloadScripts.includes(relative)) {
+      if ((stat.mode & 0o111) === 0) throw new Error(`package script must be executable: ${relative}`)
+      const firstLines = readFileSync(source, 'utf8').split('\n', 3)
+      if (!managedScriptMarkers.some((marker) => firstLines.includes(marker))) {
+        throw new Error(`package script is missing its managed marker: ${relative}`)
+      }
+    }
+  }
+  return root
+}
+
+function isLegacyManagedDirectory(target: string): boolean {
+  try {
+    return lstatSync(target).isDirectory() && existsSync(join(target, '.adl-managed-repo-dir'))
+  } catch {
+    return false
+  }
+}
+
+function replacePayloadSymlink(source: string, target: string, packageRoot: string): void {
+  mkdirSync(dirname(target), { recursive: true })
+  if (existsSync(target) || lstatExists(target)) {
+    if (lstatExists(target) && lstatSync(target).isSymbolicLink()) {
+      const current = readlinkTarget(target)
+      if (current === source) return
+      if (!isPathInside(dirname(packageRoot), current) && !payloadDirectories.some((relative) => current.endsWith(`/${relative}`))) {
+        throw new Error(`refusing to replace unmanaged payload symlink: ${target}`)
+      }
+    } else if (!isLegacyManagedDirectory(target)) {
+      throw new Error(`refusing to replace unmanaged payload directory: ${target}`)
+    }
+    rmSync(target, { recursive: true, force: true })
+  }
+  symlinkSync(source, target, 'dir')
+}
+
+function lstatExists(path: string): boolean {
+  try {
+    lstatSync(path)
+    return true
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
+    throw error
+  }
+}
+
+function readlinkTarget(path: string): string {
+  return resolve(dirname(path), readlinkSync(path))
+}
+
+function replaceManagedScript(source: string, target: string): void {
+  mkdirSync(dirname(target), { recursive: true })
+  if (lstatExists(target)) {
+    const stat = lstatSync(target)
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+      throw new Error(`refusing to replace unmanaged or symlinked script target: ${target}`)
+    }
+    const old = readFileSync(target, 'utf8')
+    if (!managedScriptMarkers.some((marker) => old.split('\n', 3).includes(marker))) {
+      throw new Error(`refusing to replace unmanaged script target: ${target}`)
+    }
+    if (old === readFileSync(source, 'utf8')) return
+  }
+  const tempDirectory = mkdtempSync(join(dirname(target), '.adl-package-script-'))
+  const temp = join(tempDirectory, 'script')
+  try {
+    copyFileSync(source, temp)
+    chmodSync(temp, 0o755)
+    renameSync(temp, target)
+  } finally {
+    rmSync(tempDirectory, { recursive: true, force: true })
+  }
+}
+
+export function installAdlPackage(options: InstallAdlPackageOptions): void {
+  const packageRoot = assertPackageRoot(options.packageRoot)
+  const systemRoot = resolve(options.systemRoot ?? '/')
+  for (const relative of payloadDirectories) {
+    replacePayloadSymlink(
+      join(packageRoot, relative),
+      join(systemRoot, 'usr/local/libexec/adl', relative.split('/').at(-1)!),
+      packageRoot,
+    )
+  }
+  for (const relative of payloadScripts) {
+    replaceManagedScript(
+      join(packageRoot, relative),
+      join(systemRoot, 'usr/local/bin', relative.split('/').at(-1)!),
+    )
+  }
+}
+
+if (import.meta.main) {
+  const args = process.argv.slice(2)
+  if (args[0] !== 'install') throw new Error('usage: install-adl-package.ts install --package-root PATH [--system-root PATH]')
+  let packageRoot = ''
+  let systemRoot = '/'
+  for (let index = 1; index < args.length; index += 2) {
+    const option = args[index]
+    const value = args[index + 1] ?? ''
+    if (option === '--package-root') packageRoot = value
+    else if (option === '--system-root') systemRoot = value
+    else throw new Error(`unknown option: ${option}`)
+  }
+  if (!packageRoot) throw new Error('missing --package-root')
+  try {
+    installAdlPackage({ packageRoot, systemRoot })
+    console.log(`projected Adl package payload from ${packageRoot}`)
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    process.exitCode = 1
+  }
+}

package/packages/fleet/src/install-embedding-model.ts

@@ -0,0 +1,412 @@
+/**
+ * Global installer for the `adl-embedding` static (Model2Vec) embedding
+ * artifact that `adl hook`'s skill-match hook loads from
+ * `${XDG_CACHE_HOME:-$HOME/.cache}/adl-embedding/model/` (falling back to
+ * BM25 when absent) — see enact-repo-controls-m5's
+ * `src/hooks/user-prompt-submit/vector.ts`, which this script's output must
+ * satisfy exactly: `model.bin`, `tokenizer.json`, `tokenizer_config.json`,
+ * `manifest.json`.
+ *
+ * The build itself (download upstream, prune the vocabulary to the
+ * highest-frequency Latin-script tokens, quantize to int8) is ported
+ * verbatim from enact-m5's own repo-local installer
+ * (`.agents/hooks/user-prompt-submit/install-model.mjs`), which explicitly
+ * does not publish a pre-built release — "the GitHub-release path is
+ * intentionally not used: that release does not exist publicly" — so this
+ * script reproduces the same deterministic transform rather than fetching a
+ * finished artifact.
+ *
+ * Tracking policy: this installer always resolves the *latest* revision of
+ * `spec.source` on HuggingFace at run time (`config.update_policy` for this
+ * fleet is "latest-stable" and nothing about this artifact is pinned) rather
+ * than reading a revision out of the manifest. Every upstream file is
+ * verified against the digest HuggingFace itself publishes for that exact
+ * revision, fetched from the paths-info API alongside the revision lookup:
+ * LFS-tracked files (large binaries such as `model.safetensors`) carry a
+ * `lfs.oid`, which is already a SHA-256 of the file content; ordinary
+ * git-tracked files (small text files such as `tokenizer_config.json`) carry
+ * only a git blob `oid` (SHA-1 of `"blob " + length + "\0" + content`), which
+ * is what a download is checked against when no `lfs` entry is present. A
+ * checksum mismatch on either kind — or a paths-info response missing an
+ * expected file — fails loud; there is no silent fallback to trusting the
+ * bytes because they merely arrived over HTTPS. `revision` is then recorded
+ * in the installed `manifest.json` so the next run can skip the rebuild
+ * (network round-trip to resolve latest + a local file read) instead of
+ * re-downloading and re-verifying multi-hundred-MB files on every six-hour
+ * reconcile just to reach the same answer.
+ *
+ * `manifest.json`'s `source`, `vocab_limit`, and `dim` come from
+ * `packages/fleet/manifest.json` (manager "embedding-model") and are passed in
+ * as `--spec`; they are this artifact's shape, not its provenance, so they
+ * stay manifest-pinned. Provenance (revision, per-file digests) is never
+ * manifest-pinned — it is resolved and verified fresh every run.
+ *
+ * `reconcile` invokes this script as the manifest's administrator via
+ * `sudo -u ... -H`, so `process.env.HOME` is that account's home (root on
+ * Linux) with no extra plumbing needed. `--home` exists purely so tests can
+ * override it.
+ */
+import { createHash } from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+export interface EmbeddingModelSpec {
+  readonly package: string
+  readonly version: string
+  readonly source: string
+  readonly vocab_limit: number
+  readonly dim: number
+}
+
+/** One entry of a HuggingFace `paths-info` response for a single file at a given revision. */
+export interface HfPathInfo {
+  readonly path: string
+  /** Git blob SHA-1 (always present). Verifies non-LFS files. */
+  readonly oid: string
+  /** Present only for LFS-tracked files; `oid` here is a SHA-256 of the file content. */
+  readonly lfs?: { readonly oid: string }
+}
+
+const ARTIFACT_FILE_NAMES = ['model.bin', 'tokenizer.json', 'tokenizer_config.json', 'manifest.json'] as const
+const UPSTREAM_FILE_NAMES = ['model.safetensors', 'tokenizer.json', 'tokenizer_config.json'] as const
+
+/** Same resolver as vector.ts's resolveGlobalArtifactDir, applied to this process's own env (or a test override). */
+export function resolveArtifactDir(env: Readonly<Record<string, string | undefined>>): string {
+  const xdgCacheHome = env.XDG_CACHE_HOME
+  const base = xdgCacheHome && xdgCacheHome.trim() !== '' ? xdgCacheHome : join(requireHome(env), '.cache')
+  return join(base, 'adl-embedding', 'model')
+}
+
+function requireHome(env: Readonly<Record<string, string | undefined>>): string {
+  const home = env.HOME
+  if (!home || home.trim() === '') throw new Error('HOME is not set and XDG_CACHE_HOME is not set')
+  return home
+}
+
+export function sha256(buf: Buffer): string {
+  return createHash('sha256').update(buf).digest('hex')
+}
+
+/** Git's own content hash: sha1("blob " + byteLength + "\0" + content) — the `oid` HuggingFace's API reports for every file, LFS or not. */
+export function gitBlobSha1(buf: Buffer): string {
+  const header = Buffer.from(`blob ${buf.length}\0`, 'utf8')
+  return createHash('sha1').update(Buffer.concat([header, buf])).digest('hex')
+}
+
+/**
+ * Verify a downloaded file against the digest HuggingFace published for it at
+ * the resolved revision. LFS-tracked files are checked by SHA-256
+ * (`pathInfo.lfs.oid`); everything else by git blob SHA-1 (`pathInfo.oid`) —
+ * the only digest HuggingFace publishes for a small, non-LFS text file.
+ * Throws on any mismatch; never silently accepts unverified bytes.
+ */
+export function verifyDownloadAgainstHf(buf: Buffer, pathInfo: HfPathInfo, label: string): void {
+  if (pathInfo.lfs) {
+    const actual = sha256(buf)
+    if (actual !== pathInfo.lfs.oid) {
+      throw new Error(`checksum mismatch for upstream ${label}: expected sha256 ${pathInfo.lfs.oid}, got ${actual}`)
+    }
+    return
+  }
+  const actual = gitBlobSha1(buf)
+  if (actual !== pathInfo.oid) {
+    throw new Error(`checksum mismatch for upstream ${label}: expected git-blob-sha1 ${pathInfo.oid}, got ${actual}`)
+  }
+}
+
+/** Parses a HuggingFace `paths-info` JSON response body into the fields this installer verifies against. */
+export function parsePathsInfoResponse(body: unknown): readonly HfPathInfo[] {
+  if (!Array.isArray(body)) throw new Error('paths-info response was not a JSON array')
+  return body.map((entry) => {
+    const e = entry as { path?: unknown; oid?: unknown; lfs?: { oid?: unknown } }
+    if (typeof e.path !== 'string' || typeof e.oid !== 'string') {
+      throw new Error(`paths-info entry missing path/oid: ${JSON.stringify(entry)}`)
+    }
+    const lfs = e.lfs && typeof e.lfs.oid === 'string' ? { oid: e.lfs.oid } : undefined
+    return lfs ? { path: e.path, oid: e.oid, lfs } : { path: e.path, oid: e.oid }
+  })
+}
+
+/** True only when a previously installed artifact exists, has every expected file, and was built from `revision`. */
+export function isInstalledAtRevision(artifactDir: string, revision: string): boolean {
+  for (const name of ARTIFACT_FILE_NAMES) {
+    if (!existsSync(join(artifactDir, name))) return false
+  }
+  let installedManifest: { revision?: unknown }
+  try {
+    installedManifest = JSON.parse(readFileSync(join(artifactDir, 'manifest.json'), 'utf8')) as { revision?: unknown }
+  } catch {
+    return false
+  }
+  return installedManifest.revision === revision
+}
+
+/** Ids 0 and 1 are [PAD]/[UNK]; keep them, then the top-scoring Latin-script tokens. */
+const LATIN_ONLY = /^[▁ -~À-ɏḀ-ỿ]+$/
+
+export function selectVocabulary(vocab: readonly [string, number][], vocabLimit: number): number[] {
+  const candidates: number[] = []
+  for (let i = 2; i < vocab.length; i++) {
+    const entry = vocab[i]
+    if (entry && LATIN_ONLY.test(entry[0])) candidates.push(i)
+  }
+  candidates.sort((a, b) => (vocab[b] as [string, number])[1] - (vocab[a] as [string, number])[1])
+  return [0, 1, ...candidates.slice(0, Math.max(0, vocabLimit - 2))]
+}
+
+export function quantizeWeights(
+  weights: Float32Array,
+  keep: readonly number[],
+  dim: number,
+): { readonly quant: Int8Array; readonly scales: Float32Array } {
+  const quant = new Int8Array(keep.length * dim)
+  const scales = new Float32Array(keep.length)
+  for (let r = 0; r < keep.length; r++) {
+    const src = (keep[r] as number) * dim
+    let max = 0
+    for (let d = 0; d < dim; d++) {
+      const v = Math.abs(weights[src + d] as number)
+      if (v > max) max = v
+    }
+    const scale = max / 127 || 1
+    scales[r] = scale
+    const dst = r * dim
+    for (let d = 0; d < dim; d++) quant[dst + d] = Math.round((weights[src + d] as number) / scale)
+  }
+  return { quant, scales }
+}
+
+export function encodeModelBin(keep: readonly number[], dim: number, quant: Int8Array, scales: Float32Array): Buffer {
+  const header = Buffer.alloc(16)
+  header.write('CLPEMB', 0, 'latin1')
+  header.writeUInt8(0, 6)
+  header.writeUInt8(1, 7)
+  header.writeUInt32LE(keep.length, 8)
+  header.writeUInt32LE(dim, 12)
+  return Buffer.concat([header, Buffer.from(scales.buffer), Buffer.from(quant.buffer)])
+}
+
+interface SafetensorsEmbeddings {
+  readonly weights: Float32Array
+  readonly rows: number
+}
+
+export function readEmbeddings(path: string, dim: number): SafetensorsEmbeddings {
+  const buf = readFileSync(path)
+  const headerLen = Number(buf.readBigUInt64LE(0))
+  const header = JSON.parse(buf.subarray(8, 8 + headerLen).toString('utf8')) as {
+    embeddings?: { dtype: string; shape: [number, number]; data_offsets: [number, number] }
+  }
+  const tensor = header.embeddings
+  if (!tensor) throw new Error('safetensors file has no "embeddings" tensor')
+  if (tensor.dtype !== 'F32') throw new Error(`expected F32 embeddings, got ${tensor.dtype}`)
+  const [rows, tensorDim] = tensor.shape
+  if (tensorDim !== dim) throw new Error(`expected ${dim} dimensions, got ${tensorDim}`)
+  const [start, end] = tensor.data_offsets
+  const dataStart = 8 + headerLen + start
+  const bytes = buf.subarray(dataStart, dataStart + (end - start))
+  const aligned = Buffer.from(bytes) // guarantee a fresh, aligned backing buffer for the Float32Array view
+  return { weights: new Float32Array(aligned.buffer, aligned.byteOffset, rows * dim), rows }
+}
+
+// ---------------------------------------------------------------------------
+// Network — real implementations, overridable in tests via EmbeddingModelDeps
+// ---------------------------------------------------------------------------
+
+async function httpGetJson(url: string): Promise<unknown> {
+  const res = await fetch(url, { headers: { 'User-Agent': 'adl' } })
+  if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`)
+  return res.json()
+}
+
+async function defaultResolveLatestRevision(source: string): Promise<string> {
+  const body = (await httpGetJson(`https://huggingface.co/api/models/${source}/revision/main`)) as { sha?: unknown }
+  if (typeof body.sha !== 'string' || body.sha.length === 0) {
+    throw new Error(`HuggingFace revision lookup for ${source} did not return a sha`)
+  }
+  return body.sha
+}
+
+async function defaultFetchPathsInfo(source: string, revision: string, paths: readonly string[]): Promise<readonly HfPathInfo[]> {
+  const url = `https://huggingface.co/api/models/${source}/paths-info/${revision}`
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'User-Agent': 'adl' },
+    body: JSON.stringify({ paths, expand: true }),
+  })
+  if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`)
+  return parsePathsInfoResponse(await res.json())
+}
+
+function defaultDownloadFile(url: string, dest: string): void {
+  const result = spawnSync(
+    'curl',
+    ['--proto', '=https', '--proto-redir', '=https', '-fsSL', '--retry', '3', '-o', dest, url],
+    { stdio: ['ignore', 'inherit', 'inherit'] },
+  )
+  if (result.status !== 0) throw new Error(`download failed (curl exit ${result.status}): ${url}`)
+}
+
+export interface EmbeddingModelDeps {
+  readonly resolveLatestRevision: (source: string) => Promise<string>
+  readonly fetchPathsInfo: (source: string, revision: string, paths: readonly string[]) => Promise<readonly HfPathInfo[]>
+  readonly downloadFile: (url: string, dest: string) => void
+}
+
+export const defaultDeps: EmbeddingModelDeps = {
+  resolveLatestRevision: defaultResolveLatestRevision,
+  fetchPathsInfo: defaultFetchPathsInfo,
+  downloadFile: defaultDownloadFile,
+}
+
+function pathInfoFor(paths: readonly HfPathInfo[], name: string): HfPathInfo {
+  const found = paths.find((p) => p.path === name)
+  if (!found) throw new Error(`paths-info response is missing ${name}`)
+  return found
+}
+
+/**
+ * Resolve the latest revision of `spec.source`, skip entirely if the
+ * installed artifact already matches it, otherwise download the three
+ * upstream files (each verified against the digest HuggingFace published for
+ * *this* revision), run the deterministic prune+quantize build, and
+ * atomically install every produced file into `artifactDir`. Nothing under
+ * `artifactDir` is touched until every download has already verified.
+ */
+export async function install(spec: EmbeddingModelSpec, artifactDir: string, deps: EmbeddingModelDeps = defaultDeps): Promise<void> {
+  const revision = await deps.resolveLatestRevision(spec.source)
+
+  if (isInstalledAtRevision(artifactDir, revision)) {
+    console.log(`adl-embedding: already installed and verified at ${artifactDir} (${spec.source}@${revision})`)
+    return
+  }
+
+  const work = mkdtempSync(join(tmpdir(), 'adl-embedding-install-'))
+  try {
+    console.log(`adl-embedding: installing ${spec.package} ${spec.version} (${spec.source}@${revision})`)
+
+    const pathsInfo = await deps.fetchPathsInfo(spec.source, revision, UPSTREAM_FILE_NAMES)
+    const downloadedPaths: Record<string, string> = {}
+    for (const name of UPSTREAM_FILE_NAMES) {
+      const pathInfo = pathInfoFor(pathsInfo, name)
+      const dest = join(work, name)
+      const url = `https://huggingface.co/${spec.source}/resolve/${revision}/${name}`
+      console.log(`  fetch   ${name}`)
+      deps.downloadFile(url, dest)
+      verifyDownloadAgainstHf(readFileSync(dest), pathInfo, name)
+      downloadedPaths[name] = dest
+    }
+
+    const tokenizer = JSON.parse(readFileSync(downloadedPaths['tokenizer.json'] as string, 'utf8')) as {
+      model: { type: string; vocab: [string, number][] }
+    }
+    if (tokenizer.model.type !== 'Unigram') throw new Error(`expected a Unigram tokenizer, got ${tokenizer.model.type}`)
+    const vocab = tokenizer.model.vocab
+    const { weights, rows } = readEmbeddings(downloadedPaths['model.safetensors'] as string, spec.dim)
+    if (rows !== vocab.length) throw new Error(`vocab/row mismatch: ${vocab.length} tokens vs ${rows} rows`)
+
+    const keep = selectVocabulary(vocab, spec.vocab_limit)
+    console.log(`  upstream: ${rows} rows x ${spec.dim} dims; keeping ${keep.length} tokens`)
+    const { quant, scales } = quantizeWeights(weights, keep, spec.dim)
+
+    const outDir = join(work, 'out')
+    mkdirSync(outDir, { recursive: true })
+    const modelBin = encodeModelBin(keep, spec.dim, quant, scales)
+    writeFileSync(join(outDir, 'model.bin'), modelBin)
+    console.log(`  built   model.bin  sha256=${sha256(modelBin)}`)
+
+    const prunedTokenizer = { ...tokenizer, model: { ...tokenizer.model, vocab: keep.map((i) => vocab[i]) } }
+    writeFileSync(join(outDir, 'tokenizer.json'), JSON.stringify(prunedTokenizer))
+    writeFileSync(join(outDir, 'tokenizer_config.json'), readFileSync(downloadedPaths['tokenizer_config.json'] as string))
+    writeFileSync(
+      join(outDir, 'manifest.json'),
+      `${JSON.stringify(
+        {
+          source: spec.source,
+          revision,
+          sourceLicense: 'MIT',
+          rows: keep.length,
+          dim: spec.dim,
+          quantization: 'int8-per-row',
+          vocabLimit: spec.vocab_limit,
+        },
+        null,
+        '\t',
+      )}\n`,
+    )
+
+    mkdirSync(artifactDir, { recursive: true })
+    for (const name of ARTIFACT_FILE_NAMES) {
+      // Atomic per-file install: write next to the target, then rename —
+      // never a window where a partially written file sits at the real path.
+      const staged = `${join(artifactDir, name)}.tmp-${process.pid}`
+      writeFileSync(staged, readFileSync(join(outDir, name)))
+      renameSync(staged, join(artifactDir, name))
+    }
+    console.log(`adl-embedding: installed and verified at ${artifactDir} (${spec.source}@${revision})`)
+  } finally {
+    rmSync(work, { recursive: true, force: true })
+  }
+}
+
+export function uninstall(artifactDir: string): void {
+  if (!existsSync(artifactDir)) {
+    console.log(`adl-embedding: nothing to remove at ${artifactDir}`)
+    return
+  }
+  rmSync(artifactDir, { recursive: true, force: true })
+  console.log(`adl-embedding: removed ${artifactDir}`)
+}
+
+function usage(): never {
+  throw new Error('usage: install-embedding-model <install|check|uninstall> --spec JSON [--home ABSOLUTE_PATH]')
+}
+
+export async function main(argv: readonly string[]): Promise<void> {
+  const mode = argv[0]
+  if (mode !== 'install' && mode !== 'check' && mode !== 'uninstall') usage()
+
+  let specJson = ''
+  let home: string | undefined
+  for (let index = 1; index < argv.length; index += 1) {
+    const argument = argv[index]
+    if (argument === '--spec') specJson = argv[++index] ?? ''
+    else if (argument === '--home') home = argv[++index]
+    else usage()
+  }
+
+  const env: Record<string, string | undefined> = { ...process.env }
+  if (home !== undefined) env.HOME = home
+  const artifactDir = resolveArtifactDir(env)
+
+  if (mode === 'uninstall') {
+    uninstall(artifactDir)
+    return
+  }
+
+  if (specJson.length === 0) usage()
+  const spec = JSON.parse(specJson) as EmbeddingModelSpec
+
+  if (mode === 'check') {
+    const revision = await defaultDeps.resolveLatestRevision(spec.source)
+    const ok = isInstalledAtRevision(artifactDir, revision)
+    console.log(
+      ok
+        ? `adl-embedding: installed and verified at ${artifactDir} (${spec.source}@${revision})`
+        : `adl-embedding: NOT installed at latest revision ${revision} at ${artifactDir}`,
+    )
+    process.exitCode = ok ? 0 : 1
+    return
+  }
+
+  await install(spec, artifactDir)
+}
+
+if (import.meta.main) {
+  main(process.argv.slice(2)).catch((cause) => {
+    console.error(`install-embedding-model: ${cause instanceof Error ? cause.message : String(cause)}`)
+    process.exitCode = 1
+  })
+}