@specific.dev/spectest 0.39.0 → 0.43.0

package/dist/harness/build-context.d.ts

@@ -0,0 +1,82 @@
+/**
+ * What goes into a docker build: the image tag, the ignore rules, and the
+ * key that lets two identical builds collapse into one.
+ *
+ * Ported out of `daemon.ts`. The functions here read no module state —
+ * the project's own `.dockerignore` is passed in rather than reached for —
+ * which is what makes the ordering rule below testable at all.
+ */
+/** Every service's built image is tagged in one namespace. */
+export declare function imageTag(name: string): string;
+/**
+ * Always excluded from a build context: version control, our own state,
+ * dependency and build output directories, and dotenv files.
+ */
+export declare const DEFAULT_DOCKERIGNORE: readonly string[];
+/**
+ * First line of a `.dockerignore` we generated, so a later bootstrap can
+ * tell our file apart from one the project ships and never mistakes its
+ * own output for user intent.
+ */
+export declare const GENERATED_DOCKERIGNORE_HEADER = "# spectest-generated \u2014 do not edit (your own .dockerignore is honoured verbatim)";
+/** Is this text a file we wrote ourselves on an earlier bootstrap? */
+export declare function isGeneratedDockerignore(text: string): boolean;
+/**
+ * Ignore rules for one dockerfile build, in precedence order: our
+ * defaults, then the project's own `.dockerignore` verbatim, then that
+ * service's `exclude`.
+ *
+ * **The order is load-bearing**, because of the `**`-plus-negations idiom
+ * that monorepos use to keep a build context small:
+ *
+ * ```
+ * **                 ← the project's file: exclude everything
+ * !go.mod            ← …then re-include exactly what the build reads
+ * !cmd/api/**
+ * ```
+ *
+ * Our defaults must come *first* so that `**` subsumes them; if they came
+ * after, they would re-exclude nothing useful but would sit below the
+ * negations and confuse the intent. The service's `exclude` comes *last*
+ * so it still gets the final word over both.
+ *
+ * Written per service (`.spectest/services/<name>/Dockerfile.dockerignore`)
+ * because BuildKit gives a Dockerfile-adjacent ignore file precedence over
+ * the context root's — which is what stops one service's `exclude` from
+ * shrinking a sibling's build context.
+ */
+export declare function serviceDockerignore(projectDockerignore: string | null, exclude?: readonly string[]): string;
+/**
+ * The context-root `.dockerignore` we write **only when the project ships
+ * none**, as a fallback for the legacy non-BuildKit builder.
+ *
+ * Deliberately does not include the project's own rules: it exists only in
+ * the case where there are none. Overwriting a project's file was a real
+ * regression — a carefully minimised context silently became the whole
+ * repo, which is a 10x build-time hit on a monorepo, and any in-env
+ * tooling that read the file saw ours instead.
+ */
+export declare function unionDockerignore(services: readonly {
+    image: {
+        type: string;
+        exclude?: readonly string[];
+    };
+}[]): string;
+/**
+ * Identity of a dockerfile build within one bootstrap, so services sharing
+ * an image definition (an api and a worker on the same codebase with
+ * different entrypoints) build once and the rest just re-tag.
+ *
+ * The build **context** is an input too, but it isn't hashed: the context
+ * is `/workspace`, which is fixed within a bootstrap and mutable between
+ * them, so this key is only ever valid inside one workspace generation.
+ * The dedup map is cleared per bootstrap for exactly that reason.
+ */
+export interface Hasher {
+    update(s: string): Hasher;
+    digest(encoding: "hex"): string;
+}
+export declare function buildContentKey(createHasher: () => Hasher, image: {
+    content: string;
+    exclude?: readonly string[];
+}): string;

package/dist/harness/build-context.js

