@huynle/hub 0.7.1 → 0.7.3

package/packages/cli/src/bootstrap/release/pins.ts

@@ -0,0 +1,192 @@
+// The reviewed harness pin list: the checked-in input (PIN_LIST_FILE, schema `hub.harness-pin-list` v1) that the
+// release job turns into the signed manifest's `harnesses` (contracts §3.6.1, I5).
+//
+// Format:
+//   { "schema": "hub.harness-pin-list", "version": 1,
+//     "pins": [ { "pin": <HarnessPin, exactly as the manifest lists it>,
+//                 "review": { "by": "<GitHub handle>", "on": "YYYY-MM-DD",
+//                             "checked": ["upstream-release", "digest-redownloaded", "evidence-listed"] } } ] }
+//
+// Review process (see README.md next to this file):
+//   - A pin changes only through a pull request that touches this file; the reviewer is someone other than the
+//     author, and the `review` record names who checked the pin, when, and that every required check was done:
+//       upstream-release     the URL is the upstream's own release asset for exactly this version and target;
+//       digest-redownloaded  the reviewer downloaded the file and computed the size and sha256 themselves;
+//       evidence-listed      `evidence` lists exactly the upstream evidence published for this file.
+//   - Each pin is checked with the manifest's own rules (supported target, exact version, https, plain file name,
+//     one per harness and target, evidence the harness can offer) plus: the file is the URL's last path segment,
+//     and the URL has no credentials, query or fragment. Nothing secret-shaped may appear anywhere.
+//   - The release job re-downloads every pinned file and refuses to sign on any size or digest mismatch
+//     (verifyPinDownloads), so the signature never vouches for a file nobody fetched in that release.
+import { createHash } from "node:crypto"
+import {
+  Checker,
+  HARNESS_ORDER,
+  fail,
+  findSecrets,
+  header,
+  isRecord,
+  list,
+  ok,
+  pointer,
+  shape,
+  text,
+  validateArtifactManifest,
+  type HarnessPin,
+  type Result,
+} from "../contracts/index.ts"
+
+export const PIN_LIST_SCHEMA = "hub.harness-pin-list"
+export const PIN_LIST_VERSION = 1
+/** The checked-in pin list, relative to the repository root. */
+export const PIN_LIST_FILE = "packages/cli/src/bootstrap/release/harness-pins.json"
+
+/** What a reviewer must have checked for each pin (all of them, every time). */
+export const PIN_CHECKS = ["upstream-release", "digest-redownloaded", "evidence-listed"] as const
+export type PinCheck = (typeof PIN_CHECKS)[number]
+
+export interface PinReview {
+  /** The reviewer's GitHub handle. */
+  readonly by: string
+  /** The review date, YYYY-MM-DD. */
+  readonly on: string
+  readonly checked: readonly PinCheck[]
+}
+
+export interface ReviewedPin {
+  readonly pin: HarnessPin
+  readonly review: PinReview
+}
+
+export interface PinList {
+  readonly schema: typeof PIN_LIST_SCHEMA
+  readonly version: typeof PIN_LIST_VERSION
+  readonly pins: readonly ReviewedPin[]
+}
+
+const HANDLE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/
+const DATE = /^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/
+const MAX_PINS = 64
+
+/** A stand-in hubctl artifact, so the pins can be checked by the manifest validator itself. */
+const SKELETON = {
+  schema: "hub.artifact-manifest",
+  version: 1,
+  product: "hubctl",
+  release: "0.0.0",
+  channel: "stable",
+  minimumVersion: "0.0.0",
+  issuedAt: 0,
+  artifacts: [{ target: "linux-x64", file: "hubctl-linux-x64", size: 1, sha256: `sha256:${"0".repeat(64)}` }],
+  signatures: [],
+} as const
+
+/** "/harnesses/3/url" → "/pins/3/pin/url"; "/harnesses/3" → "/pins/3". */
+function pinPath(path: string): string | undefined {
+  const m = /^\/harnesses\/(\d+)(\/.*)?$/.exec(path)
+  if (!m) return undefined
+  return m[2] ? `/pins/${m[1]}/pin${m[2]}` : `/pins/${m[1]}`
+}
+
+function checkReview(c: Checker, p: string, v: unknown) {
+  const r = shape(c, p, v, ["by", "on", "checked"])
+  if (!r) return
+  text(c, pointer(p, "by"), r.by, 39, HANDLE)
+  text(c, pointer(p, "on"), r.on, 10, DATE)
+  if (!list(c, pointer(p, "checked"), r.checked, PIN_CHECKS.length, (q, item) => {
+    if (typeof item !== "string" || !(PIN_CHECKS as readonly string[]).includes(item)) c.add(q, "invalid_value", `expected one of ${PIN_CHECKS.join(", ")}`)
+  }, (item) => (typeof item === "string" ? item : undefined))) return
+  for (const check of PIN_CHECKS) if (!(r.checked as unknown[]).includes(check)) c.add(pointer(p, "checked"), "missing_field", `the review did not record ${check}`)
+}
+
+function checkSource(c: Checker, p: string, pin: unknown) {
+  if (!isRecord(pin) || typeof pin.url !== "string") return
+  let url: URL
+  try {
+    url = new URL(pin.url)
+  } catch {
+    return // the manifest rules report it
+  }
+  if (url.username || url.password || url.search || url.hash) c.add(pointer(p, "url"), "invalid_value", "a pinned URL carries no credentials, query or fragment")
+  const last = decodeURIComponent(url.pathname.split("/").pop() ?? "")
+  if (typeof pin.file === "string" && last !== pin.file) c.add(pointer(p, "file"), "inconsistent", `the file must be the URL's last path segment (${last})`)
+}
+
+export function validatePinList(value: unknown): Result<PinList> {
+  const c = new Checker()
+  const r = shape(c, "", value, ["schema", "version", "pins"])
+  if (!r) return c.result(value)
+  header(c, "", r, PIN_LIST_SCHEMA, PIN_LIST_VERSION)
+  const pins: unknown[] = []
+  const listed = list(c, "/pins", r.pins, MAX_PINS, (p, entry) => {
+    const e = shape(c, p, entry, ["pin", "review"])
+    pins.push(e?.pin)
+    if (!e) return
+    if (e.review !== undefined) checkReview(c, pointer(p, "review"), e.review)
+    checkSource(c, pointer(p, "pin"), e.pin)
+  })
+  if (listed) {
+    const m = validateArtifactManifest({ ...SKELETON, harnesses: pins.map((p) => p ?? {}) })
+    if (!m.ok) for (const issue of m.issues) {
+      const path = pinPath(issue.path)
+      if (path !== undefined) c.add(path, issue.code, issue.message)
+    }
+  }
+  for (const path of findSecrets(value)) c.add(path, "secret", "a pin list never carries a secret")
+  return c.result(value)
+}
+
+const targetOrder = (a: HarnessPin, b: HarnessPin) =>
+  HARNESS_ORDER.indexOf(a.harness) - HARNESS_ORDER.indexOf(b.harness) || (a.target < b.target ? -1 : a.target > b.target ? 1 : 0)
+
+/** The manifest's `harnesses`: the pins in HARNESS_ORDER, then by target (deterministic). */
+export function harnessPins(list: PinList): HarnessPin[] {
+  return list.pins.map((p) => p.pin).sort(targetOrder)
+}
+
+export type Downloader = (url: string) => Promise<{ readonly size: number; readonly sha256: string }>
+
+/**
+ * Re-downloads every pinned file and compares its size and digest with the pin. Any mismatch or failed download is
+ * integrity_mismatch; every pin is checked and reported. Returns the manifest's `harnesses` when all match.
+ */
+export async function verifyPinDownloads(value: unknown, download: Downloader): Promise<Result<HarnessPin[]>> {
+  const valid = validatePinList(value)
+  if (!valid.ok) return valid
+  const c = new Checker()
+  for (const [i, { pin }] of valid.value.pins.entries()) {
+    const at = `/pins/${i}/pin`
+    try {
+      const got = await download(pin.url)
+      if (got.size !== pin.size) c.add(`${at}/size`, "integrity_mismatch", `${pin.harness} ${pin.version} ${pin.target}: expected ${pin.size} bytes, downloaded ${got.size}`)
+      else if (got.sha256 !== pin.sha256) c.add(`${at}/sha256`, "integrity_mismatch", `${pin.harness} ${pin.version} ${pin.target}: the download does not match the pinned digest`)
+    } catch (error) {
+      c.add(`${at}/url`, "integrity_mismatch", `${pin.harness} ${pin.version} ${pin.target}: could not download (${error instanceof Error ? error.message : String(error)})`)
+    }
+  }
+  if (c.issues.length > 0) return { ok: false, issues: c.issues }
+  return ok(harnessPins(valid.value))
+}
+
+/** Streams a URL and returns its size and digest (redirects followed); throws on an HTTP error. */
+export async function httpDigest(url: string, fetcher: typeof fetch = fetch): Promise<{ size: number; sha256: string }> {
+  const response = await fetcher(url, { redirect: "follow" })
+  if (!response.ok || !response.body) throw new Error(`HTTP ${response.status}`)
+  const hash = createHash("sha256")
+  let size = 0
+  const reader = response.body.getReader()
+  for (let next = await reader.read(); !next.done; next = await reader.read()) {
+    hash.update(next.value)
+    size += next.value.byteLength
+  }
+  return { size, sha256: `sha256:${hash.digest("hex")}` }
+}
+
+/** Reads a pin list document (JSON text). */
+export function parsePinList(text: string): Result<PinList> {
+  try {
+    return validatePinList(JSON.parse(text))
+  } catch {
+    return fail("", "invalid_value", "the pin list is not JSON")
+  }
+}

