@huynle/hub 0.6.1 → 0.7.2

package/packages/cli/src/bootstrap/contracts/preview.ts

@@ -0,0 +1,190 @@
+// SetupPreview: what `hubctl setup preview` outputs. It contains the plan, its digest and preview token, the
+// blockers that stop apply, and the upstream evidence already checked for pinned harness downloads.
+//
+// The only blocker in v1 is a manual edit. When a config the plan would change is a symlink (for example
+// ~/.config/opencode pointing into a dotfiles repository), hubctl refuses to write through it. Instead it emits the
+// exact, structured, secret-free edit for the user to make in the repository the link points to. The edit
+// replaces its action: the plan itself never contains an action that writes through the link. Apply refuses while
+// any blocker remains (manual_edit_required, exit 10). Once the user has made the edit, a new preview sees the
+// changed config, so its digest differs and that plan no longer carries the refused action.
+//
+// v1.1: a second reason, unmergeable-format: a config hubctl cannot edit losslessly (TOML, or a file it cannot
+// parse) gets the same exact, structured edit, for the file itself (no link involved), instead of a bare conflict.
+import { checkConfigSets, checkPrecondition, CONFIG_OWNERS, findExecKeys, type Action, type ConfigFormat, type ConfigOwner, type ConfigSet, type Precondition } from "./actions.ts"
+import { EVIDENCE_KINDS, HARNESS_ORDER, type EvidenceKind, type HarnessID } from "./harness.ts"
+import { checkPathRef, type PathRef } from "./paths.ts"
+import { planDigest, validatePreviewToken, validateSetupPlan, type PreviewToken, type SetupPlan } from "./plan.ts"
+import { findSecrets } from "./secrets.ts"
+import { absPath, Checker, digest, fail, header, int, isRecord, list, ok, oneOf, pointer, shape, text, type Result } from "./validate.ts"
+
+export type ManualChange =
+  | { readonly op: "merge"; readonly set: readonly ConfigSet[] }
+  /** Register this hubctl's `mcp` subcommand under `name` (the command is implied, as in the action). */
+  | { readonly op: "register-mcp-server"; readonly harness: HarnessID; readonly name: string }
+  | { readonly op: "write-file"; readonly asset: string; readonly sha256: string; readonly mode: number }
+
+export const MANUAL_EDIT_REASONS = ["symlinked-config", "unmergeable-format"] as const
+export type ManualEditReason = (typeof MANUAL_EDIT_REASONS)[number]
+
+export interface ManualEdit {
+  readonly kind: "manual-edit"
+  readonly reason: ManualEditReason
+  /** The plan action it replaces. */
+  readonly actionID: string
+  readonly path: PathRef
+  /** The symlink found between the root and the target (symlinked-config only). */
+  readonly linkPath?: string
+  /** Where the edit belongs (the file the link resolves to). */
+  readonly resolvedPath: string
+  readonly format?: ConfigFormat
+  readonly owner?: ConfigOwner
+  /** What the file looked like when the edit was computed. */
+  readonly precondition?: Precondition
+  readonly change: ManualChange
+}
+
+/** Everything that stops apply. */
+export type PlanBlocker = ManualEdit
+
+const ACTION_ID = /^[a-z0-9][a-z0-9-]{0,63}$/
+
+function checkManualEdit(c: Checker, path: string, value: unknown): void {
+  for (const p of findExecKeys(value, path)) c.add(p, "exec_field", "a manual edit never carries a command")
+  const r = shape(c, path, value, ["kind", "reason", "actionID", "path", "resolvedPath", "change"], ["linkPath", "format", "owner", "precondition"])
+  if (!r) return
+  const at = (key: string) => pointer(path, key)
+  if (r.kind !== "manual-edit") c.add(at("kind"), "invalid_value", "expected manual-edit")
+  oneOf(c, at("reason"), r.reason, MANUAL_EDIT_REASONS)
+  text(c, at("actionID"), r.actionID, 64, ACTION_ID)
+  checkPathRef(c, at("path"), r.path)
+  if (r.reason === "symlinked-config" && r.linkPath === undefined) c.add(at("linkPath"), "missing_field", "a symlinked config names its link")
+  if (r.reason === "unmergeable-format" && r.linkPath !== undefined) c.add(at("linkPath"), "inconsistent", "an unmergeable config is edited in place; no link is involved")
+  if (r.linkPath !== undefined) absPath(c, at("linkPath"), r.linkPath)
+  absPath(c, at("resolvedPath"), r.resolvedPath)
+  if (r.format !== undefined) oneOf(c, at("format"), r.format, ["json", "jsonc", "toml"] as const)
+  if (r.owner !== undefined) oneOf(c, at("owner"), r.owner, CONFIG_OWNERS)
+  if (r.precondition !== undefined) checkPrecondition(c, at("precondition"), r.precondition)
+  const change = isRecord(r.change) ? r.change : undefined
+  if (!change) return void c.add(at("change"), "invalid_value", "expected a change")
+  const cp = at("change")
+  if (!oneOf(c, pointer(cp, "op"), change.op, ["merge", "register-mcp-server", "write-file"] as const)) return
+  if (change.op === "merge") {
+    shape(c, cp, change, ["op", "set"])
+    checkConfigSets(c, pointer(cp, "set"), change.set)
+  } else if (change.op === "register-mcp-server") {
+    shape(c, cp, change, ["op", "harness", "name"])
+    oneOf(c, pointer(cp, "harness"), change.harness, HARNESS_ORDER)
+    text(c, pointer(cp, "name"), change.name, 32, /^[a-z0-9][a-z0-9-]{0,31}$/)
+  } else {
+    shape(c, cp, change, ["op", "asset", "sha256", "mode"])
+    text(c, pointer(cp, "asset"), change.asset, 128, /^[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._-]*)*$/)
+    digest(c, pointer(cp, "sha256"), change.sha256)
+    int(c, pointer(cp, "mode"), change.mode, 0, 0o7777)
+  }
+  for (const p of findSecrets(value, path)) c.add(p, "secret", "a manual edit never carries credentials")
+}
+
+export function validateManualEdit(value: unknown): Result<ManualEdit> {
+  const c = new Checker()
+  checkManualEdit(c, "", value)
+  return c.result(value)
+}
+
+/** The manual edit that replaces `action` when its target is behind a symlink; undefined if the action writes no config or file. */
+export function manualEditFor(action: Action, link: { readonly linkPath: string; readonly resolvedPath: string }): ManualEdit | undefined {
+  const base = { kind: "manual-edit", reason: "symlinked-config", actionID: action.id, linkPath: link.linkPath, resolvedPath: link.resolvedPath } as const
+  switch (action.kind) {
+    case "merge-config":
+      return { ...base, path: action.path, format: action.format, owner: action.owner, precondition: action.precondition, change: { op: "merge", set: action.set } }
+    case "register-mcp-server":
+      return { ...base, path: action.path, precondition: action.precondition, change: { op: "register-mcp-server", harness: action.harness, name: action.name } }
+    case "write-file":
+      return { ...base, path: action.path, change: { op: "write-file", asset: action.asset, sha256: action.sha256, mode: action.mode } }
+    default:
+      return undefined
+  }
+}
+
+/**
+ * v1.1: the manual edit that replaces a config action hubctl cannot apply losslessly (TOML, or a file it cannot
+ * parse), for the file at `resolvedPath` itself; undefined if the action edits no config.
+ */
+export function unmergeableEditFor(action: Action, resolvedPath: string): ManualEdit | undefined {
+  const base = { kind: "manual-edit", reason: "unmergeable-format", actionID: action.id, resolvedPath } as const
+  switch (action.kind) {
+    case "merge-config":
+      return { ...base, path: action.path, format: action.format, owner: action.owner, precondition: action.precondition, change: { op: "merge", set: action.set } }
+    case "register-mcp-server":
+      return { ...base, path: action.path, precondition: action.precondition, change: { op: "register-mcp-server", harness: action.harness, name: action.name } }
+    default:
+      return undefined
+  }
+}
+
+/** An upstream evidence check reported in the preview; "deferred" checks run on the downloaded bytes at apply. */
+export interface PreviewEvidence {
+  readonly actionID: string
+  readonly kind: EvidenceKind
+  readonly status: "verified" | "unavailable" | "deferred" | "failed"
+  readonly detail?: string
+}
+
+export const SETUP_PREVIEW_SCHEMA = "hub.setup-preview"
+
+export interface SetupPreview {
+  readonly schema: typeof SETUP_PREVIEW_SCHEMA
+  readonly version: 1
+  readonly plan: SetupPlan
+  readonly planDigest: string
+  readonly token: PreviewToken
+  readonly blockers: readonly PlanBlocker[]
+  readonly evidence: readonly PreviewEvidence[]
+}
+
+export function validateSetupPreview(value: unknown): Result<SetupPreview> {
+  const c = new Checker()
+  const r = shape(c, "", value, ["schema", "version", "plan", "planDigest", "token", "blockers", "evidence"])
+  if (!r) return c.result(value)
+  header(c, "", r, SETUP_PREVIEW_SCHEMA, 1)
+  const plan = validateSetupPlan(r.plan)
+  c.merge("/plan", plan)
+  digest(c, "/planDigest", r.planDigest)
+  const token = validatePreviewToken(r.token)
+  c.merge("/token", token)
+  const actions = plan.ok ? plan.value.actions : []
+  if (plan.ok) {
+    const d = planDigest(plan.value)
+    if (r.planDigest !== d) c.add("/planDigest", "inconsistent", "planDigest is not the digest of the plan")
+    if (token.ok && (token.value.planDigest !== d || token.value.hostFingerprint !== plan.value.hostFingerprint || token.value.snapshotDigest !== plan.value.snapshotDigest))
+      c.add("/token", "inconsistent", "the token is not for this plan")
+  }
+  list(c, "/blockers", r.blockers, 256, (p, b) => {
+    checkManualEdit(c, p, b)
+    // A manual edit replaces its action: the plan never keeps an action that would write through the symlink.
+    if (plan.ok && isRecord(b) && actions.some((a) => a.id === b.actionID)) c.add(pointer(p, "actionID"), "inconsistent", "the refused action is still in the plan")
+  })
+  list(c, "/evidence", r.evidence, 256, (p, e) => {
+    const ev = shape(c, p, e, ["actionID", "kind", "status"], ["detail"])
+    if (!ev) return
+    text(c, pointer(p, "actionID"), ev.actionID, 64, ACTION_ID)
+    oneOf(c, pointer(p, "kind"), ev.kind, EVIDENCE_KINDS)
+    oneOf(c, pointer(p, "status"), ev.status, ["verified", "unavailable", "deferred", "failed"] as const)
+    if (ev.detail !== undefined) text(c, pointer(p, "detail"), ev.detail)
+    const action = actions.find((a) => a.id === ev.actionID)
+    if (plan.ok && (action?.kind !== "install-harness" || !action.evidence.includes(ev.kind as EvidenceKind))) c.add(p, "inconsistent", "the evidence names no planned check")
+  })
+  // The preview token is not a credential (it grants nothing; apply re-plans and compares), so only its key is exempt.
+  for (const p of findSecrets(value, "", new Set(["/token"]))) c.add(p, "secret", "previews never carry credentials")
+  return c.result(value)
+}
+
+/** Whether apply may proceed past the preview's own findings (revalidatePreview still runs at apply). */
+export function previewApplicable(preview: SetupPreview): Result<SetupPreview> {
+  if (preview.blockers.length > 0) {
+    const reasons = [...new Set(preview.blockers.map((b) => (b.reason === "unmergeable-format" ? "a format hubctl cannot edit losslessly" : "symlinked config")))].join(", ")
+    return fail("/blockers", "manual_edit_required", `${preview.blockers.length} change(s) must be made by hand (${reasons}); make them and preview again`)
+  }
+  const failed = preview.evidence.find((e) => e.status === "failed")
+  if (failed) return fail("/evidence", "evidence_failed", `${failed.kind} failed for ${failed.actionID}`)
+  return ok(preview)
+}

