@huynle/hub 0.7.1 → 0.7.2

package/packages/cli/src/bootstrap/profiles/upgrade.ts

@@ -0,0 +1,276 @@
+// Upgrade and downgrade planning, under the contract's downgrade policy.
+//
+// Profiles. planProfileChange compares two profiles as sets of capabilities (harnesses, runtimes, services,
+// launching, escalation). Adding is an upgrade. Removing anything is a downgrade and needs explicit consent
+// (downgrade_rejected otherwise, like --allow-downgrade for artifacts). v1.1: given the host's service manager and
+// the units hub installed (installedServiceUnits), a removed service is planned as typed deactivate-service and
+// remove-service actions (the unit only while it is exactly what hub installed). Everything else removed (harnesses,
+// runtimes, launching, escalation) has no typed uninstall and is reported as retained: left in place until a
+// rollback (history.ts) or the user removes it.
+//
+// Catalog revisions. rebaseProfile moves a profile from the defaults it was made from (base) to a newer catalog's
+// (next), field by field: a field still equal to the old default follows the new one; a field the user changed is
+// kept and reported. New defaults never raise escalation or opt in to a runtime (OpenShell is opt-in): such changes
+// are refused and reported. A rebase that would produce an invalid profile fails instead of guessing. v1.1: the base
+// is found by the profile's own `revision` in the catalogs given (or checked against it when passed explicitly), a
+// rebase never goes to an older revision, and the result records the new revision.
+//
+// Harness versions. planHarnessVersions decides, per desired harness, against the pins of a verified manifest and
+// the versions hub installed (from the history), with decideHarnessInstall: nothing below the security floor,
+// older pins only with explicit consent, the same version with other bytes is tampering. A harness the user
+// installed another way is never replaced. Each install, upgrade or downgrade carries its install-harness action,
+// recording the version it replaces so a rollback can restore it.
+import {
+  checkHarnessPin,
+  Checker,
+  canonicalJSON,
+  decideHarnessInstall,
+  EMBEDDED_ASSETS,
+  fail,
+  HARNESS_ORDER,
+  ok,
+  validateProfile,
+  type HarnessID,
+  type Action,
+  type InstallHarness,
+  type InstallKind,
+  type Profile,
+  type Result,
+  type ServiceID,
+  type ServiceManagerID,
+  type VerifiedManifest,
+} from "../contracts/index.ts"
+import { PROFILE_CATALOG, type ProfileCatalog } from "./catalog.ts"
+import type { DesiredState } from "./desired.ts"
+import type { InstalledHarness } from "./history.ts"
+
+/** "harness:<id>", "runtime:<id>", "service:<id>", "launch", "escalation:explicit". */
+export type Capability = string
+
+export interface ProfileChange {
+  readonly from: Profile["id"]
+  readonly to: Profile["id"]
+  readonly direction: "same" | "upgrade" | "downgrade"
+  readonly adds: readonly Capability[]
+  readonly removes: readonly Capability[]
+  /** Removed capabilities hub leaves in place (no typed uninstall): undo them with a rollback. */
+  readonly retained: readonly Capability[]
+  /** v1.1: the typed steps that remove what can be removed (services), in execution order. */
+  readonly actions: readonly Action[]
+}
+
+/** v1.1: what planProfileChange needs to plan removing services. */
+export interface ServiceFacts {
+  /** The host's user service manager. */
+  readonly manager: ServiceManagerID
+  /** The digest of each unit hub installed and still owns (installedServiceUnits). */
+  readonly installed: Partial<Record<ServiceID, string>>
+}
+
+const UNIT_ROOT: Readonly<Record<ServiceManagerID, "launch-agents" | "systemd-user">> = { launchd: "launch-agents", "systemd-user": "systemd-user" }
+
+/** Deactivates, then removes (when hub knows the unit it installed), one service of a removed component. */
+function removeServiceActions(service: ServiceID, facts: ServiceFacts): Action[] {
+  const actions: Action[] = [
+    { id: `deactivate-${service}`, kind: "deactivate-service", escalation: "user", summary: `Unload the hub ${service} service (profile downgrade)`, service, manager: facts.manager },
+  ]
+  const asset = EMBEDDED_ASSETS[`service/${facts.manager}/${service}`]
+  const sha256 = facts.installed[service]
+  if (asset && sha256)
+    actions.push({
+      id: `remove-${service}`,
+      kind: "remove-service",
+      escalation: "user",
+      summary: `Remove the hub ${service} ${facts.manager} unit (profile downgrade)`,
+      service,
+      manager: facts.manager,
+      path: { root: UNIT_ROOT[facts.manager], rel: asset.installAs },
+      sha256,
+    })
+  return actions
+}
+
+function capabilities(p: Profile): Capability[] {
+  return [
+    ...HARNESS_ORDER.filter((h) => p.harnesses.includes(h)).map((h) => `harness:${h}`),
+    ...p.runtimes.map((r) => `runtime:${r}`),
+    ...p.services.map((s) => `service:${s}`),
+    ...(p.launch.enabled ? ["launch"] : []),
+    ...(p.escalation === "explicit" ? ["escalation:explicit"] : []),
+  ]
+}
+
+export function planProfileChange(fromDoc: unknown, toDoc: unknown, options: { readonly allowDowngrade?: boolean; readonly services?: ServiceFacts } = {}): Result<ProfileChange> {
+  const c = new Checker()
+  const from = validateProfile(fromDoc)
+  const to = validateProfile(toDoc)
+  c.merge("/from", from)
+  c.merge("/to", to)
+  if (!from.ok || !to.ok) return c.result(undefined)
+  const before = capabilities(from.value)
+  const after = capabilities(to.value)
+  const adds = after.filter((x) => !before.includes(x))
+  const removes = before.filter((x) => !after.includes(x))
+  const direction = removes.length > 0 ? "downgrade" : adds.length > 0 ? "upgrade" : "same"
+  if (direction === "downgrade" && !options.allowDowngrade)
+    return fail("/to", "downgrade_rejected", `${to.value.id} removes ${removes.join(", ")}; pass --allow-downgrade to change to it`)
+  const actions: Action[] = []
+  const removed = new Set<Capability>()
+  if (options.services)
+    for (const capability of removes) {
+      if (!capability.startsWith("service:")) continue
+      const service = capability.slice("service:".length) as ServiceID
+      const planned = removeServiceActions(service, options.services)
+      actions.push(...planned)
+      // A service is gone only once its unit is removed too; a deactivated unit hub never recorded stays.
+      if (planned.some((a) => a.kind === "remove-service")) removed.add(capability)
+    }
+  // Deactivate everything first, then remove the units (the plan rule: a service is deactivated before it is removed).
+  actions.sort((a, b) => Number(a.kind === "remove-service") - Number(b.kind === "remove-service"))
+  return ok({ from: from.value.id, to: to.value.id, direction, adds, removes, retained: removes.filter((x) => !removed.has(x)), actions })
+}
+
+const REBASED_FIELDS = ["harnesses", "runtimes", "services", "launch", "escalation", "enrollment"] as const
+export type RebasedField = (typeof REBASED_FIELDS)[number]
+
+export interface RebasedProfile {
+  readonly profile: Profile
+  /** Fields the user had changed from the old defaults: kept. */
+  readonly kept: readonly RebasedField[]
+  /** Fields that followed the new defaults. */
+  readonly updated: readonly RebasedField[]
+  /** New defaults refused because they would raise privilege or opt in to a runtime. */
+  readonly refused: readonly RebasedField[]
+}
+
+// An absent optional field (enrollment) compares as null.
+const same = (a: unknown, b: unknown) => canonicalJSON(a ?? null) === canonicalJSON(b ?? null)
+
+export interface RebaseInput {
+  readonly current: unknown
+  /** The defaults `current` was made from. Optional when `current.revision` names one of `catalogs`. */
+  readonly base?: unknown
+  readonly next: unknown
+  /** v1.1: catalogs (any revisions) to find the base in by `current.revision`; default: this hubctl's catalog. */
+  readonly catalogs?: readonly ProfileCatalog[]
+}
+
+export function rebaseProfile(input: RebaseInput): Result<RebasedProfile> {
+  const c = new Checker()
+  const current = validateProfile(input.current)
+  const next = validateProfile(input.next)
+  c.merge("/current", current)
+  c.merge("/next", next)
+  if (!current.ok || !next.ok) return c.result(undefined)
+  let baseDoc = input.base
+  const revision = current.value.revision
+  if (baseDoc === undefined) {
+    if (revision === undefined) return fail("/current/revision", "missing_field", "the profile records no catalog revision; pass the defaults it was made from as base")
+    const catalog = (input.catalogs ?? [PROFILE_CATALOG]).find((k) => k.revision === revision)
+    if (!catalog) return fail("/current/revision", "invalid_value", `this hubctl does not know catalog revision ${revision}`)
+    baseDoc = catalog.profiles[current.value.id]
+  }
+  const base = validateProfile(baseDoc)
+  c.merge("/base", base)
+  if (!base.ok) return c.result(undefined)
+  const [cur, old, neu] = [current.value, base.value, next.value]
+  if (cur.id !== old.id || cur.id !== neu.id) return fail("/next/id", "invalid_value", "a rebase keeps the profile; change profiles with planProfileChange")
+  if (revision !== undefined && old.revision !== undefined && old.revision !== revision)
+    return fail("/base/revision", "inconsistent", `the profile was made from catalog revision ${revision}, not ${old.revision}`)
+  if (revision !== undefined && neu.revision !== undefined && neu.revision < revision)
+    return fail("/next/revision", "downgrade_rejected", `catalog revision ${neu.revision} is older than the profile's ${revision}`)
+
+  const result: Record<string, unknown> = { ...cur }
+  const kept: RebasedField[] = []
+  const updated: RebasedField[] = []
+  const refused: RebasedField[] = []
+  for (const field of REBASED_FIELDS) {
+    if (!same(cur[field], old[field])) {
+      kept.push(field)
+      continue
+    }
+    if (same(cur[field], neu[field])) continue
+    const raises = (field === "escalation" && neu.escalation === "explicit") || (field === "runtimes" && neu.runtimes.some((r) => !cur.runtimes.includes(r)))
+    if (raises) refused.push(field)
+    else {
+      result[field] = neu[field]
+      updated.push(field)
+    }
+  }
+  if (neu.revision !== undefined) result.revision = neu.revision
+  const profile = validateProfile(result)
+  if (!profile.ok) return profile
+  return ok({ profile: profile.value, kept, updated, refused })
+}
+
+export type HarnessVersionDecision = "install" | "upgrade" | "downgrade" | "keep" | "keep-user-managed"
+
+export interface HarnessVersionStep {
+  readonly harness: HarnessID
+  readonly decision: HarnessVersionDecision
+  /** The version there now (when known). */
+  readonly from?: string
+  /** The pinned version. */
+  readonly to?: string
+  /** For install, upgrade and downgrade. */
+  readonly action?: InstallHarness
+}
+
+export interface HarnessVersionInput {
+  readonly desired: DesiredState
+  readonly manifest: VerifiedManifest
+  /** What hub installed, from the history (installedHarnesses). */
+  readonly installed: Partial<Record<HarnessID, InstalledHarness>>
+  /** The highest harness floors this machine has seen. */
+  readonly floors?: Partial<Record<HarnessID, string>>
+  readonly allowDowngrade?: boolean
+}
+
+/** Where hub installs a pinned harness version (a versioned directory under the data root). */
+export const harnessInstallPath = (harness: HarnessID, version: string) => ({ root: "data", rel: `hub/harnesses/${harness}/${version}` }) as const
+
+const VERB: Readonly<Record<Exclude<InstallKind, "reinstall">, string>> = { install: "Install", upgrade: "Upgrade", downgrade: "Downgrade" }
+
+export function planHarnessVersions(input: HarnessVersionInput): Result<HarnessVersionStep[]> {
+  const c = new Checker()
+  const { desired, manifest } = input
+  const steps: HarnessVersionStep[] = []
+  desired.harnesses.forEach((h, i) => {
+    const at = `/harnesses/${i}`
+    if (h.owner === "user") return void steps.push({ harness: h.id, decision: "keep-user-managed", ...(h.version ? { from: h.version } : {}) })
+    const inst = h.presence === "installed" ? input.installed[h.id] : undefined
+    if (h.presence === "installed") {
+      if (!inst) return c.add(at, "inconsistent", `${h.id} was installed by hub, but no committed transaction records it; recover or reinstall`)
+      if (h.version !== undefined && h.version !== inst.version) return c.add(at, "inconsistent", `${h.id} is ${h.version}, not the ${inst.version} hub installed; verify it or roll back`)
+    }
+    const pin = manifest.harnesses.find((p) => p.harness === h.id && p.target === desired.target)
+    if (!pin) {
+      if (inst) return void steps.push({ harness: h.id, decision: "keep", from: inst.version })
+      return c.add(at, "unpinned_artifact", `hub ${manifest.release} pins no ${h.id} for ${desired.target}`)
+    }
+    const decided = decideHarnessInstall(pin, { ...(inst ? { installed: { version: inst.version, sha256: inst.sha256 } } : {}), ...(input.floors?.[h.id] ? { floor: input.floors[h.id] } : {}), allowDowngrade: input.allowDowngrade })
+    if (!decided.ok) return c.merge(at, decided)
+    if (decided.value === "reinstall") return void steps.push({ harness: h.id, decision: "keep", from: pin.version, to: pin.version })
+    const action: InstallHarness = {
+      id: `install-${h.id}`,
+      kind: "install-harness",
+      escalation: "user",
+      summary: `${VERB[decided.value]} ${h.id} ${pin.version} for ${pin.target} (pinned by hub ${manifest.release})`,
+      harness: h.id,
+      version: pin.version,
+      target: pin.target,
+      source: { manifest: manifest.release, url: pin.url, file: pin.file },
+      size: pin.size,
+      sha256: pin.sha256,
+      evidence: [...pin.evidence],
+      path: harnessInstallPath(h.id, pin.version),
+      owner: "hub",
+      rollback: "restore-previous",
+      ...(inst ? { previous: { version: inst.version, sha256: inst.sha256 } } : {}),
+    }
+    const pinned = checkHarnessPin(manifest, action)
+    if (!pinned.ok) return c.merge(at, pinned)
+    steps.push({ harness: h.id, decision: decided.value, ...(inst ? { from: inst.version } : {}), to: pin.version, action })
+  })
+  return c.result(steps)
+}

