@litfamily/lithermes 1.0.0

package/src/lib/modelConfig.js

@@ -0,0 +1,431 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { writeFileAtomic } = require("./files");
+const { OPENAI_PROVIDER, RESPONSES_MODE, classifyHostVersion,
+  exactHostVersion, parseBoundary, sourceHash } = require("./modelConfigBoundary");
+const {
+  ASTRA_MODEL,
+  MANAGED_PROVIDER_MODELS,
+  applyManagedRoute,
+  customChildTransportReason,
+  inspectEffectiveRouteSafety,
+  inspectLeadRoute,
+  inspectManagedRoute,
+  inspectOrdinaryWorkerRoute,
+  managedRequest,
+  unavailableReviewerRoutes,
+  unavailableTuiRouteVisibility,
+} = require("./modelRoutePolicy");
+
+const MODELS = new Set(["gpt-6-astra", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"]);
+
+// The route every "configured" verdict is measured against: explicit installer
+// options win; otherwise the document's own route when it is a catalog route;
+// otherwise today's shipped default.
+function expectedRoute(options = {}, document = null) {
+  const explicit = ["provider", "model", "effort", "childProvider", "childModel", "childEffort"]
+    .some((key) => options[key] !== undefined && options[key] !== "");
+  if (explicit) return managedRequest(options);
+  if (document) {
+    try {
+      return managedRequest({
+        childEffort: document.getIn(["delegation", "reasoning_effort"]),
+        childModel: document.getIn(["delegation", "model"]),
+        childProvider: document.getIn(["delegation", "provider"]),
+        effort: document.getIn(["agent", "reasoning_effort"]),
+        model: document.getIn(["model", "default"]),
+        provider: document.getIn(["model", "provider"]),
+      });
+    } catch {
+      // not a catalog route; measure against the shipped default
+    }
+  }
+  return managedRequest();
+}
+const SAFE_CONTEXT_LENGTH = 372000;
+const SAFE_COMPRESSION_THRESHOLD = 0.9;
+const SAFE_AUTO_COMPACTION_LIMIT = SAFE_CONTEXT_LENGTH * SAFE_COMPRESSION_THRESHOLD;
+const MANAGED_SAMPLING_KEYS = ["temperature", "top_p", "top_logprobs"];
+
+function hasValue(document, path) {
+  return document.getIn(path, true) !== undefined;
+}
+
+function isManagedAstraRoute(provider, model) {
+  return provider === OPENAI_PROVIDER && model === ASTRA_MODEL;
+}
+
+function inspectManagedAstraSampling(document, targetRoute = null, targetWrite = false) {
+  const parentProvider = targetWrite ? targetRoute?.provider : document.getIn(["model", "provider"]);
+  const parentModel = targetWrite ? targetRoute?.model : document.getIn(["model", "default"]);
+  const parentAstra = isManagedAstraRoute(parentProvider, parentModel);
+  const configuredChildProvider = targetWrite
+    ? targetRoute?.childProvider
+    : document.getIn(["delegation", "provider"]) || parentProvider;
+  const configuredChildModel = targetWrite
+    ? targetRoute?.childModel
+    : document.getIn(["delegation", "model"]);
+  const childModel = configuredChildModel === undefined || configuredChildModel === null || configuredChildModel === ""
+    ? parentModel
+    : configuredChildModel;
+  const childAstra = isManagedAstraRoute(configuredChildProvider, childModel);
+  const childTransport = customChildTransportReason(document);
+  const sections = [];
+  if (parentAstra) sections.push("model", "agent");
+  if (childAstra && !childTransport) sections.push("delegation");
+  for (const section of sections) {
+    for (const key of MANAGED_SAMPLING_KEYS) {
+      if (hasValue(document, [section, key])) {
+        const route = section === "delegation" ? "global_child" : "parent";
+        return {
+          status: "blocked",
+          code: "LITHERMES_UNSAFE_MODEL_SAMPLING",
+          route,
+          observedSource: `${section}.${key}`,
+          reason: `managed Astra ${route} route contains unsupported sampling field ${section}.${key}; remove it before selecting Astra`,
+        };
+      }
+    }
+  }
+  return parentAstra || childAstra
+    ? {
+      status: "safe",
+      reason: "managed Astra route has no temperature, top_p, or top_logprobs field",
+      observedSource: "managed Astra model/agent/delegation config fields",
+    }
+    : {
+      status: "not_applicable",
+      reason: "no effective managed Astra parent or global-child route",
+      observedSource: "model.provider/default and delegation provider/model config",
+    };
+}
+
+function fallback(reason, classification = { class: "malformed_unknown", originalDispatchId: null }, extra = {}) {
+  return {
+    action: "fallback",
+    backupAllowed: false,
+    capabilities: unavailableCapabilities(reason),
+    classification,
+    fallbackCommand: "hermes model",
+    reason,
+    text: null,
+    ...extra,
+  };
+}
+
+function capability(status, reason, observedSource, extra = {}) {
+  return { status, reason, observedSource, ...extra };
+}
+
+function unavailableCapabilities(reason) {
+  const observedSource = "Hermes host/config validation";
+  return {
+    autoCompaction: capability("unavailable", reason, observedSource),
+    concurrency: capability("unavailable", reason, observedSource),
+    delegationRoute: capability("unavailable", reason, observedSource),
+    leadRoute: capability("unavailable", reason, observedSource),
+    modelSafety: capability("unavailable", reason, observedSource),
+    ordinaryWorkerRoute: capability("unavailable", reason, observedSource),
+    recursion: capability("unavailable", reason, observedSource),
+    reviewerRoutes: capability("unavailable", reason, observedSource),
+    runtime: capability("unavailable", reason, observedSource),
+    tuiRouteVisibility: capability("unavailable", reason, observedSource),
+  };
+}
+
+function safeOriginalDispatchId(dispatch) {
+  if (typeof dispatch !== "string" || !/^[A-Za-z0-9._:/-]{1,128}$/.test(dispatch)) return null;
+  return dispatch;
+}
+
+function classificationFromDocument(document, fresh) {
+  if (fresh) return { class: "fresh", originalDispatchId: null };
+  const provider = document.getIn(["model", "provider"]);
+  const dispatch = document.getIn(["model", "default"]);
+  const originalDispatchId = safeOriginalDispatchId(dispatch);
+  if (dispatch === undefined && provider === undefined) {
+    return { class: "unconfigured", originalDispatchId };
+  }
+  if (typeof dispatch !== "string" || (provider !== undefined && typeof provider !== "string")) {
+    return { class: "malformed_unknown", originalDispatchId };
+  }
+  const safety = inspectEffectiveRouteSafety(document, OPENAI_PROVIDER);
+  if (safety.status === "blocked") {
+    return { class: safety.classificationClass, originalDispatchId };
+  }
+  if (provider === OPENAI_PROVIDER && (dispatch === "gpt-5.4" || dispatch === "gpt-5.5")) {
+    return { class: "managed_legacy", originalDispatchId };
+  }
+  if (provider === OPENAI_PROVIDER && MODELS.has(dispatch)) {
+    return { class: "existing_managed", originalDispatchId };
+  }
+  if (MANAGED_PROVIDER_MODELS[provider]?.has(dispatch)) {
+    return { class: "existing_managed", originalDispatchId };
+  }
+  if (/^gpt-5\.6(?:$|-)/.test(dispatch)) {
+    return { class: "other_gpt56", originalDispatchId };
+  }
+  return { class: "custom", originalDispatchId };
+}
+
+function classifyModelConfig(text, options = {}) {
+  const boundary = parseBoundary(text, options);
+  if (boundary.error) {
+    const safety = boundary.document
+      ? inspectEffectiveRouteSafety(boundary.document, OPENAI_PROVIDER)
+      : null;
+    if (safety?.status === "blocked") {
+      return classificationFromDocument(boundary.document, boundary.fresh);
+    }
+    return { class: "malformed_unknown", originalDispatchId: null };
+  }
+  return classificationFromDocument(boundary.document, boundary.fresh);
+}
+
+function inspectHermesCapabilities(text, options = {}) {
+  const boundary = parseBoundary(text, options);
+  if (boundary.error) {
+    const capabilities = unavailableCapabilities(boundary.error);
+    const safety = boundary.document
+      ? inspectEffectiveRouteSafety(boundary.document, OPENAI_PROVIDER)
+      : null;
+    if (safety?.status === "blocked") capabilities.modelSafety = safety;
+    return capabilities;
+  }
+  const concurrency = boundary.document.getIn(["delegation", "max_concurrent_children"]);
+  const asyncBatches = boundary.document.getIn(["delegation", "max_async_children"]);
+  const spawnDepth = boundary.document.getIn(["delegation", "max_spawn_depth"]);
+  const orchestratorEnabled = boundary.document.getIn(["delegation", "orchestrator_enabled"]);
+  const effectiveAsyncBatches = Number.isInteger(asyncBatches) ? asyncBatches : 3;
+  const effectiveSpawnDepth = Number.isInteger(spawnDepth) ? spawnDepth : 1;
+  const flatDelegation = effectiveSpawnDepth === 1 || orchestratorEnabled === false;
+  const contextLength = boundary.document.getIn(["model", "context_length"]);
+  const compressionThreshold = boundary.document.getIn(["compression", "threshold"]);
+  const provider = boundary.document.getIn(["model", "provider"]);
+  const model = boundary.document.getIn(["model", "default"]);
+  let route;
+  try {
+    route = expectedRoute(options, boundary.document);
+  } catch {
+    // Keep doctor/reporting total for a parsed but unsupported existing route.
+    // The route safety verdict below carries the typed fail-closed result.
+    route = managedRequest();
+  }
+  const routeSafety = inspectEffectiveRouteSafety(boundary.document, OPENAI_PROVIDER);
+  const samplingSafety = inspectManagedAstraSampling(boundary.document);
+  return {
+    autoCompaction: contextLength === SAFE_CONTEXT_LENGTH && compressionThreshold === SAFE_COMPRESSION_THRESHOLD
+      ? {
+        status: "hard",
+        reason: `effective auto-compaction target is ${SAFE_AUTO_COMPACTION_LIMIT} tokens`,
+        observedSource: "model.context_length plus compression.threshold",
+        limit: SAFE_AUTO_COMPACTION_LIMIT,
+      }
+      : {
+        status: "unavailable",
+        reason: "Hermes 0.17.0 exposes ratio-only compression; no exact 650K trigger schema",
+        observedSource: "Hermes compression.threshold ratio-only schema",
+      },
+    concurrency: concurrency === 20
+      ? {
+        status: "hard",
+        reason: "effective synchronous concurrency is configured to 20",
+        observedSource: "delegation.max_concurrent_children",
+        limit: 20,
+        scope: "per-batch",
+        asyncBatchLimit: effectiveAsyncBatches,
+        potentialChildCeiling: 20 * effectiveAsyncBatches,
+      }
+      : {
+        status: "unavailable",
+        reason: `effective synchronous concurrency is ${Number.isInteger(concurrency) ? concurrency : "not configured"}, not 20`,
+        observedSource: "delegation.max_concurrent_children",
+      },
+    delegationRoute: inspectManagedRoute(boundary.document, OPENAI_PROVIDER, route),
+    leadRoute: inspectLeadRoute(boundary.document, OPENAI_PROVIDER, route),
+    modelSafety: samplingSafety.status === "blocked" ? samplingSafety : routeSafety,
+    ordinaryWorkerRoute: inspectOrdinaryWorkerRoute(boundary.document, OPENAI_PROVIDER, route),
+    recursion: flatDelegation
+      ? {
+        status: "hard",
+        reason: effectiveSpawnDepth === 1
+          ? "flat delegation blocks grandchildren at depth 1"
+          : "orchestrator kill switch blocks grandchildren despite a higher configured depth",
+        observedSource: "delegation.max_spawn_depth plus delegation.orchestrator_enabled",
+        limit: effectiveSpawnDepth,
+        flatBy: effectiveSpawnDepth === 1 ? "depth" : "orchestrator-kill-switch",
+      }
+      : {
+        status: "unavailable",
+        reason: `nested delegation is enabled at max_spawn_depth ${effectiveSpawnDepth}`,
+        observedSource: "delegation.max_spawn_depth plus delegation.orchestrator_enabled",
+        limit: effectiveSpawnDepth,
+      },
+    reviewerRoutes: unavailableReviewerRoutes(),
+    runtime: provider === OPENAI_PROVIDER && typeof model === "string"
+      ? {
+        status: "hard",
+        reason: "effective provider uses the verified OpenAI OAuth Responses route",
+        observedSource: "model.provider plus Hermes runtime provider markers",
+        provider: OPENAI_PROVIDER,
+        apiMode: RESPONSES_MODE,
+      }
+      : {
+        status: "unavailable",
+        reason: "effective model provider is not the verified OpenAI OAuth Responses route",
+        observedSource: "model.provider plus Hermes runtime provider markers",
+      },
+    tuiRouteVisibility: unavailableTuiRouteVisibility(),
+  };
+}
+
+function planModelConfig(text, options = {}) {
+  const route = managedRequest(options);
+  const request = {
+    ...route,
+    hostCapabilities: { ...options.hostCapabilities },
+    hostVersion: exactHostVersion(options.hostVersion),
+    reconfigure: Boolean(options.reconfigure),
+  };
+  const boundary = parseBoundary(text, options);
+  if (boundary.error && /^malformed model route/.test(boundary.error)) {
+    return fallback(boundary.error);
+  }
+  const safety = boundary.document
+    ? inspectEffectiveRouteSafety(boundary.document, OPENAI_PROVIDER)
+    : null;
+  if (safety?.status === "blocked") {
+    return {
+      action: "stop",
+      backupAllowed: false,
+      capabilities: inspectHermesCapabilities(text, options),
+      classification: classificationFromDocument(boundary.document, boundary.fresh),
+      reason: safety.reason,
+      request,
+      sourceHash: sourceHash(String(text || "")),
+      stop: { code: safety.code, route: safety.route },
+      text: boundary.error || safety.redact ? null : String(text || ""),
+    };
+  }
+  if (boundary.error) {
+    return fallback(
+      boundary.error,
+      undefined,
+      boundary.credentialKey ? { credentialKey: boundary.credentialKey } : {},
+    );
+  }
+  const classification = classificationFromDocument(boundary.document, boundary.fresh);
+  if (classification.class === "malformed_unknown") {
+    return fallback("unknown model config schema", classification);
+  }
+  if (classification.class === "other_gpt56"
+    && boundary.document.getIn(["model", "provider"]) === OPENAI_PROVIDER) {
+    return fallback("unknown model route", classification);
+  }
+  const shouldWrite = boundary.fresh || classification.class === "unconfigured" || Boolean(options.reconfigure);
+  const samplingSafety = inspectManagedAstraSampling(boundary.document, route, shouldWrite);
+  if (samplingSafety.status === "blocked") {
+    return {
+      action: "stop",
+      backupAllowed: false,
+      capabilities: inspectHermesCapabilities(text, options),
+      classification,
+      reason: samplingSafety.reason,
+      request,
+      sourceHash: sourceHash(String(text || "")),
+      stop: { code: samplingSafety.code, route: samplingSafety.route },
+      text: String(text || ""),
+    };
+  }
+  const transportReason = customChildTransportReason(boundary.document);
+  if (shouldWrite && transportReason) {
+    return {
+      action: "preserve",
+      backupAllowed: false,
+      capabilities: inspectHermesCapabilities(text, options),
+      classification,
+      reason: `${transportReason}; managed child route remains unapplied`,
+      request,
+      sourceHash: sourceHash(String(text || "")),
+      text: String(text || ""),
+    };
+  }
+  if (!shouldWrite) {
+    return {
+      action: "preserve",
+      backupAllowed: false,
+      capabilities: inspectHermesCapabilities(text, options),
+      classification,
+      reason: "existing model settings preserved; pass --reconfigure-model to opt in",
+      request,
+      sourceHash: sourceHash(String(text || "")),
+      text: String(text || ""),
+    };
+  }
+  const document = boundary.document;
+  applyManagedRoute(document, route);
+  // The verified legacy context/compression defaults belong to legacy model
+  // resets only. Astra has no host-published limit evidence, so an Astra reset
+  // preserves explicit values and leaves missing values absent.
+  if (options.reconfigure && route.model !== ASTRA_MODEL && route.childModel !== ASTRA_MODEL) {
+    document.setIn(["model", "context_length"], SAFE_CONTEXT_LENGTH);
+    document.setIn(["compression", "threshold"], SAFE_COMPRESSION_THRESHOLD);
+  }
+  document.setIn(["delegation", "max_concurrent_children"], 20);
+  document.setIn(["delegation", "max_spawn_depth"], 1);
+  document.setIn(["delegation", "orchestrator_enabled"], false);
+  const plannedText = document.toString({ lineWidth: 0 });
+  return {
+    action: "write",
+    backupAllowed: true,
+    capabilities: inspectHermesCapabilities(plannedText, { ...options, ...route }),
+    classification,
+    reason:
+      classifyHostVersion(options.hostVersion).status === "beyond-verified"
+        ? `Hermes ${request.hostVersion} is beyond the verified matrix; source and runtime markers verified, model schema written`
+        : `verified Hermes ${request.hostVersion} model schema`,
+    request,
+    sourceHash: sourceHash(String(text || "")),
+    text: plannedText,
+  };
+}
+
+function revalidateModelConfigPlan(hermesHome, plan) {
+  const file = path.join(hermesHome, "config.yaml");
+  const current = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  if (plan.sourceHash === sourceHash(current)) return { current, ok: true };
+  const refreshed = planModelConfig(current, plan.request || {});
+  return {
+    classification: refreshed.classification,
+    current,
+    ok: false,
+    reason: `host config changed before write; ${refreshed.reason || refreshed.classification.class}`,
+  };
+}
+
+function applyModelConfigPlan(hermesHome, plan) {
+  if (plan.action !== "write") return { backupPath: null, written: false };
+  const validation = revalidateModelConfigPlan(hermesHome, plan);
+  if (!validation.ok) {
+    return { backupPath: null, drifted: true, reason: validation.reason, written: false };
+  }
+  const file = path.join(hermesHome, "config.yaml");
+  const before = validation.current;
+  const backupPath = before ? `${file}.lithermes-model.bak` : null;
+  fs.mkdirSync(hermesHome, { recursive: true });
+  if (backupPath) {
+    writeFileAtomic(backupPath, before, "utf8");
+    fs.chmodSync(backupPath, 0o600);
+  }
+  writeFileAtomic(file, plan.text, "utf8");
+  fs.chmodSync(file, 0o600);
+  return { backupPath, sourceHash: sourceHash(before), written: true };
+}
+
+module.exports = {
+  applyModelConfigPlan,
+  classifyModelConfig,
+  inspectHermesCapabilities,
+  planModelConfig,
+  revalidateModelConfigPlan,
+};

package/src/lib/modelConfigBoundary.js

@@ -0,0 +1,206 @@
+const crypto = require("node:crypto");
+const { isMap, isScalar, parseDocument, visit } = require("yaml");
+
+// Host versions whose source and runtime markers were checked against this schema by
+// hand. Being outside this set is not a rejection: an exact-membership gate turns every
+// future Hermes release into a silent capability outage, which is precisely how the
+// July 2026 campaign's headline defect happened (the set held 0.17.0 while the host had
+// moved to 0.19.0, and the plugin went inert). The real gate is the source/runtime
+// marker check below, which is probed from the host that is actually running.
+const VERIFIED_HOST_VERSIONS = new Set(["0.17.0", "0.19.0"]);
+const VERIFIED_HOST_VERSION_TEXT = [...VERIFIED_HOST_VERSIONS].join(", ");
+// Below this the managed schema did not exist, so forward compatibility must not become
+// backward acceptance.
+const MINIMUM_HOST_VERSION = "0.17.0";
+const CONFIG_VERSION = 30;
+const CREDENTIAL_KEY = /(^|[_-])(api[_-]?key|client[_-]?secret|auth[_-]?token|(?:aws[_-]?)?access[_-]?key(?:[_-]?id)?|(?:ssh[_-]?)?private[_-]?key|token|password|passphrase|secret|credential|authorization)([_-]|$)/i;
+const MAP_PATHS = ["model", "agent", "delegation", "compression"];
+const SCALAR_PATHS = [
+  ["model", "provider"],
+  ["model", "default"],
+  ["model", "context_length"],
+  ["agent", "reasoning_effort"],
+  ["delegation", "model"],
+  ["delegation", "reasoning_effort"],
+  ["delegation", "provider"],
+  ["delegation", "base_url"],
+  ["delegation", "api_mode"],
+  ["delegation", "max_concurrent_children"],
+  ["delegation", "max_async_children"],
+  ["delegation", "max_spawn_depth"],
+  ["delegation", "orchestrator_enabled"],
+  ["compression", "threshold"],
+];
+const RUNTIME_STEM = ["co", "dex"].join("");
+const OPENAI_PROVIDER = `openai-${RUNTIME_STEM}`;
+const RESPONSES_MODE = `${RUNTIME_STEM}_responses`;
+
+function isCredentialLikeKey(value) {
+  const normalized = String(value || "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/-/g, "_");
+  return CREDENTIAL_KEY.test(normalized);
+}
+
+function isEnvironmentName(value) {
+  return /^[A-Z][A-Z0-9_]*$/.test(value) && /_/.test(value);
+}
+
+function isSecretLookingScalar(node) {
+  if (!isScalar(node)) return false;
+  const value = node.value;
+  if (value === null || typeof value === "boolean" || typeof value === "number") return false;
+  if (typeof value !== "string") return false;
+  const trimmed = value.trim();
+  if (!trimmed || /^(?:true|false|null)$/i.test(trimmed)) return false;
+  if (isEnvironmentName(trimmed) || /^\$\{[A-Z][A-Z0-9_]*\}$/.test(trimmed)) return false;
+  // Explicitly redacted fixtures are test/documentation placeholders, not
+  // material that a config round-trip could expose; real non-empty secrets
+  // (including ordinary `sk-...` values) remain blocked.
+  if (/(?:^|[-_])(redacted|placeholder)(?:[-_]|$)/i.test(trimmed)) return false;
+  return true;
+}
+
+function findCredentialRiskKey(document) {
+  let credentialKey = null;
+  // The writer serializes the complete document and may create a complete
+  // backup, so an unrelated credential can still be copied or reformatted.
+  visit(document, {
+    Pair(_key, pair) {
+      if (isScalar(pair.key)
+        && isCredentialLikeKey(pair.key.value)
+        && isSecretLookingScalar(pair.value)) {
+        credentialKey = String(pair.key.value);
+        return visit.BREAK;
+      }
+      return undefined;
+    },
+  });
+  return credentialKey;
+}
+
+function sourceHash(text) {
+  return crypto.createHash("sha256").update(text).digest("hex");
+}
+
+// Hermes 0.19 prints "Hermes Agent v0.19.0 (2026.7.20) · upstream <hash>" plus an
+// "Install directory:" second line; only that exact build/upstream shape is
+// tolerated — arbitrary suffixes ("-beta", "_beta", " stable") stay rejected.
+function exactHostVersion(raw) {
+  const firstLine = String(raw || "").split(/\r?\n/, 1)[0];
+  const match = firstLine
+    .match(/^(?:Hermes Agent )?v?([0-9]+(?:\.[0-9]+)+)(?: \([0-9]{4}\.[0-9]{1,2}\.[0-9]{1,2}\)(?: · upstream [0-9a-f]{7,40})?)?$/);
+  return match?.[1] || "";
+}
+
+/** Compare dotted numeric versions. Returns <0, 0 or >0. */
+function compareVersions(left, right) {
+  const a = left.split(".").map(Number);
+  const b = right.split(".").map(Number);
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    const diff = (a[index] ?? 0) - (b[index] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+/**
+ * Classify a host banner. The banner shape stays strict — arbitrary suffixes such as
+ * "-beta", "_beta", " stable" and four-part builds are still not a release we will write
+ * against — but a well-formed release at or above the floor is accepted whether or not
+ * this matrix has seen it.
+ */
+function classifyHostVersion(raw) {
+  const version = exactHostVersion(raw);
+  // A release is exactly major.minor.patch. Four-part builds such as 0.19.0.1 are not a
+  // published release line and were rejected before this gate accepted unseen versions.
+  if (!version || !/^\d+\.\d+\.\d+$/u.test(version)) return { version: "", status: "malformed" };
+  if (compareVersions(version, MINIMUM_HOST_VERSION) < 0) return { version, status: "too-old" };
+  if (VERIFIED_HOST_VERSIONS.has(version)) return { version, status: "verified" };
+  return { version, status: "beyond-verified" };
+}
+
+function hostVersionError(classified) {
+  if (classified.status === "malformed") {
+    return `unsupported Hermes host version; expected a release banner at or above ${MINIMUM_HOST_VERSION} (verified: ${VERIFIED_HOST_VERSION_TEXT})`;
+  }
+  if (classified.status === "too-old") {
+    return `Hermes host ${classified.version} is older than the minimum supported Hermes host ${MINIMUM_HOST_VERSION}`;
+  }
+  return "";
+}
+
+function parseBoundary(text, options = {}) {
+  const raw = String(text || "");
+  if (!raw.trim()) {
+    const document = parseDocument(`_config_version: ${CONFIG_VERSION}\n`);
+    const classified = classifyHostVersion(options.hostVersion);
+    const versionError = hostVersionError(classified);
+    if (versionError) {
+      return { document, error: versionError, fresh: true };
+    }
+    if (!options.hostCapabilities?.concurrencyHard
+      || !options.hostCapabilities?.delegationRouteHard
+      || !options.hostCapabilities?.runtimeHard) {
+      return { document, error: "unverified Hermes host source/runtime markers", fresh: true };
+    }
+    return { document, fresh: true };
+  }
+  const document = parseDocument(raw, {
+    keepSourceTokens: true,
+    maxAliasCount: 50,
+    merge: false,
+    strict: true,
+    uniqueKeys: true,
+  });
+  if (document.errors.length || !isMap(document.contents)) {
+    return { error: "malformed host config" };
+  }
+  const credentialKey = findCredentialRiskKey(document);
+  if (document.get("_config_version") !== CONFIG_VERSION) {
+    return { error: `unknown host config schema; expected version ${CONFIG_VERSION}` };
+  }
+  for (const key of MAP_PATHS) {
+    const node = document.get(key, true);
+    if (node !== undefined && !isMap(node)) return { error: `unknown host config schema at ${key}` };
+  }
+  for (const routePath of SCALAR_PATHS) {
+    const node = document.getIn(routePath, true);
+    if (node !== undefined && !isScalar(node)) {
+      return {
+        document,
+        error: `malformed model route at ${routePath.join(".")}`,
+        fresh: false,
+      };
+    }
+  }
+  const classified = classifyHostVersion(options.hostVersion);
+  const versionError = hostVersionError(classified);
+  if (versionError) {
+    return { document, error: versionError, fresh: false };
+  }
+  if (!options.hostCapabilities?.concurrencyHard
+    || !options.hostCapabilities?.delegationRouteHard
+    || !options.hostCapabilities?.runtimeHard) {
+    return { document, error: "unverified Hermes host source/runtime markers", fresh: false };
+  }
+  if (credentialKey) {
+    return {
+      document,
+      credentialKey,
+      error: `credential-risk host config (key: ${credentialKey})`,
+      fresh: false,
+    };
+  }
+  return { document, fresh: false };
+}
+
+module.exports = {
+  MINIMUM_HOST_VERSION,
+  OPENAI_PROVIDER,
+  RESPONSES_MODE,
+  classifyHostVersion,
+  exactHostVersion,
+  parseBoundary,
+  sourceHash,
+};