package/packages/cli/src/bootstrap/release/text-assets.d.ts

@@ -0,0 +1,9 @@
+// Service templates imported `with { type: "text" }` (assets.ts): Bun gives their contents as a string.
+declare module "*.plist" {
+  const text: string
+  export default text
+}
+declare module "*.service" {
+  const text: string
+  export default text
+}

package/packages/cli/src/bootstrap/release/trust-root.json

@@ -0,0 +1,13 @@
+{
+  "schema": "hub.trust-root",
+  "version": 1,
+  "threshold": 1,
+  "keys": [
+    {
+      "keyID": "hub-release-1",
+      "algorithm": "ed25519",
+      "publicKey": "MCowBQYDK2VwAyEAedYGFamR6BeN2QG7eorgc1ilpboyFzEiwaOE+n8bzVQ=",
+      "status": "active"
+    }
+  ]
+}

package/packages/cli/src/bootstrap/release/trust-root.ts

@@ -0,0 +1,39 @@
+// The trust root a standalone hubctl ships (contracts §3.6, I6): public keys only, embedded at build time with
+// `bun build --compile --define HUBCTL_TRUST_ROOT=<JSON string>` (trustRootDefine). It is never read from the
+// environment or the disk at run time, so nothing on the machine can swap it; replacing it goes through
+// rotateTrustRoot. A build without it (a source run, the npm bundle, a dev build) has no trust root and refuses
+// every manifest, rather than trusting one by default.
+import { canonicalJSON, fail, findSecrets, validateTrustRoot, type Result, type TrustRoot } from "../contracts/index.ts"
+
+/** The identifier `bun build --define` replaces with the trust root's canonical JSON (a string literal). */
+export const TRUST_ROOT_DEFINE = "HUBCTL_TRUST_ROOT"
+
+declare const HUBCTL_TRUST_ROOT: string | undefined
+
+/** The embedded trust root text, or undefined when this build has none. */
+export function embeddedTrustRootText(): string | undefined {
+  return typeof HUBCTL_TRUST_ROOT === "string" ? HUBCTL_TRUST_ROOT : undefined
+}
+
+/** The shipped trust root, validated; signature_invalid when the build has none or it is unusable. */
+export function shippedTrustRoot(text: string | undefined = embeddedTrustRootText()): Result<TrustRoot> {
+  if (text === undefined) return fail("", "signature_invalid", "this hubctl build has no trust root, so it cannot verify releases (use a signed release build)")
+  let value: unknown
+  try {
+    value = JSON.parse(text)
+  } catch {
+    return fail("", "signature_invalid", "the embedded trust root is not JSON")
+  }
+  const r = validateTrustRoot(value)
+  if (!r.ok) return fail("", "signature_invalid", `the embedded trust root is unusable: ${r.issues.map((i) => `${i.path} ${i.message}`).join("; ")}`)
+  if (findSecrets(value).length > 0) return fail("", "signature_invalid", "the embedded trust root carries key material that is not a public key")
+  return r
+}
+
+/** The `bun build` words that embed `root`; throws on anything but a valid, public-keys-only trust root. */
+export function trustRootDefine(root: TrustRoot): string[] {
+  const text = canonicalJSON(root)
+  const r = shippedTrustRoot(text)
+  if (!r.ok) throw new Error(r.issues.map((i) => i.message).join("; "))
+  return ["--define", `${TRUST_ROOT_DEFINE}=${JSON.stringify(text)}`]
+}