package/packages/cli/src/bootstrap/profiles/versions.ts

@@ -0,0 +1,50 @@
+// Profile document versions. A persisted profile is read through the contract's migration hook (migrateProfile),
+// one version at a time, and the steps taken are reported so the caller can say "migrated from v0". A document from
+// a newer hubctl is refused (unsupported_version), never read as if it were current; a version no chain of
+// migrations reaches is unmigratable. Negotiation picks the highest version both sides understand.
+import { fail, isRecord, migrateProfile, ok, PROFILE_MIGRATIONS, PROFILE_VERSION, type Profile, type ProfileMigrations, type Result } from "../contracts/index.ts"
+
+export interface MigrationStep {
+  readonly from: number
+  readonly to: number
+}
+
+export interface LoadedProfile {
+  readonly profile: Profile
+  /** The version the document had on disk. */
+  readonly from: number
+  /** The migrations applied, oldest first (empty for a current document). */
+  readonly steps: readonly MigrationStep[]
+}
+
+/** Reads a profile document of any readable version; the input is never modified. */
+export function loadProfile(raw: unknown, migrations: ProfileMigrations = PROFILE_MIGRATIONS): Result<LoadedProfile> {
+  const steps: MigrationStep[] = []
+  const recording: Record<number, (doc: Record<string, unknown>) => unknown> = {}
+  for (const [key, step] of Object.entries(migrations))
+    recording[Number(key)] = (doc) => {
+      const next = step(structuredClone(doc))
+      if (isRecord(next) && Number.isInteger(next.version)) steps.push({ from: doc.version as number, to: next.version as number })
+      return next
+    }
+  const result = migrateProfile(raw, recording)
+  if (!result.ok) return result
+  return ok({ profile: result.value, from: (raw as { version: number }).version, steps })
+}
+
+/** Every profile version this hubctl can read, ascending: the current one and each older one with an unbroken chain. */
+export function supportedProfileVersions(migrations: ProfileMigrations = PROFILE_MIGRATIONS): number[] {
+  const versions = [PROFILE_VERSION]
+  for (let v = PROFILE_VERSION - 1; typeof migrations[v] === "function"; v--) versions.unshift(v)
+  return versions
+}
+
+/** The highest offered version this hubctl can read. */
+export function negotiateProfileVersion(offered: readonly number[], migrations: ProfileMigrations = PROFILE_MIGRATIONS): Result<number> {
+  if (offered.length === 0 || !offered.every((v) => Number.isInteger(v))) return fail("", "invalid_value", "offer at least one integer profile version")
+  const supported = new Set(supportedProfileVersions(migrations))
+  const common = offered.filter((v) => supported.has(v))
+  if (common.length > 0) return ok(Math.max(...common))
+  if (offered.some((v) => v > PROFILE_VERSION)) return fail("", "unsupported_version", `profile versions ${offered.join(", ")} are newer than this hubctl understands (${PROFILE_VERSION}); upgrade hubctl`)
+  return fail("", "unmigratable", `no migration reaches profile version ${PROFILE_VERSION} from ${offered.join(", ")}`)
+}

