@specific.dev/spectest 0.74.0 → 0.75.0

package/dist/daemon.js

@@ -50,7 +50,7 @@ import { certCovers as hostmatchCertCovers, hostWithoutPort, matchRoute, selectC
 import { INGRESS_HTTPS_PORT, INGRESS_HTTP_PORT, bindRoute, clearTables, emptyTables, planBind, registryTarget, routesFor, unbindRoute, } from "./harness/ingress-table.js";
 import { startTlsTerminator } from "./harness/tls-terminator.js";
 import { runContainerArgs } from "./harness/container-run.js";
-import { BUILDKIT_CACHE_DIR, BUILDKIT_CACHE_UNION, IMAGE_CACHE_MANIFEST, imageCachePathsSync, isOnImageCache, mergeCacheIndex, } from "./harness/image-cache.js";
+import { BUILDKIT_CACHE_DIR, BUILDKIT_CACHE_UNION, buildkitCacheTag, IMAGE_CACHE_MANIFEST, imageCachePathsSync, isOnImageCache, mergeCacheIndex, } from "./harness/image-cache.js";
 import { assertAbsolute, certificateHostnames, defaultKeyMode, expandServiceToken, isNoopChown, mountFlag, needsIdTables, numericId, resolveChownIds, } from "./harness/file-mounts.js";
 import { conflict, notFound, requireString, } from "./harness/methods.js";
 import { openTerminal } from "./terminal.js";
@@ -1107,7 +1107,15 @@ async function runServiceBuild(name, image, tag) {
             // disk is what outlives the VM; `mode=max` keeps every
             // intermediate layer, uncompressed so an import never inflates,
             // and one tag per service so exports do not replace each other.
-            const cacheTag = name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+            // The tag carries the `spectest/service/` prefix because the
+            // directory is one flat tag namespace the project's own BuildKit
+            // writes into too (the docs tell it to mount this path): tags merge
+            // newest-wins with no warning anywhere, and a project naturally tags
+            // a build after the thing it builds, which is also what its service
+            // is named. Specific's `nginx-mod` service tagged its own buildctl
+            // cache `nginx-mod` and the two overwrote each other on alternate
+            // boots (reported 2026-09-06). The prefix is reserved in the docs.
+            const cacheTag = buildkitCacheTag(name);
             cacheExport = [
                 "--cache-to",
                 `type=local,dest=${_localCacheDir},mode=max,compression=uncompressed,force-compression=true,tag=${cacheTag}`,

package/dist/harness/image-cache.d.ts

@@ -56,6 +56,23 @@ export declare const BUILDKIT_CACHE_DIR = "spectest-buildkit-cache";
  * path for both of its cache flags.
  */
 export declare const BUILDKIT_CACHE_UNION = "/var/lib/spectest-buildkit-cache";
+/**
+ * The prefix under which the harness tags its own exports in that
+ * directory. It is one flat tag namespace shared with the project's own
+ * BuildKit (the `/services` docs page tells it to mount the union), tags
+ * merge newest-wins with no warning, and a project naturally tags a build
+ * after the thing it builds — which is what its spectest service is named
+ * too. So the harness's tags live under a prefix no project would choose,
+ * and the docs reserve it. Reported by Specific 2026-09-06: a service
+ * `nginx-mod` running `buildctl` tagged its cache `nginx-mod`, and it and
+ * the harness's image build for that very container overwrote each other
+ * on alternate boots.
+ */
+export declare const BUILDKIT_CACHE_TAG_PREFIX = "spectest/service/";
+/** The BuildKit cache tag for a service's Dockerfile build: the prefix plus
+ *  the service name, lowercased with anything outside `[a-z0-9-]` folded
+ *  to `-`. */
+export declare function buildkitCacheTag(service: string): string;
 /** The cache's paths, or `null` when this VM carries none.
  *  `SPECTEST_IMAGE_CACHE_MANIFEST` points a test at another file. */
 export declare function imageCachePathsSync(manifest?: string): ImageCachePaths | null;

package/dist/harness/image-cache.js

@@ -50,6 +50,25 @@ export const BUILDKIT_CACHE_DIR = "spectest-buildkit-cache";
  * path for both of its cache flags.
  */
 export const BUILDKIT_CACHE_UNION = "/var/lib/spectest-buildkit-cache";
+/**
+ * The prefix under which the harness tags its own exports in that
+ * directory. It is one flat tag namespace shared with the project's own
+ * BuildKit (the `/services` docs page tells it to mount the union), tags
+ * merge newest-wins with no warning, and a project naturally tags a build
+ * after the thing it builds — which is what its spectest service is named
+ * too. So the harness's tags live under a prefix no project would choose,
+ * and the docs reserve it. Reported by Specific 2026-09-06: a service
+ * `nginx-mod` running `buildctl` tagged its cache `nginx-mod`, and it and
+ * the harness's image build for that very container overwrote each other
+ * on alternate boots.
+ */
+export const BUILDKIT_CACHE_TAG_PREFIX = "spectest/service/";
+/** The BuildKit cache tag for a service's Dockerfile build: the prefix plus
+ *  the service name, lowercased with anything outside `[a-z0-9-]` folded
+ *  to `-`. */
+export function buildkitCacheTag(service) {
+    return `${BUILDKIT_CACHE_TAG_PREFIX}${service.replace(/[^a-z0-9-]/gi, "-").toLowerCase()}`;
+}
 function parse(raw) {
     const parsed = JSON.parse(raw);
     const root = (parsed.disks ?? []).find((d) => d.role === "root" && d.path)?.path;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.74.0",
+  "version": "0.75.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/daemon.ts

@@ -138,6 +138,7 @@ import { runContainerArgs } from "./harness/container-run.js";
 import {
   BUILDKIT_CACHE_DIR,
   BUILDKIT_CACHE_UNION,
+  buildkitCacheTag,
   IMAGE_CACHE_MANIFEST,
   imageCachePathsSync,
   isOnImageCache,
@@ -1456,7 +1457,15 @@ async function runServiceBuild(
       // disk is what outlives the VM; `mode=max` keeps every
       // intermediate layer, uncompressed so an import never inflates,
       // and one tag per service so exports do not replace each other.
-      const cacheTag = name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+      // The tag carries the `spectest/service/` prefix because the
+      // directory is one flat tag namespace the project's own BuildKit
+      // writes into too (the docs tell it to mount this path): tags merge
+      // newest-wins with no warning anywhere, and a project naturally tags
+      // a build after the thing it builds, which is also what its service
+      // is named. Specific's `nginx-mod` service tagged its own buildctl
+      // cache `nginx-mod` and the two overwrote each other on alternate
+      // boots (reported 2026-09-06). The prefix is reserved in the docs.
+      const cacheTag = buildkitCacheTag(name);
       cacheExport = [
         "--cache-to",
         `type=local,dest=${_localCacheDir},mode=max,compression=uncompressed,force-compression=true,tag=${cacheTag}`,

package/src/harness/image-cache.test.ts

@@ -28,7 +28,7 @@ describe("isOnImageCache", () => {
   });
 });
 
-import { mergeCacheIndex, type OciIndex } from "./image-cache";
+import { BUILDKIT_CACHE_TAG_PREFIX, buildkitCacheTag, mergeCacheIndex, type OciIndex } from "./image-cache";
 
 const entry = (tag: string, hex: string) => ({ mediaType: "application/vnd.oci.image.manifest.v1+json", digest: `sha256:${hex}`, size: 1, annotations: { "org.opencontainers.image.ref.name": tag } });
 
@@ -62,4 +62,20 @@ describe("mergeCacheIndex", () => {
     const out = mergeCacheIndex(lower, upper, () => true);
     expect(out.manifests.map((m) => m.annotations?.["org.opencontainers.image.ref.name"])).toEqual(["api", "cli", "worker"]);
   });
+
+  /** The directory is one tag namespace shared with the project's own
+   *  BuildKit. The harness's tags are prefixed so a project tag named after
+   *  the same service sits beside it instead of replacing it. */
+  test("a project's tag and the harness's tag for the same service both survive", () => {
+    const both: OciIndex = { schemaVersion: 2, manifests: [entry("nginx-mod", "p1"), entry(buildkitCacheTag("nginx-mod"), "h1")] };
+    const out = mergeCacheIndex(both, null, () => false);
+    expect(out.manifests.map((m) => m.digest)).toEqual(["sha256:p1", "sha256:h1"]);
+  });
+});
+
+describe("buildkitCacheTag", () => {
+  test("the reserved prefix plus the normalised service name", () => {
+    expect(buildkitCacheTag("nginx-mod")).toBe(`${BUILDKIT_CACHE_TAG_PREFIX}nginx-mod`);
+    expect(buildkitCacheTag("Api_v2")).toBe("spectest/service/api-v2");
+  });
 });

package/src/harness/image-cache.ts

@@ -66,6 +66,27 @@ export const BUILDKIT_CACHE_DIR = "spectest-buildkit-cache";
  */
 export const BUILDKIT_CACHE_UNION = "/var/lib/spectest-buildkit-cache";
 
+/**
+ * The prefix under which the harness tags its own exports in that
+ * directory. It is one flat tag namespace shared with the project's own
+ * BuildKit (the `/services` docs page tells it to mount the union), tags
+ * merge newest-wins with no warning, and a project naturally tags a build
+ * after the thing it builds — which is what its spectest service is named
+ * too. So the harness's tags live under a prefix no project would choose,
+ * and the docs reserve it. Reported by Specific 2026-09-06: a service
+ * `nginx-mod` running `buildctl` tagged its cache `nginx-mod`, and it and
+ * the harness's image build for that very container overwrote each other
+ * on alternate boots.
+ */
+export const BUILDKIT_CACHE_TAG_PREFIX = "spectest/service/";
+
+/** The BuildKit cache tag for a service's Dockerfile build: the prefix plus
+ *  the service name, lowercased with anything outside `[a-z0-9-]` folded
+ *  to `-`. */
+export function buildkitCacheTag(service: string): string {
+  return `${BUILDKIT_CACHE_TAG_PREFIX}${service.replace(/[^a-z0-9-]/gi, "-").toLowerCase()}`;
+}
+
 function parse(raw: string): ImageCachePaths | null {
   const parsed = JSON.parse(raw) as { disks?: { role?: string; path?: string }[] };
   const root = (parsed.disks ?? []).find((d) => d.role === "root" && d.path)?.path;