package/packages/cli/src/bootstrap/release/verify.ts

@@ -0,0 +1,88 @@
+// The hubctl release verification library: everything an installer checks about a downloaded hubctl before it
+// touches the disk, in the order that keeps untrusted data inert:
+//   1. the manifest is well formed and signed by `threshold` active keys of the shipped trust root (T1, T2);
+//   2. it lists an artifact for exactly this host's target, and the host is a supported one (T3);
+//   3. the downloaded bytes have exactly that size and digest (T1);
+//   4. the install is not a downgrade below the security floor, nor an unconsented downgrade (T4).
+// Only the contracts are used (node:crypto, no dependencies), so the release signing job can run it without any
+// npm install.
+import { createHash } from "node:crypto"
+import {
+  checkArtifactBytes,
+  compareVersions,
+  decideInstall,
+  fail,
+  ok,
+  selectArtifact,
+  verifyManifest,
+  type ArtifactEntry,
+  type InstallKind,
+  type Result,
+  type SignatureVerifier,
+  type TrustRoot,
+  type VerifiedManifest,
+} from "../contracts/index.ts"
+
+export interface ReleaseCheckInput {
+  /** The parsed manifest document (untrusted). */
+  readonly manifest: unknown
+  /** The trust root this hubctl ships (or a rotated successor accepted through rotateTrustRoot). */
+  readonly root: TrustRoot
+  /** This host's target (targetOf); never a "close enough" one. */
+  readonly target: string
+  /** Size and digest of the downloaded hubctl (digestBytes). */
+  readonly bytes: { readonly sha256: string; readonly size: number }
+  /** The hubctl installed now, if any. */
+  readonly installed?: { readonly version: string; readonly sha256: string }
+  /** The highest security floor this machine has seen in a verified manifest. */
+  readonly floor?: string
+  /** Explicit --allow-downgrade (never below the floor). */
+  readonly allowDowngrade?: boolean
+  readonly verifier?: SignatureVerifier
+}
+
+export interface AcceptedRelease {
+  readonly manifest: VerifiedManifest
+  readonly artifact: ArtifactEntry
+  readonly kind: InstallKind
+  /** The security floor to persist after the install: max(seen floor, manifest floor). */
+  readonly floor: string
+}
+
+/** Largest manifest accepted (a real one is a few kilobytes). */
+export const MAX_MANIFEST_BYTES = 1_048_576
+
+const maxVersion = (a: string, b?: string) => (b !== undefined && compareVersions(b, a) > 0 ? b : a)
+
+export function verifyHubctlRelease(input: ReleaseCheckInput): Result<AcceptedRelease> {
+  const verified = verifyManifest(input.manifest, input.root, input.verifier)
+  if (!verified.ok) return verified
+  const manifest = verified.value
+  const artifact = selectArtifact(manifest, input.target)
+  if (!artifact.ok) return artifact
+  const bytes = checkArtifactBytes(artifact.value, input.bytes)
+  if (!bytes.ok) return bytes
+  const kind = decideInstall({
+    candidate: { release: manifest.release, minimumVersion: manifest.minimumVersion, sha256: input.bytes.sha256 },
+    ...(input.installed ? { installed: input.installed } : {}),
+    ...(input.floor !== undefined ? { floor: input.floor } : {}),
+    ...(input.allowDowngrade !== undefined ? { allowDowngrade: input.allowDowngrade } : {}),
+  })
+  if (!kind.ok) return kind
+  return ok({ manifest, artifact: artifact.value, kind: kind.value, floor: maxVersion(manifest.minimumVersion, input.floor) })
+}
+
+/** Size and "sha256:<hex>" of some bytes, the form manifests list. */
+export function digestBytes(bytes: Uint8Array): { size: number; sha256: string } {
+  return { size: bytes.byteLength, sha256: `sha256:${createHash("sha256").update(bytes).digest("hex")}` }
+}
+
+/** JSON text of a downloaded manifest, bounded; the document still needs verifyHubctlRelease. */
+export function parseManifest(text: string): Result<unknown> {
+  if (text.length > MAX_MANIFEST_BYTES) return fail("", "invalid_value", `a manifest is at most ${MAX_MANIFEST_BYTES} bytes`)
+  try {
+    return ok(JSON.parse(text) as unknown)
+  } catch {
+    return fail("", "invalid_value", "the manifest is not JSON")
+  }
+}