package/packages/cli/src/bootstrap/release/README.md

@@ -0,0 +1,115 @@
+# Standalone hubctl releases
+
+This directory builds, signs and verifies the standalone `hubctl` (contracts §3.6, §3.7, I5, I6 in
+`docs/bootstrap-contracts.md`). The central hub server binaries (`scripts/build-binaries.sh`) are separate and
+unchanged.
+
+| File | Role |
+|---|---|
+| `verify.ts` | The installer's checks on a downloaded hubctl: signature (trust root), exact target, size and digest, downgrade policy. |
+| `manifest.ts` | Builds the manifest body (every supported target, or an explicit `targets` subset; matrix order; harness pins) and signs it (ed25519, detached, over `manifestPayload`). |
+| `pins.ts` | The reviewed harness pin list (`harness-pins.json`): format, validation, re-download check. |
+| `trust-root.ts` | The trust root embedded at build time (`--define HUBCTL_TRUST_ROOT=…`), never read at run time. |
+| `assets.ts` | The six service templates of `EMBEDDED_ASSETS`, imported as text so the binary carries them. |
+| `cli.ts` | The release tool behind `bun scripts/hubctl-release.ts build\|manifest\|sign\|verify\|trust-root`. |
+
+Everything except `build` needs only bun and node's built-ins, so the signing job installs no npm packages.
+
+## Building
+
+```sh
+scripts/build-hubctl.sh                        # dev build: every supported target, no trust root
+scripts/build-hubctl.sh linux-x64              # one target
+scripts/build-hubctl.sh --require-trust-root   # release build: refuses without trust-root.json
+scripts/build-hubctl.sh linux-x64 --outdir /tmp/out   # binaries and checksums in /tmp/out
+```
+
+Outputs: `dist/hubctl-<target>` and `dist/HUBCTL_SHA256SUMS` (in `--outdir` instead, when given). x64 targets are
+compiled against Bun's `-baseline` runtime, which needs no AVX2 (older CPUs, QEMU's default `kvm64` model). The supported targets are `darwin-arm64`,
+`darwin-x64`, `linux-x64` and `linux-arm64` (glibc). Windows and musl are refused with their reasons. The
+binary is the whole program: it runs without bun, node or the repository, and a `hub` link to it is the same
+command surface. A build without a trust root cannot verify any release (`shippedTrustRoot` fails closed).
+
+## The harness pin list (`harness-pins.json`)
+
+```json
+{ "schema": "hub.harness-pin-list", "version": 1,
+  "pins": [ { "pin": { "harness": "opencode", "version": "…", "target": "darwin-arm64", "url": "https://…/file.zip",
+                       "file": "file.zip", "size": 123, "sha256": "sha256:…", "evidence": [] },
+              "review": { "by": "github-handle", "on": "2026-10-28",
+                          "checked": ["upstream-release", "digest-redownloaded", "evidence-listed"] } } ] }
+```
+
+`pin` is exactly a manifest `HarnessPin`. Each pin is checked with the manifest's own rules: a supported
+target, an exact version, https, a plain file name, one pin per harness and target, and only evidence that
+harness can offer. On top of that, the file must be the URL's last path segment, the URL may not carry
+credentials, a query or a fragment, and nothing secret-shaped may appear anywhere in the list.
+
+The list is empty until the harness adapter tasks confirm the upstream sources (HBS-06 for OpenCode 2.x).
+
+**Review process**
+
+1. A pin changes only through a pull request that touches `harness-pins.json`. The reviewer is not the author.
+2. The reviewer fills in `review`:
+   - `by`: their GitHub handle.
+   - `on`: the review date.
+   - `checked`: all three checks.
+     - `upstream-release`: the URL is the upstream's own release asset for exactly this version and target.
+     - `digest-redownloaded`: they downloaded the file themselves and computed its size and sha256, for example
+       with `curl -fsSL <url> | shasum -a 256`.
+     - `evidence-listed`: `evidence` lists exactly the upstream evidence published for that file (§5 of the
+       contracts doc).
+3. CI validates the file (`bootstrap-release-pins.test.ts`).
+4. At release time, the `hubctl-sign` job downloads every pinned file again and refuses to sign on any size or
+   digest mismatch. The signature never vouches for a file that nobody fetched during that release.
+
+## The release key (decision Q5)
+
+There is one ed25519 key, with threshold 1. The private key is the `HUB_RELEASE_SIGNING_KEY` secret of the
+`hubctl-release` GitHub environment. Only the `hubctl-sign` job uses that environment, and only its Sign step
+sees the secret. The key is PKCS#8, either PEM or base64 DER. No key is ever committed.
+
+A maintainer sets the key up once, on their own machine. This has not been done yet:
+
+```sh
+openssl genpkey -algorithm ed25519 -out release-key.pem      # keep it offline
+HUB_RELEASE_SIGNING_KEY="$(cat release-key.pem)" bun scripts/hubctl-release.ts trust-root --key-id hub-release-1 \
+  > packages/cli/src/bootstrap/release/trust-root.json       # public key only; commit through a reviewed PR
+gh secret set HUB_RELEASE_SIGNING_KEY --env hubctl-release < release-key.pem
+gh variable set HUBCTL_RELEASE --body true                   # enables the hubctl release jobs
+gh variable set HUBCTL_MINIMUM_VERSION --body 0.0.0           # the security floor (optional, default 0.0.0)
+```
+
+To rotate the key, publish a version-2 trust root signed by the current key (`rotateTrustRoot`), with the old key
+`retired`, or `revoked` if it was compromised. Then update `trust-root.json` and the secret.
+
+## The release workflow (`.github/workflows/release.yml`)
+
+The hubctl jobs are added alongside the existing jobs. They run only when `HUBCTL_RELEASE` is `true`.
+
+1. `hubctl` (needs `test`): `scripts/build-hubctl.sh --require-trust-root` cross-compiles all four targets.
+   Then it smoke-tests `linux-x64` with an empty `PATH` (no bun or node): `--version` must equal the CLI
+   version, and `hub --help` must equal `hubctl --help`.
+2. `hubctl-sign` (needs `hubctl`, environment `hubctl-release`, no npm install):
+   - `manifest` re-downloads the pins and writes the body. `issuedAt` is the tagged commit's time.
+   - `sign` signs the body and verifies it against `trust-root.json`. A wrong secret writes nothing.
+   - `verify --dist dist` runs the installer's checks on every artifact.
+3. `hubctl-publish` (needs the existing `release` job and `hubctl-sign`): it verifies again, then attaches
+   `hubctl-*`, `hubctl-manifest.json` and `HUBCTL_SHA256SUMS` to the GitHub release.
+
+## Verifying by hand
+
+```sh
+bun scripts/hubctl-release.ts verify --manifest hubctl-manifest.json --target linux-x64 --file hubctl-linux-x64
+```
+
+The exit code is 0 when the artifact is accepted and 11 when it is rejected: `signature_invalid`, `wrong_platform`,
+`integrity_mismatch`, `downgrade_rejected` or `below_security_floor`. Pass `--installed V --installed-sha256 D`,
+`--floor V` and `--allow-downgrade` to apply the downgrade policy.
+
+## A partial release (some targets only)
+
+`manifest`, `sign` and `verify --dist` take `--targets T,…` (e.g. `--targets linux-x64`) to list exactly the
+targets a test or partial release ships. Each listed target must be built and is checked in full; an artifact for
+any other target is refused. `sign` refuses a partial body unless `--targets` names the same list, so a partial
+release is never signed by accident. Without `--targets`, every supported target is required.

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

