@jr2/orchestrator 0.2.1 → 0.4.1

package/src/config.ts

@@ -21,11 +21,12 @@ import { join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { z } from "zod";
 import { repoIdentity } from "./repo-identity.ts";
+import { assertSize, type Size } from "./size.ts";
 
 // ------------------------------------------------------------------------------------------------
 // `git.credentials` (ADR-0051): how the cluster authenticates to a Repo, and the fence.
 //
-// A Repo is identified by its url and nothing in this file names one (CONTEXT.md "Repo"). What
+// A Repo is identified by its url and nothing in this file names one (GLOSSARY.md "Repo"). What
 // the config declares is CREDENTIALS, matched by prefix on the identity — the Argo and Flux shape.
 // The Orchestrator resolves the entry when it creates a Repo CR and writes a `secretRef`; the
 // cache agent reads only that. The list is also the fence: a per-run url (run input, a ticket
@@ -38,10 +39,25 @@ import { repoIdentity } from "./repo-identity.ts";
 export type GitCredential = {
   /** A prefix on the identity (`github.com/ourorg/`), or `*` for everything. */
   match: string;
-  /** Env var name holding an HTTPS token; `jr2 up` materializes its value into the Instance Secret. */
+  /** Env var name holding an HTTPS token; `jr2 up` writes its value into the entry's clone Secret
+   * (`jr2-git-<hash>`), which the cache agent spends. The Orchestrator never holds it (ADR-0068). */
   token?: string;
   /** A Secret (Flux key names: `identity`, `identity.pub`, `known_hosts`) holding a deploy key. */
   sshKey?: string;
+  /** The credential a `push()` spends (ADR-0051, ADR-0067), when it is not the clone credential: an
+   * ssh key (a Secret of `sshKey`'s shape) or a token (an env var, as `token`). Absent, the clone
+   * credential pushes; an entry with neither admits a clone, never a push. A token goes Basic
+   * through a credential helper only. */
+  push?: { sshKey: string } | { token: string };
+  /** The key a `push({ sign: true })` signs with, and the committer it signs as (ADR-0067): an ssh
+   * key (a Secret with `identity`) by default, or a GPG key (a Secret with `private.asc`, no
+   * passphrase). Explicit: an auth key is never reused as a signing key. The committer's email must
+   * belong to the forge account that holds the key, or the forge shows the signature unverified. */
+  sign?: { sshKey: string; name: string; email: string } | { gpgKey: string; name: string; email: string };
+  /** Who an unsigned `push({ squash: true })` is committed by (ADR-0067): the squashed commit is
+   * new, and without `sign` no signer names its committer. Its date is the Effector's clock; the
+   * author line stays the Agent's. A signed push's committer is the signer's. */
+  committer?: { name: string; email: string };
 };
 
 export type GitConfig = {
@@ -63,7 +79,7 @@ export function matchCredential(identity: string, list: readonly GitCredential[]
 }
 
 /** The Secret a Repo CR's `secretRef` names for `url` under `entry`, picked by the url's scheme:
- * https/http spend a token (a Secret the Orchestrator derives from the env var), ssh spends the
+ * https/http spend a token (the clone Secret `jr2 up` writes from the env var), ssh spends the
  * named deploy-key Secret. `undefined` when no entry, no applicable field, or a scheme that carries
  * no credential (`git://`, a local path) — the clone is anonymous. */
 export function credentialSecretFor(
@@ -105,6 +121,8 @@ export type HarnessEnvVar = {
 /** A whole-Secret/ConfigMap env injection (corev1.EnvFromSource) for the Harness container —
  * e.g. `{ secretRef: { name: "anthropic" } }` to hand a real Harness its model API key. */
 export type HarnessEnvFromSource = {
+  /** Put before every key's name, as corev1 does. */
+  prefix?: string;
   secretRef?: { name: string };
   configMapRef?: { name: string };
 };
@@ -136,8 +154,9 @@ export type HarnessProvider = {
   /** The endpoint — reachable FROM PODS (`localhost` never is; a LAN address works on kind).
    * Deployment-varying → resolve from env (`.env`), never hardcode (ADR-0019). */
   baseUrl: string;
-  /** API key, when the endpoint wants one. May read `process.env` — `jr2 up` materializes config
-   * env values into the instance's Secret; the literal never lands in a manifest (ADR-0019).
+  /** API key, when the endpoint wants one. May read `process.env`. It is a held secret
+   * (ADR-0059): `jr2 up` gives the value to the Custodian alone, bound to `baseUrl`'s host, and the
+   * Harness container holds only its Stand-in. So `baseUrl` must be `https://` when this is set.
    * Genuinely optional: an unauthenticated endpoint needs none (the Harness sends the wire
    * library's placeholder, which vLLM/Ollama ignore). */
   apiKey?: string;
@@ -153,6 +172,52 @@ export type HarnessProvider = {
   models?: Record<string, HarnessProviderModel>;
 };
 
+/** Where one of pi's catalog providers sends its calls (ADR-0059) — reach, not a model choice
+ * (ADR-0018). The catalog keeps every model fact (limits, cost, thinking levels); this changes only
+ * the endpoint, for a gateway that serves the provider's own API (LiteLLM, for example). */
+export type CatalogReach = {
+  /** Replaces `model.baseUrl` for every model of this provider — the WHOLE base the provider's API
+   * appends to (`https://litellm.corp.example` for `anthropic`, which appends `/v1/messages`;
+   * `https://litellm.corp.example/v1` for `openai`). HTTPS only. Deployment-varying → `.env`. */
+  baseUrl: string;
+};
+
+/**
+ * One secret of the Instance (ADR-0059's entry shape, ADR-0068's list). Its placement is READ, never
+ * declared, and naming is placement: a pod gets the secrets something in it names. A Held secret is
+ * one a Harness pod names — a `workspace()` lists it under `secrets: [...]`, or it is a known model
+ * key the provider of an Agent whose Turns run there reads — and there the Harness container's env
+ * carries its Stand-in, `jr2-held-<name>`, and that pod's Custodian puts the value into requests
+ * toward `hosts` alone. An entry an Effect names with `secret("name")` is an Effect secret, a file in
+ * that Effect's Effector. Both is both, and `jr2 up` reports it per pod; an entry nothing names goes
+ * nowhere, and `jr2 up` warns. `hosts`, `headers` and `paths` are the binding, never the placement.
+ */
+export type SecretEntry = {
+  /** As a Held secret, the env var the Harness container sees — `[A-Z_][A-Z0-9_]*`, holding the
+   * Stand-in. As an Effect secret, the name `secret("name")` names and the Effector's file. */
+  name: string;
+  /** The value as a literal, usually read from `process.env`/`.env`. `jr2 up` writes it into the
+   * Secret of each placement that names it — `jr2-held-secrets-<pod>` (that pod's Custodian's),
+   * `jr2-instance-effector` — and nowhere else. Exactly one of `value`/`valueFrom`. */
+  value?: string;
+  /** Or a key of a Secret you manage (Sealed Secrets, External Secrets). `jr2 up` checks that the
+   * Secret and key exist; each placement mounts that one key as a file, and no other container does. */
+  valueFrom?: { secretKeyRef: { name: string; key: string } };
+  /** Where the value may go as a Held secret — its binding, not its placement. Each entry is `host`,
+   * `host:port`, or an `https://`
+   * URL (its host and port are taken; the path is ignored). Exact DNS names or IP literals; no
+   * wildcards. Port default 443. A known model-key name (`MODEL_KEYS`) may leave it out: it then
+   * goes to the one host that provider's calls go to. */
+  hosts?: readonly string[];
+  /** Request headers the Stand-in is swapped in, lowercase. Default
+   * `["authorization", "x-api-key", "x-goog-api-key", "api-key"]`. */
+  headers?: readonly string[];
+  /** Optional path prefixes the value may be sent to (`/v1/messages`). Absent → every path. A
+   * gateway key that can reach admin routes (a LiteLLM key that can mint keys) should narrow this:
+   * a key minted through the Custodian is a key the Agent can take away. */
+  paths?: readonly string[];
+};
+
 /** The agent-runtime section (ADR-0018): what the stock Harness image consumes alongside the
  * Agent definition each Turn hands it (ADR-0049). Moved out of `sandbox` deliberately — `sandbox`
  * is pod transport (it still CARRIES this env to the Harness container), but model concerns are
@@ -164,20 +229,25 @@ export type HarnessProvider = {
  * One definition value may still be carried by several Machines, so the variation that matters is
  * per-definition and per-invocation, which one global default serves not at all. */
 export type HarnessConfig = {
-  /** Custom model provider, preflighted from inside the cluster by `jr2 up` (ADR-0019). */
+  /** Custom model provider, preflighted from inside the cluster by `jr2 up` (ADR-0019). Its
+   * `apiKey` is a held secret, `JR2_PROVIDER_API_KEY`, bound to `baseUrl`'s host (ADR-0059). */
   provider?: HarnessProvider;
-  /** Env vars for the Harness container (Agent creds, e.g. ANTHROPIC_API_KEY). Values read from
-   * `process.env`/`.env` are materialized into the instance-owned Secret by `jr2 up`. */
+  /** pi catalog providers whose calls go somewhere else, keyed by the catalog provider id
+   * (`anthropic`, `openai`, ...) — a gateway that serves the provider's own API (ADR-0059). */
+  catalog?: Readonly<Record<string, CatalogReach>>;
+  /** Env vars for the Harness container. Values read from `process.env`/`.env` are materialized
+   * into the instance-owned Secret by `jr2 up`. The Agent can read every one of them, so a known
+   * model key here is refused — it goes in the top-level `secrets` list (ADR-0059). */
   env?: readonly HarnessEnvVar[];
   /** Whole-Secret/ConfigMap env for the Harness container — `envFrom` refs to Secrets YOU manage
-   * (Sealed Secrets etc.); `jr2 up` preflights that each referenced Secret exists (ADR-0019). */
+   * (Sealed Secrets etc.); `jr2 up` preflights that each referenced Secret exists (ADR-0019), and
+   * refuses one that carries a known model key (ADR-0059). */
   envFrom?: readonly HarnessEnvFromSource[];
   /** Path to a PEM CA bundle, RELATIVE to the instance folder — commit the file (CA certs are
    * public; e.g. an internal CA in front of a LAN vLLM). Only `jr2 up` reads it (host-side): it
    * materializes the `jr2-ca` ConfigMap and runs the provider preflight with the same trust. The
-   * bundle lands on the Harness container and NOWHERE else — never the Adapter, whose Orchestrator
-   * credential has no business behind the same trust store (the `harness.env` asymmetry,
-   * ADR-0013/0020). */
+   * Harness container trusts it, and so does the Custodian when it verifies a bound host
+   * (ADR-0020, ADR-0059). */
   caBundle?: string;
 };
 
@@ -207,19 +277,59 @@ export type SandboxPlacement = {
   tolerations?: readonly Toleration[];
 };
 
+/**
+ * The Instance's Sandbox defaults (ADR-0052, ADR-0060): placement, and the Size for a Workspace
+ * that states none.
+ */
+export type SandboxConfig = SandboxPlacement & {
+  /**
+   * The Instance's default Size (ADR-0060) — `{ limits: { memory, cpu } }` and nothing else — for
+   * a Workspace that states no Size at all; the kit fills what it leaves out. NEVER an override of a Size a Machine states: a
+   * Size is a fact of the Machine, and its one override path is `customize(machine, { resources })`.
+   * Absent → the kit default, memory 2Gi and cpu 1. jr2 reserves the whole Size (every request
+   * equals its limit) and enforces the CPU limit.
+   */
+  resources?: Size;
+};
+
+/**
+ * The PriorityClasses jr2's pods run under (ADR-0060). Absent, `jr2 up` creates two, cluster-scoped,
+ * beside the CRDs: `jr2-control` (100000, PreemptLowerPriority) for the Orchestrator, the operator
+ * and the Repo cache agent, and `jr2-sandbox` (1000, preemptionPolicy Never) for Sandboxes and the
+ * Instance Harness — so an ordinary pod cannot preempt a live Workspace, and a waiting Sandbox
+ * evicts nobody. A cluster with its own scheme names existing classes here, and `jr2 up` then
+ * creates none for that key.
+ */
+export type PriorityClasses = {
+  /** An existing PriorityClass for the Orchestrator, the operator and the Repo cache agent. */
+  control?: string;
+  /** An existing PriorityClass for Sandboxes and the Instance Harness. */
+  sandbox?: string;
+};
+
 export type JR2Config = {
   /** The instance's identity (ADR-0019): its kube namespace defaults to this (`-n` overrides),
    * and `jr2 up` labels every object it owns with it. Default: the instance folder's name. */
   name?: string;
+  /** Every secret of the Instance, one list for both sides (ADR-0068). Naming is the placement: a
+   * Held secret where a `workspace()` lists it under `secrets: [...]` or an Agent's provider reads
+   * it — a model API key belongs here, never in `harness.env` (ADR-0059) — and an Effect secret
+   * where an Effect names it with `secret("name")`. `hosts` is a Held secret's binding, never its
+   * placement: an entry nothing names goes nowhere. See `SecretEntry`. */
+  secrets?: readonly SecretEntry[];
   /** How the cluster authenticates to Repos, and the fence a per-run url must pass (ADR-0051).
    * NOT a list of Repos: a Machine names those itself, through its `workspace()`'s Repo Slots, and
    * whether the instance has a data plane at all is read off the registered Machines. */
   git?: GitConfig;
   /** Agent-runtime config for the stock Harness (see `HarnessConfig`). */
   harness?: HarnessConfig;
-  /** Which nodes are this Instance's Sandbox nodes (see `SandboxPlacement`, ADR-0052). Absent →
-   * wherever an ordinary pod lands. */
-  sandbox?: SandboxPlacement;
+  /** Which nodes are this Instance's Sandbox nodes (see `SandboxPlacement`, ADR-0052), and the
+   * Size of a Workspace that states none (see `SandboxConfig`, ADR-0060). Absent → wherever an
+   * ordinary pod lands, at the kit's Size. */
+  sandbox?: SandboxConfig;
+  /** Existing PriorityClasses to use instead of the two `jr2 up` creates (see `PriorityClasses`,
+   * ADR-0060). */
+  priorityClasses?: PriorityClasses;
   /** Image registry prefix (deployment-varying — resolve from env). Absent → images are
    * `kind load`-ed; present → pushed. A non-kind cluster without one fails loudly (ADR-0019). */
   registry?: string;
@@ -231,7 +341,7 @@ export type JR2Config = {
    *
    * Separate from `registry` on purpose: `registry` addresses images THIS converge builds,
    * `kitRegistry` addresses artifacts the kit already published. One key for both would make every
-   * private-registry user mirror three images they could have pulled from the home. */
+   * private-registry user mirror the Kit images they could have pulled from the home. */
   kitRegistry?: string;
   /** What `jr2 up` builds its images FOR — docker platform strings, e.g. `["linux/arm64"]`
    * (deployment-varying — resolve from env). Absent → derived from the cluster's schedulable nodes
@@ -260,10 +370,13 @@ export function defineConfig(c: JR2Config): JR2Config {
 /**
  * Load an instance's `jr2.config.ts` (default export). Absent file → undefined (an instance
  * can boot configless); a file that fails to IMPORT throws — a broken config must be loud,
- * never silently treated as "no config". The one shape check lives here, on the path the host
- * CLI and the in-cluster Orchestrator share: `git.credentials` is checked at runtime, because an
- * instance is zero-build and nothing typechecks this file before Node strips its types and
- * imports it.
+ * never silently treated as "no config". The shape checks live here, on the path the host CLI
+ * and the in-cluster Orchestrator share: `git.credentials`, `secrets` and `harness.catalog` are
+ * checked at runtime, because an instance is zero-build and nothing typechecks this file before
+ * Node strips its types and imports it. SHAPE only: a secret's
+ * `value` reads `.env`, which the in-cluster evaluation does not have, so an absent value is not
+ * this function's to refuse — `jr2 up` checks presence and every held-secret rule host-side
+ * (`heldSecretsOf`, ADR-0059).
  */
 export async function loadConfig(dir: string): Promise<JR2Config | undefined> {
   const file = join(dir, "jr2.config.ts");
@@ -271,11 +384,29 @@ export async function loadConfig(dir: string): Promise<JR2Config | undefined> {
   const mod = (await import(pathToFileURL(file).href)) as { default?: JR2Config };
   if (!mod.default) throw new Error(`${file} has no default export (use \`export default defineConfig({…})\`)`);
   if (mod.default.git !== undefined) checkGit(mod.default.git, file);
+  if (mod.default.secrets !== undefined) checkSecrets(mod.default.secrets, file);
+  if (mod.default.harness !== undefined) checkHarness(mod.default.harness, file);
+  if (mod.default.sandbox !== undefined) checkSandbox(mod.default.sandbox, file);
+  if (mod.default.priorityClasses !== undefined) checkPriorityClasses(mod.default.priorityClasses, file);
   return mod.default;
 }
 
 const NonEmpty = z.string().min(1);
-const Credential = z.object({ match: NonEmpty, token: NonEmpty.optional(), sshKey: NonEmpty.optional() }).strict();
+const Credential = z
+  .object({
+    match: NonEmpty,
+    token: NonEmpty.optional(),
+    sshKey: NonEmpty.optional(),
+    push: z.union([z.object({ sshKey: NonEmpty }).strict(), z.object({ token: NonEmpty }).strict()]).optional(),
+    sign: z
+      .union([
+        z.object({ sshKey: NonEmpty, name: NonEmpty, email: NonEmpty }).strict(),
+        z.object({ gpgKey: NonEmpty, name: NonEmpty, email: NonEmpty }).strict(),
+      ])
+      .optional(),
+    committer: z.object({ name: NonEmpty, email: NonEmpty }).strict().optional(),
+  })
+  .strict();
 
 /** `git.credentials`' SHAPE, checked at load — by index and field, so a bad entry names itself
  * (`git.credentials[1].token`) rather than surfacing as a Secret that never matches. */
@@ -294,4 +425,84 @@ function checkGit(git: unknown, where: string): void {
   }
 }
 
-const GIT_HINT = "an entry is { match, token?, sshKey? } (ADR-0051)";
+const GIT_HINT =
+  "an entry is { match, token?, sshKey?, push?: { sshKey } | { token }, sign?: { sshKey | gpgKey, name, email }, " +
+  "committer?: { name, email } } (ADR-0051)";
+
+const OptionalText = z.string().optional();
+const SecretShape = z
+  .object({
+    name: NonEmpty,
+    // `.env` values are absent in-cluster, so `undefined` must pass here — presence is `jr2 up`'s.
+    value: OptionalText,
+    valueFrom: z
+      .object({ secretKeyRef: z.object({ name: NonEmpty, key: NonEmpty }).strict() })
+      .strict()
+      .optional(),
+    hosts: z.array(z.string()).optional(),
+    headers: z.array(z.string()).optional(),
+    paths: z.array(z.string()).optional(),
+  })
+  .strict();
+const CatalogReachShape = z.object({ baseUrl: z.string() }).strict();
+
+/** `secrets`' SHAPE (ADR-0059's entry, ADR-0068's list) — by index and field, the `checkGit` style,
+ * so a bad entry names itself (`secrets[1].hosts`). */
+function checkSecrets(secrets: unknown, where: string): void {
+  if (!Array.isArray(secrets)) throw new Error(`${where} at secrets: expected an array — ${SECRET_HINT}`);
+  for (const [i, entry] of secrets.entries()) {
+    const parsed = SecretShape.safeParse(entry);
+    if (parsed.success) continue;
+    const issue = parsed.error.issues[0];
+    const at = ["", ...(issue?.path ?? [])].map(String).join(".");
+    throw new Error(`${where} at secrets[${i}]${at}: ${issue?.message ?? "invalid"} — ${SECRET_HINT}`);
+  }
+}
+
+/** `harness.catalog`'s SHAPE (ADR-0059) — by provider id and field, the `checkGit` style. */
+function checkHarness(harness: unknown, where: string): void {
+  if (typeof harness !== "object" || harness === null || Array.isArray(harness)) {
+    throw new Error(`${where} at harness: expected an object`);
+  }
+  const { catalog } = harness as { catalog?: unknown };
+  if (catalog !== undefined) {
+    if (typeof catalog !== "object" || catalog === null || Array.isArray(catalog)) {
+      throw new Error(`${where} at harness.catalog: expected an object keyed by catalog provider id — ${CATALOG_HINT}`);
+    }
+    for (const [id, reach] of Object.entries(catalog)) {
+      const parsed = CatalogReachShape.safeParse(reach);
+      if (parsed.success) continue;
+      const issue = parsed.error.issues[0];
+      const at = ["", ...(issue?.path ?? [])].map(String).join(".");
+      throw new Error(`${where} at harness.catalog.${id}${at}: ${issue?.message ?? "invalid"} — ${CATALOG_HINT}`);
+    }
+  }
+}
+
+const SECRET_HINT =
+  "an entry is { name, value? | valueFrom?: { secretKeyRef: { name, key } }, hosts?, headers?, paths? } (ADR-0059, ADR-0068)";
+const CATALOG_HINT = "an entry is <provider id>: { baseUrl } (ADR-0059)";
+
+/** `sandbox.resources`' SHAPE (ADR-0060), checked at load by field — `requests`, or any key beside
+ * the two limits, is refused naming itself (`sandbox.resources.requests`). */
+function checkSandbox(sandbox: unknown, where: string): void {
+  if (typeof sandbox !== "object" || sandbox === null || Array.isArray(sandbox)) {
+    throw new Error(`${where} at sandbox: expected an object — { nodeSelector?, tolerations?, resources? }`);
+  }
+  const { resources } = sandbox as { resources?: unknown };
+  if (resources !== undefined) assertSize(`${where} at sandbox.resources`, resources);
+}
+
+const PriorityClassesShape = z.object({ control: NonEmpty.optional(), sandbox: NonEmpty.optional() }).strict();
+
+/** `priorityClasses`' SHAPE (ADR-0060): two optional class names, nothing else. */
+function checkPriorityClasses(classes: unknown, where: string): void {
+  const parsed = PriorityClassesShape.safeParse(classes);
+  if (parsed.success) return;
+  const issue = parsed.error.issues[0];
+  const at = ["", ...(issue?.path ?? [])].map(String).join(".");
+  throw new Error(
+    `${where} at priorityClasses${at}: ${issue?.message ?? "invalid"} — { control?, sandbox? }, each the name of ` +
+      "an existing PriorityClass (ADR-0060)",
+  );
+}

package/src/content-hash.ts

@@ -0,0 +1,105 @@
+// The content address jr2 takes of a tree (ADR-0038, ADR-0069). It lives here, not in the CLI,
+// because two ends compute it over one Assembly: `jr2 up` hashes the staged tree, and the door
+// recomputes the hash over the unpacked tree before it accepts a publish. One implementation, so
+// the two ends cannot drift.
+
+import { createHash } from "node:crypto";
+import { readdir, readFile, readlink, stat } from "node:fs/promises";
+import { basename, join, relative } from "node:path";
+
+/** The salt of an Assembly's hash (ADR-0069). The host and the door both hash with it. */
+export const ASSEMBLY_HASH_SALT = "assembly";
+
+/**
+ * The name of an Assembly (ADR-0069): a hash over every entry the Assembly's archive carries. The
+ * host names its staged tree with it, and the door recomputes it over the unpacked tree. The door
+ * then trusts "one hash names one Assembly" three times: `jr2 up` skips a publish whose hash is
+ * current, the door answers `unchanged`, and the door reuses an `assemblies/<hash>/` it already
+ * holds. So the hash covers what the archive carries, and nothing can change under one hash:
+ *
+ * - Each directory is a record, so an empty one counts.
+ * - Each symlink is a record with its target. `contentHash` skips links (an image tag must not see
+ *   pnpm's store links twice), but an Assembly's links travel, and a changed target is a changed
+ *   Assembly.
+ * - Each record is framed: a type, then every field as its byte length and its bytes. Without the
+ *   frame, a file `a` that holds `X0:b\nY` hashes as the files `a` = `X` and `b` = `Y`.
+ *
+ * The walk is in byte order (`byteOrder`). Modes are not in the hash: nothing at the door reads
+ * them, and an umask must not move an Assembly's name. Other entry types (a socket, a FIFO) are not
+ * records: the archive refuses them, so they never reach the door. Nothing is excluded: the hash
+ * names every byte the archive carries.
+ */
+export async function assemblyHash(dir: string): Promise<string> {
+  const h = createHash("sha256");
+  h.update(`salt:${ASSEMBLY_HASH_SALT}\n`);
+  const field = (bytes: Buffer): void => {
+    h.update(`${bytes.length}:`);
+    h.update(bytes);
+  };
+  const walk = async (d: string, rel: string): Promise<void> => {
+    const entries = (await readdir(d, { withFileTypes: true })).sort((a, b) => byteOrder(a.name, b.name));
+    for (const e of entries) {
+      const p = join(d, e.name);
+      const path = Buffer.from(rel === "" ? e.name : `${rel}/${e.name}`, "utf8");
+      if (e.isSymbolicLink()) {
+        h.update("l");
+        field(path);
+        field(Buffer.from(await readlink(p), "utf8"));
+      } else if (e.isDirectory()) {
+        h.update("d");
+        field(path);
+        await walk(p, path.toString("utf8"));
+      } else if (e.isFile()) {
+        h.update("f");
+        field(path);
+        field(await readFile(p));
+      }
+    }
+  };
+  await walk(dir, "");
+  return h.digest("hex").slice(0, 12);
+}
+
+/**
+ * The order a content address walks a directory in: UTF-8 byte order of the entry names, never a
+ * locale's collation. `localeCompare` reads the ICU locale from `LANG`/`LC_ALL`, and the two ends
+ * of a hash run in different locales: in `cs_CZ`, "ch" sorts after "h", so a host there would
+ * hash `node_modules/chalk` after `hono` while the Kit image hashes it first, and every publish
+ * would fail the door's check. The Assembly's tar orders its entries by the same rule.
+ */
+export function byteOrder(a: string, b: string): number {
+  return Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+}
+
+/**
+ * A short content hash over `paths` (files and/or directories, sorted walk), salted with `salt`.
+ * Symlinks are skipped rather than followed: in a pnpm bundle `node_modules/<pkg>` links into the
+ * virtual store, whose real files the walk already visits — following would hash the same bytes
+ * twice. Each path contributes its entries under its own index prefix, so two directories that
+ * happen to hold the same relative filenames stay distinguishable.
+ */
+export async function contentHash(paths: string[], salt: string, exclude: Set<string> = new Set()): Promise<string> {
+  const h = createHash("sha256");
+  h.update(`salt:${salt}\n`);
+  const walk = async (root: string, d: string, index: number): Promise<void> => {
+    const entries = (await readdir(d, { withFileTypes: true })).sort((a, b) => byteOrder(a.name, b.name));
+    for (const e of entries) {
+      if (exclude.has(e.name)) continue;
+      const p = join(d, e.name);
+      if (e.isDirectory()) await walk(root, p, index);
+      else if (e.isFile()) {
+        h.update(`${index}:${relative(root, p)}\n`);
+        h.update(await readFile(p));
+      }
+    }
+  };
+  for (const [index, p] of paths.entries()) {
+    const st = await stat(p);
+    if (st.isDirectory()) await walk(p, p, index);
+    else {
+      h.update(`${index}:${basename(p)}\n`);
+      h.update(await readFile(p));
+    }
+  }
+  return h.digest("hex").slice(0, 12);
+}