@@ -0,0 +1,113 @@
+/**
+ * What goes into a docker build: the image tag, the ignore rules, and the
+ * key that lets two identical builds collapse into one.
+ *
+ * Ported out of `daemon.ts`. The functions here read no module state —
+ * the project's own `.dockerignore` is passed in rather than reached for —
+ * which is what makes the ordering rule below testable at all.
+ */
+/** Every service's built image is tagged in one namespace. */
+export function imageTag(name) {
+    return `spectest/${name}:latest`;
+}
+/**
+ * Always excluded from a build context: version control, our own state,
+ * dependency and build output directories, and dotenv files.
+ */
+export const DEFAULT_DOCKERIGNORE = [
+    ".git",
+    ".spectest",
+    "spectest",
+    "node_modules",
+    "target",
+    "__pycache__",
+    ".venv",
+    ".env",
+    ".env.local",
+    ".env.*",
+    "dist",
+    "build",
+    ".next",
+    ".turbo",
+    ".DS_Store",
+];
+/**
+ * First line of a `.dockerignore` we generated, so a later bootstrap can
+ * tell our file apart from one the project ships and never mistakes its
+ * own output for user intent.
+ */
+export const GENERATED_DOCKERIGNORE_HEADER = "# spectest-generated — do not edit (your own .dockerignore is honoured verbatim)";
+/** Is this text a file we wrote ourselves on an earlier bootstrap? */
+export function isGeneratedDockerignore(text) {
+    return text.startsWith(GENERATED_DOCKERIGNORE_HEADER);
+}
+/**
+ * Ignore rules for one dockerfile build, in precedence order: our
+ * defaults, then the project's own `.dockerignore` verbatim, then that
+ * service's `exclude`.
+ *
+ * **The order is load-bearing**, because of the `**`-plus-negations idiom
+ * that monorepos use to keep a build context small:
+ *
+ * ```
+ * **                 ← the project's file: exclude everything
+ * !go.mod            ← …then re-include exactly what the build reads
+ * !cmd/api/**
+ * ```
+ *
+ * Our defaults must come *first* so that `**` subsumes them; if they came
+ * after, they would re-exclude nothing useful but would sit below the
+ * negations and confuse the intent. The service's `exclude` comes *last*
+ * so it still gets the final word over both.
+ *
+ * Written per service (`.spectest/services/<name>/Dockerfile.dockerignore`)
+ * because BuildKit gives a Dockerfile-adjacent ignore file precedence over
+ * the context root's — which is what stops one service's `exclude` from
+ * shrinking a sibling's build context.
+ */
+export function serviceDockerignore(projectDockerignore, exclude) {
+    const parts = [DEFAULT_DOCKERIGNORE.join("\n")];
+    if (projectDockerignore !== null) {
+        parts.push(`# --- from the project's .dockerignore ---\n${projectDockerignore.trimEnd()}`);
+    }
+    if (exclude && exclude.length > 0) {
+        parts.push(`# --- from this service's exclude ---\n${exclude.join("\n")}`);
+    }
+    return parts.join("\n") + "\n";
+}
+/**
+ * The context-root `.dockerignore` we write **only when the project ships
+ * none**, as a fallback for the legacy non-BuildKit builder.
+ *
+ * Deliberately does not include the project's own rules: it exists only in
+ * the case where there are none. Overwriting a project's file was a real
+ * regression — a carefully minimised context silently became the whole
+ * repo, which is a 10x build-time hit on a monorepo, and any in-env
+ * tooling that read the file saw ours instead.
+ */
+export function unionDockerignore(services) {
+    const seen = new Set(DEFAULT_DOCKERIGNORE);
+    const extras = [];
+    for (const s of services) {
+        if (s.image.type === "dockerfile" && s.image.exclude) {
+            for (const e of s.image.exclude) {
+                if (!seen.has(e)) {
+                    seen.add(e);
+                    extras.push(e);
+                }
+            }
+        }
+    }
+    return [GENERATED_DOCKERIGNORE_HEADER, ...DEFAULT_DOCKERIGNORE, ...extras].join("\n") + "\n";
+}
+export function buildContentKey(createHasher, image) {
+    return (createHasher()
+        .update(image.content)
+        // A separator that cannot occur in either field. Without it a
+        // Dockerfile whose text ends with an exclude list would hash the
+        // same as that Dockerfile with the list actually set, and two
+        // genuinely different builds would collapse into one.
+        .update("\0")
+        .update(JSON.stringify(image.exclude ?? []))
+        .digest("hex"));
+}

package/dist/harness/buildkit-progress.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Reading `docker build --progress=plain` output.
+ *
+ * BuildKit's plain progress is the only machine-readable account of what a
+ * build actually did, and it is what the dashboard shows when a bootstrap
+ * is slow — which step took the time, and which were cache hits. Parsing
+ * it is pure string work, so it belongs out here where it can be tested
+ * against real output shapes rather than inferred from the regexes.
+ *
+ * Ported out of `daemon.ts`.
+ *
+ * The format, for the parts we read:
+ *
+ * ```
+ * #7 [builder 3/6] RUN go build ./...
+ * #7 sha256:abc…                       ← noise; ignored
+ * #7 DONE 12.4s
+ * #9 CACHED
+ * ```
+ */
+export interface BuildStep {
+    name: string;
+    secs: number;
+    cached: boolean;
+}
+/**
+ * Summarise a build's steps, slowest first.
+ *
+ * Only the **first** line seen for a step id names it: BuildKit repeats
+ * the id for progress and digest lines, and a later one would overwrite
+ * the actual command with noise.
+ *
+ * A `CACHED` step is recorded at zero seconds rather than dropped —
+ * "this was cached" is the answer to "why was this build fast", and
+ * omitting it makes a fully-cached build look like it did nothing.
+ */
+export declare function summarizeBuildKit(out: string): BuildStep[];

