skill-family-engineering-kit 0.1.2 → 0.2.0

package/src/cli.mjs

@@ -2,7 +2,9 @@
 import { realpathSync } from "node:fs";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import { readFileContained, resolveContained } from "skill-family-harness-node";
 import { bundledProfilesRoot } from "./licensing.mjs";
+import { checkReportAction, renderReportAction } from "./report.mjs";
 import {
   COMMAND_SIDE_EFFECTS,
   KIT_EXIT_CODES,
@@ -12,14 +14,23 @@ import {
   unknownCommandError,
   invalidParamsError,
   mutationModeError,
+  describeHost,
+  probeHost,
+  buildHostAdapter,
+  materializeHostBuild,
+  planHost,
+  refuseHostApply,
 } from "./index.mjs";
 
 /**
  * skill-family-engineering-kit CLI.
  *
- * Exactly four top-level commands exist; there is no fifth. Exit codes are
- * stable: 0 = ok/clean, 1 = findings (check), 2 = rejected/usage/mechanism
- * error. Every refusal prints its registered SFC code and stable kind.
+ * Exactly four top-level commands exist; there is no fifth. The report layer
+ * (FND-ADR-005) hangs under two of them as positional sub-actions —
+ * `projection report` (render) and `check report` (graded diagnosis) — not as
+ * a fifth command. Exit codes are stable: 0 = ok/clean, 1 = findings (check),
+ * 2 = rejected/usage/mechanism error. Every refusal prints its registered
+ * SFC code and stable kind.
  */
 
 const HELP_TEXT = `skill-family-engineering-kit —— 构建期工程工具包（恰好四个顶层命令）
@@ -37,15 +48,22 @@ const HELP_TEXT = `skill-family-engineering-kit —— 构建期工程工具包
   projection   投影受管生成物。
                副作用: 只写 manifest 授权且被目标声明为受管的路径；
                未授权路径、手写文件与越界路径一律拒绝（拒绝时零写入）。
+               报告子动作: projection report 将调用方提交的 report-model 确定性渲染为
+               中立 Markdown（FND-ADR-005）；默认只写 stdout，给定 --out/
+               --binding 时只写这两个显式且被 --root 收容的路径（原子写）。
   check        契约/漂移/闭包/版本/文档事实/Git 前置状态诊断。
                副作用: 无 —— 只诊断、绝不自动修复，git 仅只读探测。
+               报告子动作: check report 对一份已渲染报告做分级诊断：
+               硬失败（SFC3001/3002/3003）计为发现（退出码 1）；
+               风格告警只报告、绝不阻塞机器正确的报告。
 
 全局选项:
   --root <dir>  目标工作区根目录（默认当前目录）
   --help, -h    显示本帮助或单个命令的帮助
 
 退出码: 0 成功/无发现；1 check 有发现；2 拒绝/用法/机制错误。
-错误码复用 contracts 的 SFC* 体系（SFC2002/SFC2003/SFC2004 + 稳定 details.kind）。
+错误码复用 contracts 的 SFC* 体系（SFC2002/SFC2003/SFC2004 + 稳定 details.kind；
+报告层硬失败使用 SFC3001/SFC3002/SFC3003）。
 禁止项: git init/commit/push/tag、发布、删除、远端写入；不存在第五个顶层命令。
 `;
 
@@ -61,6 +79,10 @@ function commandHelp(command) {
       "  --licensing-profile <id> 许可证 Profile id（默认 registry 第一个变体）",
       "  --licensing-variant <id> 多变体 Profile 的必选变体 id",
       "  --profiles-root <dir> 许可证 Profile 根目录",
+      "",
+      "宿主构建: skill-family-kit scaffold host-build --root <workspace> --host <id>",
+      "  --path-category <id> --input <relpath> --out <relpath> [--hosts-root <dir>]",
+      "  将完整 source closure 逐字节写入 sibling staging，验证后一次 rename；目标必须不存在。",
     ],
     "adopt-plan": [
       "选项:",
@@ -72,6 +94,11 @@ function commandHelp(command) {
       "  --profiles-root <dir> 许可证 Profile 根目录",
       "  --no-git-spawn        禁用只读 git status 探测，仅用文件系统事实",
       "",
+      "只读宿主子动作: host-describe | host-probe | host-plan | host-apply",
+      "  host-probe 默认不执行进程；仅 --allow-host-spawn + --host-executable <绝对路径> 可启用受审计版本向量；",
+      "  host-plan 必须显式提供 --build-manifest/--probe-facts，绝不隐式探测；",
+      "  host-apply 在本阶段稳定拒绝，且不会产生占位文件或临时目录。",
+      "",
       "  迁移闭环（FND-070）: 只读读取目标仓 skill-family.migration.json",
       "  （旧实现退出清单 + 临时例外）；例外缺 owner/reason/deadline/",
       "  migrationTarget 任一字段即计为冲突；到期例外不自动续期；",
@@ -81,6 +108,13 @@ function commandHelp(command) {
       "选项:",
       "  --root <dir>          目标工作区（默认当前目录）",
       "  --manifest <relpath>  投影 manifest 相对路径（默认 skill-family.projection.json）",
+      "",
+      "报告子动作: skill-family-kit projection report [options]",
+      "  --model <relpath>     经 Contracts 验证的 report-model JSON（必填）",
+      "  --result <relpath>    机器结果 JSON（必填，仅用于摘要和错误绑定核对）",
+      "  --out <relpath>       报告 Markdown 输出路径；缺省时 Markdown 只写 stdout",
+      "  --binding <relpath>   同时写出 report-binding JSON（model/result/report 三摘要）",
+      "  确定性: 同一 report-model 反复渲染字节一致；Harness 不推导状态、不补造事实。",
     ],
     check: [
       "选项:",
@@ -88,6 +122,14 @@ function commandHelp(command) {
       "  --only <class>        只运行一个诊断类: contracts|drift|closure|version|docs|git|identity",
       "  --profiles-root <dir> 许可证 Profile 根目录",
       "  --no-git-spawn        禁用只读 git status 探测，仅用文件系统事实",
+      "",
+      "报告子动作: skill-family-kit check report [options]",
+      "  --report <relpath>    已渲染报告 Markdown（必填，只读）",
+      "  --model <relpath>     对应 report-model JSON（必填，只读）",
+      "  --result <relpath>    对应机器结果 JSON（必填，只读；核对 digest/errors）",
+      "  --binding <relpath>   可选 report-binding JSON；摘要过期即 SFC3001",
+      "  分级: 硬失败（SFC3001/3002/3003）计为发现，退出码 1；",
+      "  风格告警（超长句/重复段/翻译腔/未解释术语）只报告、绝不改变判定。",
     ],
   };
   return [
@@ -172,8 +214,134 @@ const COMMAND_SPECS = {
       "--no-git-spawn": { key: "noGitSpawn", value: false },
     },
   },
+  "projection report": {
+    flags: {
+      "--root": { key: "root", value: true },
+      "--model": { key: "model", value: true },
+      "--result": { key: "result", value: true },
+      "--out": { key: "out", value: true },
+      "--binding": { key: "binding", value: true },
+    },
+  },
+  "check report": {
+    flags: {
+      "--root": { key: "root", value: true },
+      "--report": { key: "report", value: true },
+      "--model": { key: "model", value: true },
+      "--result": { key: "result", value: true },
+      "--binding": { key: "binding", value: true },
+    },
+  },
+  "scaffold host-build": {
+    flags: {
+      "--root": { key: "root", value: true },
+      "--host": { key: "hostId", value: true },
+      "--path-category": { key: "pathCategoryId", value: true },
+      "--input": { key: "input", value: true },
+      "--out": { key: "out", value: true },
+      "--hosts-root": { key: "hostsRoot", value: true },
+    },
+  },
+  "adopt-plan host-describe": {
+    flags: { "--host": { key: "hostId", value: true }, "--hosts-root": { key: "hostsRoot", value: true } },
+  },
+  "adopt-plan host-probe": {
+    flags: {
+      "--host": { key: "hostId", value: true },
+      "--hosts-root": { key: "hostsRoot", value: true },
+      "--allow-host-spawn": { key: "allowHostSpawn", value: false },
+      "--host-executable": { key: "hostExecutable", value: true },
+    },
+  },
+  "adopt-plan host-plan": {
+    flags: {
+      "--root": { key: "root", value: true },
+      "--host": { key: "hostId", value: true },
+      "--path-category": { key: "pathCategoryId", value: true },
+      "--build-manifest": { key: "buildManifest", value: true },
+      "--probe-facts": { key: "probeFacts", value: true },
+      "--hosts-root": { key: "hostsRoot", value: true },
+    },
+  },
+  "adopt-plan host-apply": { flags: {} },
 };
 
+async function readJson(root, relPath, label) {
+  if (!relPath) throw invalidParamsError(`${label} is required`);
+  try {
+    return JSON.parse((await readFileContained(root, relPath)).toString("utf8"));
+  } catch (cause) {
+    if (cause?.code?.startsWith?.("SFC")) throw cause;
+    throw invalidParamsError(`${label} must name valid JSON contained in --root`);
+  }
+}
+
+async function runHostSubAction(command, action, rest) {
+  const specName = `${command} ${action}`;
+  try {
+    if (action === "host-apply") refuseHostApply();
+    const spec = COMMAND_SPECS[specName];
+    const options = parseOptions(rest, { command: specName, flags: spec.flags });
+    const hostsRoot = options.hostsRoot;
+    let output;
+    if (action === "host-describe") {
+      output = await describeHost({ hostId: options.hostId, hostsRoot });
+    } else if (action === "host-probe") {
+      output = await probeHost({ hostId: options.hostId, hostsRoot, allowSpawn: options.allowHostSpawn === true, executable: options.hostExecutable });
+    } else if (action === "host-build") {
+      const root = options.root ?? ".";
+      const input = await readJson(root, options.input, "--input");
+      const build = await buildHostAdapter({ hostId: options.hostId, pathCategoryId: options.pathCategoryId, input, hostsRoot });
+      if (build.status === "built") {
+        if (!options.out) throw invalidParamsError("--out is required");
+        const targetRoot = await resolveContained(root, options.out);
+        await materializeHostBuild({ targetRoot, build });
+      }
+      output = build.status === "built" ? { status: "built", manifest: build.manifest, outputRoot: options.out } : build;
+    } else if (action === "host-plan") {
+      const root = options.root ?? ".";
+      const buildManifest = await readJson(root, options.buildManifest, "--build-manifest");
+      const probeDocument = await readJson(root, options.probeFacts, "--probe-facts");
+      const probeFacts = Array.isArray(probeDocument) ? probeDocument : probeDocument.facts;
+      output = await planHost({ hostId: options.hostId, pathCategoryId: options.pathCategoryId, buildManifest, probeFacts, hostsRoot });
+    }
+    process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+    return KIT_EXIT_CODES.ok;
+  } catch (error) {
+    printError(error);
+    return KIT_EXIT_CODES.rejected;
+  }
+}
+
+async function runReportSubAction(command, rest) {
+  const specName = `${command} report`;
+  try {
+    const options = parseOptions(rest, { command: specName, flags: COMMAND_SPECS[specName].flags });
+    if (options.help) {
+      process.stdout.write(`${commandHelp(command)}\n`);
+      return KIT_EXIT_CODES.ok;
+    }
+    const action = command === "projection" ? renderReportAction : checkReportAction;
+    const { status, output } = await action({
+      root: options.root,
+      model: options.model,
+      result: options.result,
+      report: options.report,
+      out: options.out,
+      binding: options.binding,
+    });
+    if (output !== undefined) {
+      process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+    }
+    if (status === "ok") return KIT_EXIT_CODES.ok;
+    if (status === "findings") return KIT_EXIT_CODES.findings;
+    return KIT_EXIT_CODES.rejected;
+  } catch (error) {
+    printError(error);
+    return KIT_EXIT_CODES.rejected;
+  }
+}
+
 export async function cliMain(argv) {
   if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
     process.stdout.write(HELP_TEXT);
@@ -185,6 +353,19 @@ export async function cliMain(argv) {
     return KIT_EXIT_CODES.rejected;
   }
 
+  // Positional report sub-actions (FND-ADR-005): `projection report` renders,
+  // `check report` diagnoses. They hang under existing commands; the
+  // four-command vocabulary and runCommand stay untouched.
+  if ((command === "projection" || command === "check") && argv[1] === "report") {
+    return runReportSubAction(command, argv.slice(2));
+  }
+  if (command === "scaffold" && argv[1] === "host-build") {
+    return runHostSubAction(command, "host-build", argv.slice(2));
+  }
+  if (command === "adopt-plan" && ["host-describe", "host-probe", "host-plan", "host-apply"].includes(argv[1])) {
+    return runHostSubAction(command, argv[1], argv.slice(2));
+  }
+
   try {
     const options = parseOptions(argv.slice(1), { command, flags: COMMAND_SPECS[command].flags });
     if (options.help) {

package/src/core-check.mjs

@@ -0,0 +1,223 @@
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+import { KIT_ERROR_KINDS } from "./errors.mjs";
+import { CHECK_CLASSES, runChecks } from "./check.mjs";
+import {
+  IDENTITY_RECORD_PATH,
+  MANAGED_LOCK_PATH,
+  PROJECT_MANIFEST_PATH,
+} from "./skeleton.mjs";
+import {
+  listTargetEntries,
+  loadTargetFacts,
+  matchAnyGitignorePattern,
+  matchAnyGlob,
+  resolveTargetRoot,
+} from "./workspace.mjs";
+
+/**
+ * runCoreCheck — the single shared production entry of the closed-world
+ * project check (C2).
+ *
+ * The generated `scripts/check-core.mjs` entrypoints of scaffolded projects
+ * ONLY import this function: safe file-tree enumeration, lstat/symlink/FIFO
+ * and special-entry rejection, file-registry classification (managed /
+ * handwritten / artifact closed world), declaration path containment, the
+ * seven check classes, and the stable finding/exit mapping all live here and
+ * nowhere else. No generated string may re-derive a recursive walk, an lstat
+ * classification, a glob match, or a local closed-world algorithm.
+ *
+ * Stages (all read-only; never opens a file before it is lstat-classified):
+ *   1. declaration containment — escaping managed declarations (absolute
+ *      paths, `..` segments) are reported lexically and never touch the fs;
+ *   2. managed preflight — lstat only: missing / symlink / non-regular
+ *      managed paths fail closed before anything could read them;
+ *   3. tree enumeration — every symlink and special entry fails closed;
+ *      every regular file must belong to the registered closed world
+ *      (managed, handwritten, artifact, or a tracked tool lock);
+ *   4. the seven check classes through runChecks — skipped whenever an
+ *      unsafe path (symlink/special at a managed or class-read path) would
+ *      be opened by them: FIFOs must never be read (they block), symlinks
+ *      must never be followed.
+ *
+ * Exit mapping: 0 clean; 2 when any finding carries a security kind
+ * (CORE_CHECK_SECURITY_KINDS, including the harness containment kinds that
+ * can surface through escaping lock entries); 1 otherwise.
+ */
+
+/** Finding kinds that always map to the security exit code 2. */
+export const CORE_CHECK_SECURITY_KINDS = Object.freeze([
+  // Kit kinds of this entry.
+  KIT_ERROR_KINDS.SYMLINK_AT_MANAGED_PATH,
+  KIT_ERROR_KINDS.NOT_A_REGULAR_FILE,
+  KIT_ERROR_KINDS.SYMLINK_ENTRY,
+  KIT_ERROR_KINDS.SPECIAL_ENTRY,
+  KIT_ERROR_KINDS.UNCONTAINED_DECLARATION,
+  // Stable harness containment kinds that surface through drift findings when
+  // a lock entry tries to escape the target (reported, never followed).
+  "absolute-path",
+  "windows-drive-path",
+  "windows-path",
+  "unc-path",
+  "path-traversal",
+  "symlink-escape",
+  "realpath-escape",
+  "invalid-path",
+]);
+
+const CORE_CLASS = "core";
+
+/**
+ * Paths the seven check classes open by name. They take part in the unsafe
+ * read-set even when they are not declared managed (README.md is handwritten
+ * in the skeleton), so a symlink/FIFO there can never hang or escape a read.
+ */
+const CLASS_READ_PATHS = Object.freeze([
+  "README.md",
+  "package.json",
+  PROJECT_MANIFEST_PATH,
+  MANAGED_LOCK_PATH,
+  IDENTITY_RECORD_PATH,
+  "identity-record.json",
+]);
+
+/** Lexical containment of a managed declaration; never touches the fs. */
+export function isContainedDeclaration(rel) {
+  if (typeof rel !== "string" || rel.length === 0) return false;
+  if (rel.startsWith("/")) return false;
+  if (rel.split("/").includes("..")) return false;
+  return true;
+}
+
+/**
+ * Runs the unified closed-world check over one target.
+ * Options: { root, allowGitSpawn, profilesRoot }.
+ * Returns { kind, ok, exitCode, findings, classes, unsafeReadPaths }.
+ * Never writes anywhere.
+ */
+export async function runCoreCheck({ root, allowGitSpawn = true, profilesRoot } = {}) {
+  const rootAbs = await resolveTargetRoot(root ?? ".");
+  const facts = await loadTargetFacts(rootAbs);
+  const findings = [];
+  const push = (kind, message, extra) =>
+    findings.push({ class: CORE_CLASS, kind, code: "SFC2004", message, ...(extra ?? {}) });
+
+  // ---- Stage 1: declaration containment (purely lexical) -----------------
+  const declarations = [...facts.managedSet].sort();
+  const containedDeclarations = [];
+  for (const rel of declarations) {
+    if (isContainedDeclaration(rel)) {
+      containedDeclarations.push(rel);
+    } else {
+      push(
+        KIT_ERROR_KINDS.UNCONTAINED_DECLARATION,
+        `managed declaration escapes the target root (absolute path or '..' segment): ${rel}`,
+        { path: rel },
+      );
+    }
+  }
+
+  // ---- Stage 2: managed preflight (lstat only, never open/read) ----------
+  const unsafeReadPaths = new Set();
+  for (const rel of containedDeclarations) {
+    let st;
+    try {
+      st = await lstat(path.join(rootAbs, rel));
+    } catch {
+      push(
+        KIT_ERROR_KINDS.MANAGED_FILE_MISSING,
+        `managed file declared in the registry/manifest/lock does not exist: ${rel}`,
+        { path: rel },
+      );
+      continue;
+    }
+    if (st.isSymbolicLink()) {
+      push(KIT_ERROR_KINDS.SYMLINK_AT_MANAGED_PATH, `managed path is a symbolic link: ${rel}`, { path: rel });
+      unsafeReadPaths.add(rel);
+    } else if (!st.isFile()) {
+      push(
+        KIT_ERROR_KINDS.NOT_A_REGULAR_FILE,
+        `managed path is not a regular file (FIFO/socket/device/directory): ${rel}`,
+        { path: rel },
+      );
+      unsafeReadPaths.add(rel);
+    }
+  }
+
+  // ---- Stage 3: safe tree enumeration + closed-world classification ------
+  const entries = await listTargetEntries(rootAbs);
+  for (const entry of entries) {
+    if (entry.kind === "directory" || entry.kind === "directory-opaque") continue;
+    if (entry.kind === "symlink") {
+      // Symlinks are never classified by content patterns: unregistered ones
+      // fail closed; managed ones were already reported by the preflight.
+      if (!facts.managedSet.has(entry.path)) {
+        push(
+          KIT_ERROR_KINDS.SYMLINK_ENTRY,
+          `symbolic link is outside the registered closed world (managed/handwritten/artifact): ${entry.path}`,
+          { path: entry.path },
+        );
+      }
+      if (facts.managedSet.has(entry.path) || CLASS_READ_PATHS.includes(entry.path)) {
+        unsafeReadPaths.add(entry.path);
+      }
+      continue;
+    }
+    if (entry.kind === "special") {
+      if (!facts.managedSet.has(entry.path)) {
+        push(
+          KIT_ERROR_KINDS.SPECIAL_ENTRY,
+          `special entry (FIFO/socket/device) is outside the registered closed world: ${entry.path}`,
+          { path: entry.path },
+        );
+      }
+      if (facts.managedSet.has(entry.path) || CLASS_READ_PATHS.includes(entry.path)) {
+        unsafeReadPaths.add(entry.path);
+      }
+      continue;
+    }
+    // Regular files must belong to exactly one registered class. Managed
+    // bytes are verified by the drift class, never re-derived here.
+    if (facts.managedSet.has(entry.path)) continue;
+    if (matchAnyGlob(facts.handwrittenPatterns, entry.path)) continue;
+    if (matchAnyGitignorePattern(facts.artifactPatterns, entry.path)) continue;
+    if (facts.trackedToolLocks.includes(entry.path)) continue;
+    push(
+      KIT_ERROR_KINDS.UNREGISTERED_FILE,
+      `regular file is not registered in the closed world (managed/handwritten/artifact): ${entry.path}`,
+      { path: entry.path },
+    );
+  }
+
+  // ---- Stage 4: the seven check classes through the shared entry ---------
+  let classReport = null;
+  if (unsafeReadPaths.size === 0) {
+    classReport = await runChecks({ root: rootAbs, allowGitSpawn, profilesRoot });
+    findings.push(...classReport.findings);
+  }
+
+  let exitCode = 0;
+  if (findings.length > 0) {
+    const securityKinds = new Set(CORE_CHECK_SECURITY_KINDS);
+    exitCode = findings.some((f) => securityKinds.has(f.kind)) ? 2 : 1;
+  }
+  if (classReport && classReport.mechanism) exitCode = 2;
+
+  return {
+    kind: "skill-family.core-check-report",
+    schemaVersion: 1,
+    target: { root: ".", entryCount: entries.length },
+    ok: findings.length === 0,
+    exitCode,
+    findings,
+    classes:
+      classReport?.classes ??
+      CHECK_CLASSES.map((name) => ({ name, selected: false, completed: false, findings: 0 })),
+    classChecksSkipped:
+      unsafeReadPaths.size > 0
+        ? { reason: "unsafe read-set (symlink/special at a managed or class-read path)", paths: [...unsafeReadPaths].sort() }
+        : null,
+    policy:
+      "core check is diagnosis only: it enumerates with lstat, never opens an unclassified entry, never follows symlinks, and never writes",
+  };
+}

package/src/errors.mjs

@@ -48,9 +48,12 @@ export const KIT_ERROR_KINDS = Object.freeze({
   // check / shared
   CONTRACTS_MISSING: "contracts-missing",
   CONTRACT_PARSE_FAILED: "contract-parse-failed",
+  DOCUMENT_INCOMPLETE: "document-incomplete",
+  CHECK_CLASS_FAILED: "check-class-failed",
   MANAGED_FILE_MISSING: "managed-file-missing",
   MANAGED_FILE_DRIFT: "managed-file-drift",
   SYMLINK_AT_MANAGED_PATH: "symlink-at-managed-path",
+  NOT_A_REGULAR_FILE: "not-a-regular-file",
   CLOSURE_INPUT_MISSING: "closure-input-missing",
   CONTRACTS_VERSION_MISMATCH: "contracts-version-mismatch",
   README_MISSING: "readme-missing",
@@ -59,6 +62,19 @@ export const KIT_ERROR_KINDS = Object.freeze({
   GIT_NO_COMMITS: "git-no-commits",
   GIT_DIRTY: "git-dirty",
   MUTATION_MODE_REQUESTED: "mutation-mode-requested",
+  // core check: the single shared closed-world entry (C2)
+  UNREGISTERED_FILE: "unregistered-file",
+  SYMLINK_ENTRY: "symlink-entry",
+  SPECIAL_ENTRY: "special-entry",
+  UNCONTAINED_DECLARATION: "uncontained-declaration",
+  // report sub-actions (projection report / check report, FND-ADR-005)
+  REPORT_INPUT_MISSING: "report-input-missing",
+  REPORT_PATH_CONFLICT: "report-path-conflict",
+  REPORT_WRITE_FAILED: "report-write-failed",
+  // read-only host integration slice
+  HOST_CONTRACT_INVALID: "host-contract-invalid",
+  HOST_PROBE_FAILED: "host-probe-failed",
+  HOST_BUILD_FAILED: "host-build-failed",
 });
 
 /** Error carrying one frozen SFC code plus a stable kit kind in details. */

package/src/host-drivers.mjs

@@ -0,0 +1,24 @@
+import path from "node:path";
+import { probeVersionVector } from "skill-family-harness-node";
+
+const CAPABILITIES = Object.freeze(["cli", "version", "payload", "registry", "discover", "enabled", "reload", "smoke", "uninstall"]);
+const DRIVERS = Object.freeze({
+  "claude-version-v1": Object.freeze({ executableBasename: "claude", argv: Object.freeze(["--version"]) }),
+  "codex-version-v1": Object.freeze({ executableBasename: "codex", argv: Object.freeze(["--version"]) }),
+});
+
+/**
+ * Selects one audited host-specific driver vector. The generic process and
+ * four-state classification mechanism lives in Harness.
+ */
+export async function probeTrustedVersionDriver({ hostId, driverId, capabilities = CAPABILITIES, executable, allowSpawn = false, timeoutMs = 5000, runner } = {}) {
+  const driver = DRIVERS[driverId];
+  if (!driver) throw new TypeError(`unknown frozen host driver: ${String(driverId)}`);
+  if (allowSpawn && path.basename(executable ?? "") !== driver.executableBasename) {
+    throw new TypeError(`driver ${driverId} requires an explicit ${driver.executableBasename} executable`);
+  }
+  return probeVersionVector({ hostId, capabilities, executable, argv: driver.argv, allowSpawn, timeoutMs, runner });
+}
+
+export const HOST_CAPABILITIES = CAPABILITIES;
+export const HOST_DRIVER_IDS = Object.freeze(Object.keys(DRIVERS));

package/src/host-profiles.mjs

@@ -0,0 +1,51 @@
+import { validateDocument } from "skill-family-contracts";
+import { readFileContained } from "skill-family-harness-node";
+import { invalidParamsError, kitError, KIT_ERROR_KINDS } from "./errors.mjs";
+
+const HOST_DESCRIPTOR_SCHEMA_ID = "https://contracts.skill-family.example/v1/host-descriptor.json";
+const HOST_REGISTRY_SCHEMA_ID = "https://contracts.skill-family.example/v1/host-registry.json";
+const HOST_ID_PATTERN = /^[a-z][a-z0-9-]{1,63}$/;
+
+function validateRegistered(document, schemaId, message) {
+  const result = validateDocument(document, { schemaId, dialect: "2020-12", policy: "strict" });
+  if (!result.valid) throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, message, { errors: result.errors });
+  return result.data;
+}
+
+function assertRegistrySemantics(registry) {
+  return registry;
+}
+
+export async function loadHostRegistry({ hostsRoot, registry } = {}) {
+  if (registry !== undefined) return Object.freeze(structuredClone(assertRegistrySemantics(validateRegistered(registry, HOST_REGISTRY_SCHEMA_ID, "host registry fails its registered contract"))));
+  if (!hostsRoot) throw invalidParamsError("loadHostRegistry requires an explicit hostsRoot or injected registry");
+  let document;
+  try {
+    document = JSON.parse((await readFileContained(hostsRoot, "registry.json")).toString("utf8"));
+  } catch (cause) {
+    if (cause?.code?.startsWith?.("SFC")) throw cause;
+    throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, "host registry cannot be read or parsed", { causeKind: cause?.details?.kind ?? "unknown" });
+  }
+  return Object.freeze(structuredClone(assertRegistrySemantics(validateRegistered(document, HOST_REGISTRY_SCHEMA_ID, "host registry fails its registered contract"))));
+}
+
+export async function describeHost({ hostId, hostsRoot, registry } = {}) {
+  if (!HOST_ID_PATTERN.test(hostId ?? "")) throw invalidParamsError("describeHost requires a valid hostId");
+  const loaded = await loadHostRegistry({ hostsRoot, registry });
+  if (!loaded.hosts.includes(hostId)) throw invalidParamsError(`unknown host: ${hostId}`, { hostId });
+  if (!hostsRoot) throw invalidParamsError("host descriptor resolution requires an explicit hostsRoot");
+  let document;
+  try {
+    document = JSON.parse((await readFileContained(hostsRoot, `${hostId}/host-descriptor.json`)).toString("utf8"));
+  } catch (cause) {
+    if (cause?.code?.startsWith?.("SFC")) throw cause;
+    throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, "host descriptor cannot be read or parsed", { hostId, causeKind: cause?.details?.kind ?? "unknown" });
+  }
+  const descriptor = validateRegistered(document, HOST_DESCRIPTOR_SCHEMA_ID, "host descriptor fails its registered contract");
+  if (descriptor.hostId !== hostId) throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, "host descriptor hostId does not match its registry entry", { hostId });
+  const categoryIds = descriptor.pathCategories.map((category) => category.id);
+  if (new Set(categoryIds).size !== categoryIds.length) throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, "host descriptor has duplicate path category ids", { hostId });
+  return Object.freeze(structuredClone(descriptor));
+}
+
+export { HOST_DESCRIPTOR_SCHEMA_ID, HOST_REGISTRY_SCHEMA_ID };