@@ -0,0 +1,39 @@
+// The embedded-asset bundle: the six service templates of EMBEDDED_ASSETS (contracts §3.7, I2), imported as text so
+// `bun build --compile` (and the npm bundle) carry them inside the program. A standalone hubctl never reads
+// scripts/ at run time; node.ts / spoke-services.ts render from embeddedAsset(id).text (wired by HBS-13).
+//
+// Each import must match EMBEDDED_ASSETS[id].source; the release tests check every entry byte for byte.
+import { EMBEDDED_ASSETS, type EmbeddedAsset } from "../contracts/index.ts"
+import { digestBytes } from "./verify.ts"
+import launchdNode from "../../../../../scripts/io.github.huynle.hub-node.plist" with { type: "text" }
+import systemdNode from "../../../../../scripts/hub-node.service" with { type: "text" }
+import launchdClaude from "../../../../../scripts/io.github.huynle.hub-claude-code.plist" with { type: "text" }
+import systemdClaude from "../../../../../scripts/hub-claude-code.service" with { type: "text" }
+import launchdCodex from "../../../../../scripts/io.github.huynle.hub-codex-spoke.plist" with { type: "text" }
+import systemdCodex from "../../../../../scripts/hub-codex-spoke.service" with { type: "text" }
+
+export type AssetID = keyof typeof EMBEDDED_ASSETS
+
+/** The template text of every embedded asset, by EMBEDDED_ASSETS id. */
+export const EMBEDDED_TEXT: Readonly<Record<string, string>> = Object.freeze({
+  "service/launchd/node": launchdNode,
+  "service/systemd-user/node": systemdNode,
+  "service/launchd/claude-code": launchdClaude,
+  "service/systemd-user/claude-code": systemdClaude,
+  "service/launchd/codex-spoke": launchdCodex,
+  "service/systemd-user/codex-spoke": systemdCodex,
+})
+
+export interface EmbeddedText {
+  readonly asset: EmbeddedAsset
+  readonly text: string
+  /** "sha256:<hex>" of the template's UTF-8 bytes (a write-file action pins the rendered result instead). */
+  readonly sha256: string
+}
+
+/** An embedded template with its contract entry and digest; undefined for any other id. */
+export function embeddedAsset(id: string): EmbeddedText | undefined {
+  if (!Object.hasOwn(EMBEDDED_ASSETS, id) || !Object.hasOwn(EMBEDDED_TEXT, id)) return undefined
+  const text = EMBEDDED_TEXT[id]!
+  return { asset: EMBEDDED_ASSETS[id]!, text, sha256: digestBytes(new TextEncoder().encode(text)).sha256 }
+}