package/dist/harness/buildkit-progress.js

@@ -0,0 +1,66 @@
+/**
+ * Reading `docker build --progress=plain` output.
+ *
+ * BuildKit's plain progress is the only machine-readable account of what a
+ * build actually did, and it is what the dashboard shows when a bootstrap
+ * is slow — which step took the time, and which were cache hits. Parsing
+ * it is pure string work, so it belongs out here where it can be tested
+ * against real output shapes rather than inferred from the regexes.
+ *
+ * Ported out of `daemon.ts`.
+ *
+ * The format, for the parts we read:
+ *
+ * ```
+ * #7 [builder 3/6] RUN go build ./...
+ * #7 sha256:abc…                       ← noise; ignored
+ * #7 DONE 12.4s
+ * #9 CACHED
+ * ```
+ */
+/** Longest step name we keep — these are Dockerfile lines and can be huge. */
+const MAX_NAME = 80;
+/**
+ * Summarise a build's steps, slowest first.
+ *
+ * Only the **first** line seen for a step id names it: BuildKit repeats
+ * the id for progress and digest lines, and a later one would overwrite
+ * the actual command with noise.
+ *
+ * A `CACHED` step is recorded at zero seconds rather than dropped —
+ * "this was cached" is the answer to "why was this build fast", and
+ * omitting it makes a fully-cached build look like it did nothing.
+ */
+export function summarizeBuildKit(out) {
+    const names = new Map();
+    const secs = new Map();
+    const cached = new Set();
+    for (const line of out.split("\n")) {
+        let m = line.match(/^#(\d+)\s+\[[^\]]*\]\s+(.+)$/);
+        if (m) {
+            const id = `#${m[1]}`;
+            if (!names.has(id))
+                names.set(id, m[2].trim().slice(0, MAX_NAME));
+            continue;
+        }
+        m = line.match(/^#(\d+)\s+DONE\s+([\d.]+)s/);
+        if (m) {
+            secs.set(`#${m[1]}`, parseFloat(m[2]));
+            continue;
+        }
+        m = line.match(/^#(\d+)\s+CACHED/);
+        if (m) {
+            const id = `#${m[1]}`;
+            cached.add(id);
+            // Don't clobber a real duration: a step can report CACHED after a
+            // DONE when part of its work was reused.
+            if (!secs.has(id))
+                secs.set(id, 0);
+        }
+    }
+    const steps = [];
+    for (const [id, name] of names) {
+        steps.push({ name, secs: secs.get(id) ?? 0, cached: cached.has(id) });
+    }
+    return steps.sort((a, b) => b.secs - a.secs);
+}

package/dist/harness/container-run.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Assembling the `docker run` command line for a service container.
+ *
+ * Ported out of `daemon.ts` as part of the harness split. This is the most
+ * consequential command the harness builds — it decides a container's
+ * network identity, what it trusts, what it can see of the host, and what
+ * it actually executes — and it had no tests, because the only way to
+ * reach it was to start a real container.
+ *
+ * Splitting the argv construction from running it makes every rule below
+ * assertable in milliseconds. The caller keeps the side effects: removing
+ * a leftover container, invoking docker, and reading the result.
+ *
+ * ## Rules encoded here
+ *
+ * **Two names, always.** Every service answers to its bare name and to
+ * `<name>.internal`. The multi-label form exists because a single-label
+ * host breaks things that assume a FQDN — notably headless Chromium, which
+ * tries TLS against a bare name and fails with a protocol error even
+ * though `fetch` to the same URL is fine.
+ *
+ * **Certificate trust is two different mechanisms, and mixing them up
+ * breaks images silently.** `NODE_EXTRA_CA_CERTS` *appends* to the trust
+ * store, so it takes the bare spectest CA. `SSL_CERT_FILE`,
+ * `REQUESTS_CA_BUNDLE` and `AWS_CA_BUNDLE` *replace* it, so they must get
+ * the combined bundle — public roots plus ours. Pointing those three at
+ * the bare CA leaves the container trusting spectest and nothing else, and
+ * every outbound HTTPS call to a real service fails to verify. Node never
+ * showed the problem, which is why it went unnoticed: only the appending
+ * variable was in play.
+ *
+ * **`command` and `args` are different overrides.** `command` replaces the
+ * entrypoint and runs through `sh -c`; `args` keeps the entrypoint and
+ * overrides CMD, which is what init-wrapped images like postgres need to
+ * take extra flags. Accepting both would silently drop one.
+ */
+/** The subset of a service's config that shapes its container. */
+export interface ContainerService {
+    name: string;
+    env?: Record<string, string>;
+    workdir?: string;
+    privileged?: boolean;
+    tmpfs?: readonly string[];
+    cgroupns?: string;
+    command?: string;
+    args?: readonly string[];
+}
+export interface ContainerRunInput {
+    svc: ContainerService;
+    /** The image tag to run. */
+    tag: string;
+    /** Docker network to attach to. */
+    network: string;
+    /** Extra `--network-alias` names beyond `<name>` and `<name>.internal`. */
+    aliases?: readonly string[];
+    /** Volume/file/certificate mount flags, already assembled. */
+    volumeFlags?: readonly string[];
+    /** Ingress hostnames to pin to {@link ContainerRunInput.gatewayIp}. */
+    ingressHosts?: readonly string[];
+    /** The bridge gateway, where the ingress listeners are. Null when it
+     *  isn't known yet, in which case no `--add-host` is emitted. */
+    gatewayIp?: string | null;
+    /** The host image-cache gateway, reachable as `spectest-host`. */
+    hostCacheGateway?: string | null;
+    hostCacheName: string;
+    /** The in-VM root CA, bind-mounted and appended to Node's roots. */
+    caPath: string;
+    /** Public roots ⧺ our CA, for the variables that *replace* the store. */
+    caBundle?: string | null;
+}
+/**
+ * Bound TCP give-up time inside the container's own network namespace.
+ *
+ * `net.ipv4.tcp_retries2` is per-netns and a fresh netns resets to the
+ * kernel default (15, roughly 15 minutes of RTO backoff), so lowering it on
+ * the guest's init netns does not reach containers — and the flows that
+ * actually wedge live here: buildkit pulling base images and exporting
+ * cache, and k3s's containerd pulling images, all over the VM↔host path to
+ * the host registry. On a lost retransmit under concurrent forks such a
+ * flow otherwise stalls a build for minutes; six retries resets a genuinely
+ * stuck connection in tens of seconds and the client reconnects. Live
+ * connections keep getting ACKs and are unaffected.
+ *
+ * Safe because every service runs on the bridge network with its own netns,
+ * never `--network=host`, where writing `net.*` is denied.
+ */
+export declare const TCP_RETRIES2 = 6;
+/** Build the full `docker run` argv. Pure: no I/O, no module state. */
+export declare function runContainerArgs(input: ContainerRunInput): string[];

package/dist/harness/container-run.js

@@ -0,0 +1,118 @@
+/**
+ * Assembling the `docker run` command line for a service container.
+ *
+ * Ported out of `daemon.ts` as part of the harness split. This is the most
+ * consequential command the harness builds — it decides a container's
+ * network identity, what it trusts, what it can see of the host, and what
+ * it actually executes — and it had no tests, because the only way to
+ * reach it was to start a real container.
+ *
+ * Splitting the argv construction from running it makes every rule below
+ * assertable in milliseconds. The caller keeps the side effects: removing
+ * a leftover container, invoking docker, and reading the result.
+ *
+ * ## Rules encoded here
+ *
+ * **Two names, always.** Every service answers to its bare name and to
+ * `<name>.internal`. The multi-label form exists because a single-label
+ * host breaks things that assume a FQDN — notably headless Chromium, which
+ * tries TLS against a bare name and fails with a protocol error even
+ * though `fetch` to the same URL is fine.
+ *
+ * **Certificate trust is two different mechanisms, and mixing them up
+ * breaks images silently.** `NODE_EXTRA_CA_CERTS` *appends* to the trust
+ * store, so it takes the bare spectest CA. `SSL_CERT_FILE`,
+ * `REQUESTS_CA_BUNDLE` and `AWS_CA_BUNDLE` *replace* it, so they must get
+ * the combined bundle — public roots plus ours. Pointing those three at
+ * the bare CA leaves the container trusting spectest and nothing else, and
+ * every outbound HTTPS call to a real service fails to verify. Node never
+ * showed the problem, which is why it went unnoticed: only the appending
+ * variable was in play.
+ *
+ * **`command` and `args` are different overrides.** `command` replaces the
+ * entrypoint and runs through `sh -c`; `args` keeps the entrypoint and
+ * overrides CMD, which is what init-wrapped images like postgres need to
+ * take extra flags. Accepting both would silently drop one.
+ */
+/**
+ * Bound TCP give-up time inside the container's own network namespace.
+ *
+ * `net.ipv4.tcp_retries2` is per-netns and a fresh netns resets to the
+ * kernel default (15, roughly 15 minutes of RTO backoff), so lowering it on
+ * the guest's init netns does not reach containers — and the flows that
+ * actually wedge live here: buildkit pulling base images and exporting
+ * cache, and k3s's containerd pulling images, all over the VM↔host path to
+ * the host registry. On a lost retransmit under concurrent forks such a
+ * flow otherwise stalls a build for minutes; six retries resets a genuinely
+ * stuck connection in tens of seconds and the client reconnects. Live
+ * connections keep getting ACKs and are unaffected.
+ *
+ * Safe because every service runs on the bridge network with its own netns,
+ * never `--network=host`, where writing `net.*` is denied.
+ */
+export const TCP_RETRIES2 = 6;
+/** Build the full `docker run` argv. Pure: no I/O, no module state. */
+export function runContainerArgs(input) {
+    const { svc, tag, network } = input;
+    if (svc.command && svc.args?.length) {
+        throw new Error(`service ${svc.name}: \`command\` and \`args\` are mutually exclusive ` +
+            `(command replaces the entrypoint with /bin/sh -c; args keeps it)`);
+    }
+    const args = [
+        "run",
+        "-d",
+        "--restart=no",
+        `--name=${svc.name}`,
+        `--hostname=${svc.name}`,
+        `--network=${network}`,
+        `--network-alias=${svc.name}.internal`,
+    ];
+    for (const alias of input.aliases ?? [])
+        args.push(`--network-alias=${alias}`);
+    args.push("--sysctl", `net.ipv4.tcp_retries2=${TCP_RETRIES2}`);
+    // Ingress hostnames via /etc/hosts, which beats Docker's embedded DNS —
+    // so app code reaching a fake or a TLS-terminated proxy lands on the
+    // harness listener without touching the container's resolver config.
+    if (input.gatewayIp) {
+        for (const h of input.ingressHosts ?? []) {
+            args.push(`--add-host=${h}:${input.gatewayIp}`);
+        }
+    }
+    if (input.hostCacheGateway) {
+        args.push(`--add-host=${input.hostCacheName}:${input.hostCacheGateway}`);
+    }
+    if (svc.workdir)
+        args.push(`--workdir=${svc.workdir}`);
+    // See the module header: the appending variable takes the bare CA, the
+    // replacing ones take the combined bundle.
+    args.push(`--volume=${input.caPath}:${input.caPath}:ro`);
+    args.push("-e", `NODE_EXTRA_CA_CERTS=${input.caPath}`);
+    const bundle = input.caBundle;
+    if (bundle) {
+        if (bundle !== input.caPath)
+            args.push(`--volume=${bundle}:${bundle}:ro`);
+        args.push("-e", `SSL_CERT_FILE=${bundle}`);
+        args.push("-e", `REQUESTS_CA_BUNDLE=${bundle}`);
+        args.push("-e", `AWS_CA_BUNDLE=${bundle}`);
+    }
+    // The service's own env comes after ours, so a project can override the
+    // defaults we set rather than being silently overridden by them.
+    for (const [k, v] of Object.entries(svc.env ?? {}))
+        args.push("-e", `${k}=${v}`);
+    for (const flag of input.volumeFlags ?? [])
+        args.push(flag);
+    if (svc.privileged)
+        args.push("--privileged");
+    for (const p of svc.tmpfs ?? [])
+        args.push(`--tmpfs=${p}`);
+    if (svc.cgroupns)
+        args.push(`--cgroupns=${svc.cgroupns}`);
+    if (svc.command)
+        args.push("--entrypoint=/bin/sh");
+    args.push(tag);
+    if (svc.command)
+        args.push("-c", svc.command);
+    else if (svc.args?.length)
+        args.push(...svc.args);
+    return args;
+}

package/dist/harness/file-mounts.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Staging `files` and `certificates` for bind-mounting into a container.
+ *
+ * Ported out of `daemon.ts` as part of the harness split. These are the
+ * *pre-entrypoint* injection point — the only way to put something in place
+ * before the container's own process starts, which is what a config file a
+ * daemon reads at startup, or a TLS key it refuses to run without, actually
+ * needs. `setup` and `helpers` both run too late.
+ *
+ * What lives here is the part that decides *what* is staged and with which
+ * permissions. Writing the bytes, minting the certificate and running chown
+ * stay with the caller — but every rule that has ever been reported as a bug
+ * is a pure function below, with a test.
+ *
+ * ## The permission rules, and why they are not obvious
+ *
+ * **A bind mount carries the host inode's mode and ownership straight
+ * through, and the harness writes as root.** So `mode` on its own is not
+ * enough: locking a file down to `0600` gives the container a file owned by
+ * root that whoever it runs as cannot open. Postgres refusing to start on
+ * its own TLS key is the canonical report. `user`/`group` exist to name the
+ * reader, and naming one is what makes a strict mode usable.
+ *
+ * **Declaring a reader also implies the mode.** A key whose owner is named
+ * gets the strictest mode that owner can still open — `0600` when a user is
+ * named, `0640` when only a group is. A server that checks (postgres, ssh)
+ * refuses a lax key, so defaulting to something permissive would just move
+ * the failure. This only applies when an owner was named, so no existing
+ * environment changes behaviour.
+ *
+ * **`-1` means "leave this half alone", and Bun will not accept it.**
+ * chown(2) and node both read `-1` as unchanged, which is how plain `chown`
+ * lets you set a user without touching the group. Bun's `fs.chown` rejects
+ * it with `EPERM` (measured on Bun 1.3.14), so the untouched half has to be
+ * filled in from the file's current owner before the call —
+ * {@link resolveChownIds} is that, kept separate so the rule is testable
+ * without a filesystem.
+ */
+/** Numeric ids for a staged file. `-1` means "unchanged". */
+export interface OwnerIds {
+    uid: number;
+    gid: number;
+}
+/** `{{SPECTEST_SERVICE}}` → the service's map key.
+ *
+ *  Lets a component author self-referential config without knowing the key
+ *  the user will choose for it — k3s's `registries.yaml` pointing at
+ *  `<key>.internal:5000` is the reason this exists. */
+export declare function expandServiceToken(text: string, service: string): string;
+/** Parse a `user`/`group` value that may be a numeric id already. */
+export declare function numericId(value: string | undefined): number | undefined;
+/**
+ * Does resolving this owner need the image's `/etc/passwd` + `/etc/group`?
+ *
+ * Probing an image costs a `docker create` + `docker cp`, so it is worth
+ * knowing that two numeric ids need no probe at all.
+ */
+export declare function needsIdTables(user?: string, group?: string): boolean;
+/**
+ * The mode a certificate's key should get.
+ *
+ * `undefined` when no owner was named — the file keeps whatever the harness
+ * wrote, which is the pre-existing behaviour for every environment that
+ * never asked about ownership.
+ */
+export declare function defaultKeyMode(explicit: string | undefined, owner: OwnerIds | undefined): string | undefined;
+/**
+ * Fill in the halves of a chown that were meant to be left alone.
+ *
+ * Takes the file's current ids rather than reading them, so the rule is a
+ * pure function. See the module header for why `-1` cannot simply be passed
+ * through under Bun.
+ */
+export declare function resolveChownIds(owner: OwnerIds, current: OwnerIds): OwnerIds;
+/** True when the owner asks for no change at all, so the chown can be
+ *  skipped entirely rather than resolved and re-applied. */
+export declare function isNoopChown(owner: OwnerIds): boolean;
+/**
+ * Reject a container path that isn't absolute.
+ *
+ * A relative path would be resolved by docker against the container's
+ * working directory, so the file would land somewhere that depends on the
+ * image rather than where the project said — a mount that appears to work
+ * and puts the file in the wrong place is worse than one that refuses.
+ */
+export declare function assertAbsolute(service: string, label: string, p: string): void;
+/** The hostnames a certificate entry covers, with the service token
+ *  expanded and the empty case refused. */
+export declare function certificateHostnames(service: string, index: number, hostnames: readonly string[]): string[];
+/** A read-only single-file bind mount. */
+export declare function mountFlag(hostPath: string, containerPath: string): string;