package/packages/cli/src/bootstrap/contracts/profile.ts

@@ -0,0 +1,105 @@
+// Setup profiles: how much of Hub a machine gets.
+//   session-only   the harness integration only (follow and steer sessions); no services, no launches.
+//   launch-node    plus the `hub node` service, so the hub can launch bounded sessions on this machine.
+//   full-harness   plus every chosen harness's spoke service (and opt-in OpenShell checks).
+// Profiles are versioned documents; an older document is upgraded by the migration hook, one version at a time,
+// before it is validated. Escalation is never automatic and services are never activated without confirmation.
+//
+// v1.1 (profile version 2): `revision` records the catalog revision a profile was made from (profile rebases use
+// it), and `enrollment` says whether the plan enrolls the machine ("inline", the default) or leaves it to a separate
+// `hubctl machine enroll` ("separate", which the Ansible path always uses), so both paths plan the same digest.
+import { SERVICE_IDS, type ServiceID } from "./exec.ts"
+import { HARNESS_ORDER, RUNTIME_IDS, type HarnessID, type RuntimeID } from "./harness.ts"
+import { bool, Checker, fail, header, int, isRecord, oneOf, shape, subset, type Result } from "./validate.ts"
+
+export const PROFILE_SCHEMA = "hub.bootstrap-profile"
+export const PROFILE_VERSION = 2
+/** Profile versions a plan may record: plans made by a v1.0 hubctl (profile version 1) still validate and resume. */
+export const PLAN_PROFILE_VERSIONS = [1, 2] as const
+export type PlanProfileVersion = (typeof PLAN_PROFILE_VERSIONS)[number]
+/** v1.1: inline: the plan enrolls the machine (enroll-machine). separate: enrollment is its own step; the plan never enrolls. */
+export const ENROLLMENT_MODES = ["inline", "separate"] as const
+export type EnrollmentMode = (typeof ENROLLMENT_MODES)[number]
+export const PROFILE_IDS = ["session-only", "launch-node", "full-harness"] as const
+export type ProfileID = (typeof PROFILE_IDS)[number]
+
+export interface Profile {
+  readonly schema: typeof PROFILE_SCHEMA
+  readonly version: typeof PROFILE_VERSION
+  readonly id: ProfileID
+  /** In HARNESS_ORDER. */
+  readonly harnesses: readonly HarnessID[]
+  readonly runtimes: readonly RuntimeID[]
+  readonly services: readonly ServiceID[]
+  readonly launch: { readonly enabled: boolean; readonly maxDurationS?: number }
+  /** "explicit": the user may approve elevated actions at apply time; "never": the plan stays unprivileged. */
+  readonly escalation: "never" | "explicit"
+  /** v1.1: the built-in catalog revision this profile was made from (absent: unknown, e.g. written by hand). */
+  readonly revision?: number
+  /** v1.1: whether the plan enrolls the machine (default "inline"). */
+  readonly enrollment?: EnrollmentMode
+}
+
+/** The enrollment mode a profile plans with. */
+export const enrollmentModeOf = (profile: Pick<Profile, "enrollment">): EnrollmentMode => profile.enrollment ?? "inline"
+
+/** The service each harness's spoke runs as, when it has one (OpenCode's spoke lives in its plugin). */
+export const HARNESS_SERVICE: Readonly<Partial<Record<HarnessID, ServiceID>>> = Object.freeze({ "claude-code": "claude-code", codex: "codex-spoke" })
+
+export function validateProfile(value: unknown): Result<Profile> {
+  const c = new Checker()
+  const r = shape(c, "", value, ["schema", "version", "id", "harnesses", "runtimes", "services", "launch", "escalation"], ["revision", "enrollment"])
+  if (!r) return c.result(value)
+  header(c, "", r, PROFILE_SCHEMA, PROFILE_VERSION)
+  if (r.revision !== undefined) int(c, "/revision", r.revision, 1, 1_000_000)
+  if (r.enrollment !== undefined) oneOf(c, "/enrollment", r.enrollment, ENROLLMENT_MODES)
+  oneOf(c, "/id", r.id, PROFILE_IDS)
+  oneOf(c, "/escalation", r.escalation, ["never", "explicit"] as const)
+  const harnesses = subset(c, "/harnesses", r.harnesses, HARNESS_ORDER) ? r.harnesses : []
+  const services = subset(c, "/services", r.services, SERVICE_IDS) ? r.services : []
+  subset(c, "/runtimes", r.runtimes, RUNTIME_IDS)
+  if (Array.isArray(r.harnesses) && r.harnesses.length === 0) c.add("/harnesses", "invalid_value", "a profile sets up at least one harness")
+  const order = harnesses.map((h) => HARNESS_ORDER.indexOf(h))
+  if (order.some((v, i) => i > 0 && v < order[i - 1]!)) c.add("/harnesses", "inconsistent", `harnesses go in the order ${HARNESS_ORDER.join(", ")}`)
+  const launch = shape(c, "/launch", r.launch, ["enabled"], ["maxDurationS"])
+  if (launch) {
+    bool(c, "/launch/enabled", launch.enabled)
+    if (launch.maxDurationS !== undefined) int(c, "/launch/maxDurationS", launch.maxDurationS, 1, 86_400)
+    if (launch.enabled === true && launch.maxDurationS === undefined) c.add("/launch/maxDurationS", "inconsistent", "launches are always bounded")
+    if (launch.enabled === true && !services.includes("node")) c.add("/launch", "inconsistent", "launching needs the node service")
+  }
+  if (r.id === "session-only" && services.length > 0) c.add("/services", "inconsistent", "session-only installs no services")
+  if (r.id === "session-only" && launch?.enabled === true) c.add("/launch", "inconsistent", "session-only never launches")
+  if ((r.id === "launch-node" || r.id === "full-harness") && !services.includes("node")) c.add("/services", "inconsistent", `${String(r.id)} needs the node service`)
+  for (const [harness, service] of Object.entries(HARNESS_SERVICE))
+    if (services.includes(service!) && !harnesses.includes(harness as HarnessID)) c.add("/services", "inconsistent", `the ${service} service needs the ${harness} harness`)
+  return c.result(value)
+}
+
+/** One step: a document of version N (the key) to version N+1. */
+export type ProfileMigration = (raw: Record<string, unknown>) => unknown
+export type ProfileMigrations = Readonly<Record<number, ProfileMigration>>
+
+/**
+ * Registered migrations to the current version. 1 → 2 (v1.1): the new fields are optional and mean what a version-1
+ * document meant (catalog revision unknown, enrollment inline), so only the version changes.
+ */
+export const PROFILE_MIGRATIONS: ProfileMigrations = Object.freeze({
+  1: (raw: Record<string, unknown>) => ({ ...raw, version: 2 }),
+})
+
+/** Upgrades an older profile document step by step, then validates it. */
+export function migrateProfile(raw: unknown, migrations: ProfileMigrations = PROFILE_MIGRATIONS): Result<Profile> {
+  let doc = raw
+  for (;;) {
+    if (!isRecord(doc) || !Number.isInteger(doc.version)) return fail("/version", "invalid_value", "a profile needs an integer version")
+    const version = doc.version as number
+    if (version > PROFILE_VERSION) return fail("/version", "unsupported_version", `profile version ${version} is newer than this hubctl understands (${PROFILE_VERSION}); upgrade hubctl`)
+    if (version === PROFILE_VERSION) return validateProfile(doc)
+    const step = migrations[version]
+    if (!step) return fail("/version", "unmigratable", `no migration from profile version ${version}`)
+    const next = step(doc)
+    if (!isRecord(next) || !Number.isInteger(next.version) || (next.version as number) <= version) return fail("/version", "unmigratable", `the migration from version ${version} did not advance the version`)
+    doc = next
+  }
+}