package/packages/cli/src/bootstrap/transaction/builtin.ts

@@ -0,0 +1,312 @@
+// The built-in executors: the local file, config and directory steps, plus the two artifact installs whose bytes
+// must be authenticated before use. Each only computes what the target should become; the engine stages, journals
+// and replaces it atomically.
+//
+//   ensure-directory   a directory (an existing directory is left as it is)
+//   write-file         an embedded/rendered asset whose bytes must match the plan's digest; never overwrites
+//   merge-config       a lossless JSON merge, only if the file is still as previewed (precondition digest)
+//   link-executable    the hub ↔ hubctl alias symlink (an existing entry is backed up and replaced)
+//   select-harness-version  v1.1: the harness's `current` link, switched atomically to an installed version
+//                      directory (relative, so it reads the same inside and outside a container); the previous
+//                      link is backed up, so a rollback makes the previous version current again
+//   install-service    the rendered unit, whose bytes must match the plan's digest
+//   deactivate-service v1.1: unloads a hub service through the injected ServiceControl (an external effect; its
+//                      undo loads it again)
+//   remove-service     v1.1: removes the unit, only while it is still exactly the one hub installed (backed up, so
+//                      a rollback restores it)
+//   install-artifact   hubctl from a verified manifest: exact target, pinned digest, downgrade policy, bytes checked
+//                      (hubctl's own executable is digested and copied in chunks, never read whole)
+//   install-harness    a harness pinned by the verified manifest: checkHarnessPin, downgrade policy, the pinned
+//                      digest of the download first, then the upstream evidence, then the adapter's unpacker
+//
+// Fetching and unpacking come from injected, typed sources (no shell, no generic exec); verification always
+// happens here, so a source cannot skip it. Harness downloads stream into the step's staging area, which digests
+// them as it writes: the pin is checked against that digest, never one the source reports, before anything is
+// unpacked; the unpacker streams the archive's members into the staging area too (bounded memory, stream.ts).
+import {
+  checkArtifactBytes,
+  checkHarnessEvidence,
+  checkHarnessPin,
+  decideHarnessInstall,
+  decideInstall,
+  isSafeRel,
+  selectArtifact,
+  type ArtifactEntry,
+  type EvidenceResult,
+  type HarnessID,
+  type InstallHarness,
+  type InstallService,
+  type ServiceID,
+  type ServiceManagerID,
+  type VerifiedManifest,
+} from "../contracts/index.ts"
+import type { ActionExecutor, ExecutorMap, StepContext, TreeFile } from "./executor.ts"
+import { mergeConfigText } from "./json-merge.ts"
+import { fromResult, txFail, txOk, type TxResult } from "./result.ts"
+import { sha256Of } from "./state.ts"
+import { fileDigest, type StagedFile, type StagingArea } from "./stream.ts"
+
+export interface HubctlSource {
+  /** The release manifest, already verified against the shipped trust root. */
+  readonly manifest: VerifiedManifest
+  /**
+   * The release file for `entry`: its bytes, or the path of a local copy (hubctl's own standalone executable), which
+   * the executor digests and the engine copies in chunks. Either way the executor checks it against the pin.
+   */
+  fetch(entry: ArtifactEntry): Promise<Uint8Array | { readonly path: string }>
+  /** The hubctl currently installed, if any (downgrade policy). */
+  readonly installed?: { readonly version: string; readonly sha256: string }
+  /** The highest security floor this machine has seen. */
+  readonly floor?: string
+  /** Explicit --allow-downgrade. */
+  readonly allowDowngrade?: boolean
+}
+
+export interface HarnessSource {
+  readonly manifest: VerifiedManifest
+  /**
+   * Downloads the pinned file into `staging` (streamed, staging.write) and runs the upstream evidence checks the
+   * action lists (adapter-specific).
+   */
+  fetch(action: InstallHarness, staging: StagingArea): Promise<{ readonly file: StagedFile; readonly evidence: readonly EvidenceResult[] }>
+  /**
+   * Unpacks the verified download into the install tree (adapter-specific): large members are streamed into
+   * `staging` and named as staged files; nothing else is written.
+   */
+  unpack(action: InstallHarness, file: StagedFile, staging: StagingArea): Promise<TxResult<readonly TreeFile[]>>
+  installed?(harness: HarnessID): { readonly version: string; readonly sha256: string } | undefined
+  floor?(harness: HarnessID): string | undefined
+  readonly allowDowngrade?: boolean
+}
+
+/**
+ * v1.1: the typed client for the user's service manager (launchd / systemd --user), supplied by the integrator
+ * (HBS-13). It names a service and manager, never a command; how it reaches the manager is its own business.
+ */
+export interface ServiceControl {
+  deactivate(service: ServiceID, manager: ServiceManagerID): Promise<TxResult<void>>
+  /** Loads a service again (the undo of a deactivation). */
+  activate(service: ServiceID, manager: ServiceManagerID): Promise<TxResult<void>>
+}
+
+export interface BuiltinDeps {
+  /** Embedded or rendered assets by id (write-file). */
+  readonly assets?: (asset: string) => Uint8Array | undefined
+  /** The rendered unit for an install-service action (HBS-13 renders EMBEDDED_ASSETS with serviceArgv). */
+  readonly renderService?: (action: InstallService) => Uint8Array | undefined
+  readonly hubctl?: HubctlSource
+  readonly harness?: HarnessSource
+  /** v1.1: deactivate-service (and its undo). Without it, deactivation is refused at preflight. */
+  readonly services?: ServiceControl
+}
+
+const ok = txOk(undefined)
+const decode = (bytes: Uint8Array) => new TextDecoder().decode(bytes)
+
+export const ensureDirectoryExecutor = (): ActionExecutor<"ensure-directory"> => ({
+  kind: "ensure-directory",
+  plan: (action) => ({ class: "directory", path: action.path }),
+  change: async (action) => txOk({ type: "directory", mode: action.mode }),
+})
+
+/** Bytes whose digest must equal the plan's pin. */
+function pinned(bytes: Uint8Array | undefined, sha256: string, what: string): TxResult<Uint8Array> {
+  if (!bytes) return txFail("not_found", `${what} is not available in this hubctl`)
+  if (sha256Of(bytes) !== sha256) return txFail("integrity_mismatch", `${what} does not match the digest in the plan`)
+  return txOk(bytes)
+}
+
+export const writeFileExecutor = (assets: BuiltinDeps["assets"] = () => undefined): ActionExecutor<"write-file"> => ({
+  kind: "write-file",
+  plan: (action) => ({ class: "file", path: action.path }),
+  check: async (action) => {
+    const r = pinned(assets(action.asset), action.sha256, `asset ${action.asset}`)
+    return r.ok ? ok : r
+  },
+  change: async (action) => {
+    const r = pinned(assets(action.asset), action.sha256, `asset ${action.asset}`)
+    return r.ok ? txOk({ type: "file", bytes: r.value, mode: action.mode, replace: "refuse" }) : r
+  },
+})
+
+function preconditionHolds(ctx: StepContext, precondition: { readonly exists: boolean; readonly sha256?: string }): boolean {
+  const o = ctx.original
+  if (o.symlink) return false
+  return precondition.exists ? o.exists && o.sha256 === precondition.sha256 : !o.exists
+}
+
+export const mergeConfigExecutor = (): ActionExecutor<"merge-config"> => ({
+  kind: "merge-config",
+  plan: (action) => ({ class: "config", path: action.path }),
+  check: async (action, ctx) =>
+    preconditionHolds(ctx, action.precondition) ? ok : txFail("conflict", `${ctx.target} changed since the preview; nothing was overwritten (preview again)`),
+  change: async (action, ctx) => {
+    const text = ctx.current.exists ? decode(ctx.fs.readFile(ctx.target!)) : undefined
+    const merged = mergeConfigText(text, action.format, action.set)
+    if (!merged.ok) return merged
+    if (merged.value === text) return txOk({ type: "none", reason: "already merged" })
+    return txOk({ type: "file", bytes: new TextEncoder().encode(merged.value), mode: ctx.current.mode ?? 0o600, replace: "backup" })
+  },
+})
+
+export const linkExecutableExecutor = (): ActionExecutor<"link-executable"> => ({
+  kind: "link-executable",
+  plan: (action) => ({ class: "link", path: action.path, resolve: { finalMayBeSymlink: true } }),
+  change: async (action, ctx) => {
+    // The link's own path is symlink-checked (it is what gets written). Its target is only the link's text, never
+    // written through, and may lead through a harness's `current` link, which is a symlink by design (§3.6.1).
+    const target = ctx.resolve(action.target, { targetOnly: true })
+    return target.ok ? txOk({ type: "symlink", target: target.value, replace: "backup" }) : target
+  },
+})
+
+export const selectHarnessVersionExecutor = (): ActionExecutor<"select-harness-version"> => ({
+  kind: "select-harness-version",
+  plan: (action) => ({ class: "link", path: action.path, resolve: { finalMayBeSymlink: true } }),
+  change: async (action, ctx) => {
+    const dir = ctx.resolve(action.target)
+    if (!dir.ok) return dir
+    if (ctx.fs.lstat(dir.value)?.kind !== "directory") return txFail("not_found", `${action.harness} ${action.version} is not installed (${dir.value} is not a directory)`)
+    // `current` and the version directory are siblings (contract harnessCurrentRef / harnessVersionRef).
+    return txOk({ type: "symlink", target: action.version, replace: "backup" })
+  },
+})
+
+export const installServiceExecutor = (render: BuiltinDeps["renderService"] = () => undefined): ActionExecutor<"install-service"> => ({
+  kind: "install-service",
+  plan: (action) => ({ class: "service", path: action.path }),
+  check: async (action) => {
+    const r = pinned(render(action), action.sha256, `the ${action.service} ${action.manager} unit`)
+    return r.ok ? ok : r
+  },
+  change: async (action) => {
+    const r = pinned(render(action), action.sha256, `the ${action.service} ${action.manager} unit`)
+    return r.ok ? txOk({ type: "file", bytes: r.value, mode: 0o644, replace: "backup" }) : r
+  },
+})
+
+export const deactivateServiceExecutor = (services?: ServiceControl): ActionExecutor<"deactivate-service"> => ({
+  kind: "deactivate-service",
+  plan: () => ({ class: "external" }),
+  check: async () => (services ? ok : missing("service manager")),
+  change: async (action) => (services ? txOk({ type: "effect", perform: () => services.deactivate(action.service, action.manager) }) : missing("service manager")),
+  undo: async (action) => (services ? services.activate(action.service, action.manager) : missing("service manager")),
+})
+
+export const removeServiceExecutor = (): ActionExecutor<"remove-service"> => ({
+  kind: "remove-service",
+  plan: (action) => ({ class: "service", path: action.path }),
+  check: async (action, ctx) =>
+    !ctx.original.exists || (ctx.original.sha256 === action.sha256 && !ctx.original.symlink)
+      ? ok
+      : txFail("conflict", `${ctx.target} is not the ${action.service} unit hub installed (it changed since); nothing was removed`),
+  change: async (action, ctx) => (ctx.current.exists ? txOk({ type: "remove" }) : txOk({ type: "none", reason: `the ${action.service} unit is already gone` })),
+})
+
+const missing = (what: string) => txFail("internal", `this hubctl was built without a ${what} source`)
+
+export const installArtifactExecutor = (source?: HubctlSource): ActionExecutor<"install-artifact"> => {
+  const entryFor = (action: { readonly target: string; readonly version: string; readonly sha256: string }, host: string): TxResult<ArtifactEntry> => {
+    if (!source) return missing("hubctl release")
+    if (action.target !== host) return txFail("wrong_platform", `the plan installs hubctl for ${action.target}, but this host is ${host}`)
+    const entry = fromResult(selectArtifact(source.manifest, action.target))
+    if (!entry.ok) return entry
+    if (source.manifest.release !== action.version || entry.value.sha256 !== action.sha256)
+      return txFail("integrity_mismatch", `the plan's hubctl ${action.version} is not the artifact the verified ${source.manifest.release} manifest pins`)
+    const decision = fromResult(
+      decideInstall({
+        candidate: { release: source.manifest.release, minimumVersion: source.manifest.minimumVersion, sha256: entry.value.sha256 },
+        installed: source.installed,
+        floor: source.floor,
+        allowDowngrade: source.allowDowngrade,
+      }),
+    )
+    return decision.ok ? entry : decision
+  }
+  return {
+    kind: "install-artifact",
+    plan: (action) => ({ class: "artifact", path: action.path }),
+    check: async (action, ctx) => {
+      const entry = entryFor(action, ctx.host.target)
+      return entry.ok ? ok : entry
+    },
+    change: async (action, ctx) => {
+      const entry = entryFor(action, ctx.host.target)
+      if (!entry.ok) return entry
+      const fetched = await source!.fetch(entry.value)
+      if (fetched instanceof Uint8Array) {
+        const checked = fromResult(checkArtifactBytes(entry.value, { sha256: sha256Of(fetched), size: fetched.byteLength }))
+        if (!checked.ok) return checked
+        return txOk({ type: "file", bytes: fetched, mode: 0o755, replace: "backup" })
+      }
+      const info = ctx.fs.lstat(fetched.path)
+      if (info?.kind !== "file") return txFail("not_found", `${fetched.path} is not a regular file`)
+      const staged = { path: fetched.path, sha256: fileDigest(ctx.fs, fetched.path), size: info.size }
+      const checked = fromResult(checkArtifactBytes(entry.value, { sha256: staged.sha256, size: staged.size }))
+      if (!checked.ok) return checked
+      // The engine copies it in chunks and checks this digest again while it copies.
+      return txOk({ type: "file", staged, mode: 0o755, replace: "backup" })
+    },
+  }
+}
+
+export const installHarnessExecutor = (source?: HarnessSource): ActionExecutor<"install-harness"> => {
+  const pinFor = (action: InstallHarness, host: string) => {
+    if (!source) return missing("harness")
+    if (action.target !== host) return txFail("wrong_platform", `the plan installs ${action.harness} for ${action.target}, but this host is ${host}`)
+    const pin = fromResult(checkHarnessPin(source.manifest, action))
+    if (!pin.ok) return pin
+    const decision = fromResult(
+      decideHarnessInstall(pin.value, { installed: source.installed?.(action.harness) ?? action.previous, floor: source.floor?.(action.harness), allowDowngrade: source.allowDowngrade }),
+    )
+    return decision.ok ? pin : decision
+  }
+  return {
+    kind: "install-harness",
+    plan: (action) => ({ class: "harness", path: action.path }),
+    check: async (action, ctx) => {
+      const pin = pinFor(action, ctx.host.target)
+      return pin.ok ? ok : pin
+    },
+    change: async (action, ctx) => {
+      const pin = pinFor(action, ctx.host.target)
+      if (!pin.ok) return pin
+      const download = await source!.fetch(action, ctx.staging)
+      // The digest the staging area recorded while it wrote the download (never one the source reports).
+      const written = ctx.staging.written(download.file)
+      if (!written) return txFail("internal", `the ${action.harness} source did not download into the transaction's staging area`)
+      // The pinned digest first (mandatory), then the upstream evidence; only verified bytes reach the unpacker.
+      const evidence = fromResult(checkHarnessEvidence(action, written, download.evidence))
+      if (!evidence.ok) return evidence
+      ctx.recordEvidence(evidence.value)
+      const files = await source!.unpack(action, { path: download.file.path, ...written }, ctx.staging)
+      if (!files.ok) return files
+      const seen = new Set<string>()
+      for (const f of files.value) {
+        if (!isSafeRel(f.rel) || seen.has(f.rel) || !Number.isInteger(f.mode) || f.mode < 0 || f.mode > 0o777) return txFail("invalid", `the ${action.harness} archive has an unsafe entry ${JSON.stringify(f.rel)}`)
+        // Unpacked members are files the staging area wrote, with the digest it recorded.
+        if ("staged" in f && ctx.staging.written(f.staged)?.sha256 !== f.staged.sha256) return txFail("invalid", `the ${action.harness} archive's ${JSON.stringify(f.rel)} was not unpacked into the staging area`)
+        seen.add(f.rel)
+      }
+      for (const rel of seen) if ([...seen].some((other) => other.startsWith(`${rel}/`))) return txFail("invalid", `the ${action.harness} archive uses ${rel} as both a file and a directory`)
+      if (seen.size === 0) return txFail("invalid", `the ${action.harness} archive is empty`)
+      return txOk({ type: "tree", files: files.value, mode: 0o755 })
+    },
+  }
+}
+
+/** The built-in executors for the local kinds; adapters add the rest (see executor.ts). */
+export function builtinExecutors(deps: BuiltinDeps): ExecutorMap {
+  return {
+    "ensure-directory": ensureDirectoryExecutor(),
+    "write-file": writeFileExecutor(deps.assets),
+    "merge-config": mergeConfigExecutor(),
+    "link-executable": linkExecutableExecutor(),
+    "select-harness-version": selectHarnessVersionExecutor(),
+    "install-service": installServiceExecutor(deps.renderService),
+    "deactivate-service": deactivateServiceExecutor(deps.services),
+    "remove-service": removeServiceExecutor(),
+    "install-artifact": installArtifactExecutor(deps.hubctl),
+    "install-harness": installHarnessExecutor(deps.harness),
+  }
+}