package/packages/cli/src/bootstrap/contracts/secrets.ts

@@ -0,0 +1,52 @@
+// Secret detection for everything the bootstrap writes outside the credential store: plans, previews, journals,
+// discovery snapshots, status output, logs and generated Ansible. A document that findSecrets flags is refused,
+// not redacted: the only place a machine token may live is the credential store (credentials.ts).
+import { isRecord, pointer } from "./validate.ts"
+
+/** Key names (case-insensitive, "-" and "_" ignored) that mean the value is a credential. */
+const SECRET_KEY_PARTS = ["token", "secret", "password", "passwd", "passphrase", "apikey", "privatekey", "credential", "authorization", "cookie", "devicecode"] as const
+
+/** Value shapes of known credentials (anywhere in a string, at a word start): hub app (hat_), session (hst1.), launch (hlt1) and machine test tokens, common vendor keys, PEM keys, bearer headers. */
+const B = "(?:^|[^A-Za-z0-9_])"
+const SECRET_VALUES: readonly RegExp[] = [
+  new RegExp(`${B}hat_[A-Za-z0-9_-]{8,}`),
+  new RegExp(`${B}hst1\\.[A-Za-z0-9_-]`),
+  new RegExp(`${B}hlt1[A-Za-z0-9._-]{8,}`),
+  new RegExp(`${B}mt_[A-Za-z0-9_-]+`),
+  new RegExp(`${B}sk-[A-Za-z0-9_-]{8,}`),
+  new RegExp(`${B}(?:ghp|gho|ghs|ghu)_[A-Za-z0-9]{8,}`),
+  new RegExp(`${B}github_pat_`),
+  new RegExp(`${B}xox[abprs]-`),
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+  /\bBearer\s+\S/i,
+]
+
+export function isSecretKey(key: string): boolean {
+  const k = key.toLowerCase().replaceAll(/[-_]/g, "")
+  return SECRET_KEY_PARTS.some((part) => k === part || k.endsWith(part) || k.startsWith(part))
+}
+
+export const isSecretValue = (value: string): boolean => SECRET_VALUES.some((re) => re.test(value))
+
+/**
+ * JSON pointers of every credential-named key (with a value) and every credential-shaped string in `value`.
+ * `allowKeys` exempts exact pointers whose key name only looks like a credential (a preview's `/token`); their
+ * values are still scanned.
+ */
+export function findSecrets(value: unknown, base = "", allowKeys: ReadonlySet<string> = new Set()): string[] {
+  const found: string[] = []
+  const walk = (v: unknown, path: string) => {
+    if (typeof v === "string") {
+      if (isSecretValue(v)) found.push(path)
+    } else if (Array.isArray(v)) v.forEach((item, i) => walk(item, pointer(path, i)))
+    else if (isRecord(v))
+      for (const [key, item] of Object.entries(v)) {
+        if (item === undefined) continue
+        const p = pointer(path, key)
+        if (isSecretKey(key) && !allowKeys.has(p)) found.push(p)
+        else walk(item, p)
+      }
+  }
+  walk(value, base)
+  return found
+}

package/packages/cli/src/bootstrap/contracts/validate.ts

@@ -0,0 +1,212 @@
+// A small, dependency-free validator kit for the bootstrap contracts. Every document crossing a trust boundary (a
+// discovery snapshot, a plan read back from disk, a preview token, a manifest downloaded from a release, a journal
+// left by a crashed apply) is parsed as `unknown` and checked here; nothing is cast blindly. Checks collect every
+// issue (with a JSON pointer) instead of stopping at the first, so a report shows the whole problem.
+
+/** Machine-readable reasons a check fails. Tests and callers match on `code`, never on `message`. */
+export type IssueCode =
+  | "invalid_value"
+  | "missing_field"
+  | "unknown_field"
+  | "unsupported_version"
+  | "inconsistent"
+  | "duplicate"
+  | "invalid_path"
+  | "unmapped_root"
+  | "symlink"
+  | "exec_field"
+  | "secret"
+  | "unsupported_platform"
+  | "wrong_platform"
+  | "integrity_mismatch"
+  | "signature_invalid"
+  | "downgrade_rejected"
+  | "below_security_floor"
+  | "trust_root_rollback"
+  | "unmigratable"
+  | "preview_foreign"
+  | "preview_expired"
+  | "preview_not_yet_valid"
+  | "preview_replayed"
+  | "preview_stale"
+  | "unpinned_artifact"
+  | "evidence_failed"
+  | "manual_edit_required"
+  /** v1.1: an action needs escalation the profile never allows (was `inconsistent`). */
+  | "escalation_required"
+  /** v1.1: the profile installs services, but the host has no user service manager. */
+  | "no_service_manager"
+
+export interface Issue {
+  /** JSON pointer of the offending value ("" for the document itself). */
+  readonly path: string
+  readonly code: IssueCode
+  readonly message: string
+}
+
+export type Result<T> = { readonly ok: true; readonly value: T } | { readonly ok: false; readonly issues: readonly Issue[] }
+
+export const ok = <T>(value: T): Result<T> => ({ ok: true, value })
+export const fail = <T = never>(path: string, code: IssueCode, message: string): Result<T> => ({ ok: false, issues: [{ path, code, message }] })
+
+/** Collects issues while a document is walked. */
+export class Checker {
+  readonly issues: Issue[] = []
+
+  add(path: string, code: IssueCode, message: string): void {
+    this.issues.push({ path, code, message })
+  }
+
+  merge(prefix: string, result: Result<unknown>): void {
+    if (!result.ok) for (const issue of result.issues) this.issues.push({ ...issue, path: `${prefix}${issue.path}` })
+  }
+
+  result<T>(value: unknown): Result<T> {
+    return this.issues.length === 0 ? ok(value as T) : { ok: false, issues: [...this.issues] }
+  }
+}
+
+export type Json = null | boolean | number | string | readonly Json[] | { readonly [key: string]: Json }
+
+export const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/** JSON pointer segment escaping (RFC 6901). */
+export const pointer = (base: string, key: string | number): string => `${base}/${String(key).replaceAll("~", "~0").replaceAll("/", "~1")}`
+
+/**
+ * Checks that `value` is an object whose keys are all in `allowed` (keys holding `undefined` count as absent) and
+ * that every key in `required` is present. Returns the object, or undefined (with issues added) when not an object.
+ */
+export function shape(c: Checker, path: string, value: unknown, required: readonly string[], optional: readonly string[] = []): Record<string, unknown> | undefined {
+  if (!isRecord(value)) {
+    c.add(path, "invalid_value", "expected an object")
+    return undefined
+  }
+  const allowed = new Set([...required, ...optional])
+  for (const [key, v] of Object.entries(value)) if (v !== undefined && !allowed.has(key)) c.add(pointer(path, key), "unknown_field", `unknown field ${key}`)
+  for (const key of required) if (value[key] === undefined) c.add(pointer(path, key), "missing_field", `missing ${key}`)
+  return value
+}
+
+/** schema + version header shared by every versioned document. */
+export function header(c: Checker, path: string, r: Record<string, unknown>, schema: string, version: number): void {
+  if (r.schema !== schema) c.add(pointer(path, "schema"), "invalid_value", `expected schema ${schema}`)
+  if (!Number.isInteger(r.version)) c.add(pointer(path, "version"), "invalid_value", "version must be an integer")
+  else if (r.version !== version) c.add(pointer(path, "version"), "unsupported_version", `version ${String(r.version)} is not supported (expected ${version})`)
+}
+
+export function oneOf<T extends string>(c: Checker, path: string, value: unknown, options: readonly T[]): value is T {
+  if (typeof value === "string" && (options as readonly string[]).includes(value)) return true
+  if (value !== undefined) c.add(path, "invalid_value", `expected one of ${options.join(", ")}`)
+  return false
+}
+
+export function bool(c: Checker, path: string, value: unknown): value is boolean {
+  if (typeof value === "boolean") return true
+  if (value !== undefined) c.add(path, "invalid_value", "expected true or false")
+  return false
+}
+
+export function int(c: Checker, path: string, value: unknown, min: number, max: number): value is number {
+  if (Number.isInteger(value) && (value as number) >= min && (value as number) <= max) return true
+  if (value !== undefined) c.add(path, "invalid_value", `expected an integer in ${min}..${max}`)
+  return false
+}
+
+/** A timestamp: integer milliseconds since the epoch. */
+export const instant = (c: Checker, path: string, value: unknown): value is number => int(c, path, value, 0, 8.64e15)
+
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f]/
+
+/** A one-line printable string of bounded length (no control characters, so it cannot fake output lines). */
+export function text(c: Checker, path: string, value: unknown, max = 200, pattern?: RegExp): value is string {
+  if (typeof value === "string" && value.length >= 1 && value.length <= max && !CONTROL.test(value) && (!pattern || pattern.test(value))) return true
+  if (value !== undefined) c.add(path, "invalid_value", pattern ? `expected a string matching ${pattern}` : `expected a one-line string of 1..${max} characters`)
+  return false
+}
+
+export const DIGEST = /^sha256:[0-9a-f]{64}$/
+export const digest = (c: Checker, path: string, value: unknown): value is string => text(c, path, value, 71, DIGEST)
+
+export const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/
+export const semver = (c: Checker, path: string, value: unknown): value is string => text(c, path, value, 64, SEMVER)
+
+/** An absolute, normalized POSIX path: no empty, "." or ".." segments, no trailing slash, no control characters. */
+export function isAbsolutePath(value: unknown): value is string {
+  if (typeof value !== "string" || !value.startsWith("/") || value.length > 4096 || CONTROL.test(value) || value.includes("\\")) return false
+  if (value === "/") return true
+  return value
+    .slice(1)
+    .split("/")
+    .every((s) => s !== "" && s !== "." && s !== "..")
+}
+
+export function absPath(c: Checker, path: string, value: unknown): value is string {
+  if (isAbsolutePath(value)) return true
+  if (value !== undefined) c.add(path, "invalid_path", "expected an absolute, normalized path")
+  return false
+}
+
+/** An array whose items are checked by `item`; `unique` reports repeated keys as duplicates. */
+export function list(c: Checker, path: string, value: unknown, max: number, item: (p: string, v: unknown) => void, unique?: (v: unknown) => string | undefined): value is unknown[] {
+  if (!Array.isArray(value) || value.length > max) {
+    if (value !== undefined) c.add(path, "invalid_value", `expected a list of at most ${max} items`)
+    return false
+  }
+  const seen = new Set<string>()
+  value.forEach((v, i) => {
+    item(pointer(path, i), v)
+    const key = unique?.(v)
+    if (key === undefined) return
+    if (seen.has(key)) c.add(pointer(path, i), "duplicate", `duplicate ${key}`)
+    seen.add(key)
+  })
+  return true
+}
+
+/** A list of distinct strings drawn from `options`. */
+export function subset<T extends string>(c: Checker, path: string, value: unknown, options: readonly T[]): value is T[] {
+  return list(c, path, value, options.length, (p, v) => oneOf(c, p, v, options), (v) => (typeof v === "string" ? v : undefined))
+}
+
+/** A plain file name (no directories). */
+export const FILE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+
+/** An https URL without credentials (download sources: never plain http, not even for loopback). */
+export function httpsURL(c: Checker, path: string, value: unknown): value is string {
+  if (typeof value === "string" && value.length <= 2048) {
+    try {
+      const url = new URL(value)
+      if (url.protocol === "https:" && !url.username && !url.password) return true
+    } catch {}
+  }
+  if (value !== undefined) c.add(path, "invalid_value", "expected an https URL without credentials")
+  return false
+}
+
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "[::1]"])
+
+/** v1.1: whether `value` is a plain-http URL of a non-loopback host, without credentials (an insecure hub). */
+export function isInsecureHubURL(value: unknown): value is string {
+  if (typeof value !== "string" || value.length > 2048) return false
+  try {
+    const url = new URL(value)
+    return url.protocol === "http:" && !LOOPBACK_HOSTS.has(url.hostname) && !url.username && !url.password
+  } catch {
+    return false
+  }
+}
+
+/** http(s) URL; plain http only for loopback hubs (a local hub on 127.0.0.1). */
+export function hubURL(c: Checker, path: string, value: unknown): value is string {
+  if (typeof value === "string" && value.length <= 2048) {
+    try {
+      const url = new URL(value)
+      const loopback = LOOPBACK_HOSTS.has(url.hostname)
+      if ((url.protocol === "https:" || (url.protocol === "http:" && loopback)) && !url.username && !url.password) return true
+    } catch {}
+  }
+  if (value !== undefined) c.add(path, "invalid_value", "expected an https URL (http only for a loopback hub), without credentials")
+  return false
+}