@tokenoftrust/storefront-runner 2.2.24 → 2.2.26

package/apps/storefront/src/lib/assets/durableAssetsRoute.ts

@@ -0,0 +1,65 @@
+/**
+ * Owner operations on durable images (ADR 0038): the status of every designated image, and the
+ * explicit, recorded removal. Pure handlers over injected seams; the Astro routes in
+ * `pages/api/changes/durable-assets/` bind the session, tenant config and TENANT_CACHE.
+ *
+ * Removal is the ONLY way a durable image stops being durable. It refuses an entry the latest
+ * published declaration still lists (drop it from `content/durable-assets.json` and publish first),
+ * records `{entry, actorId, at}` with the owner's opaque actor id, and never deletes anything
+ * itself: both pool GCs release the hold once the removal is older than the normal grace.
+ */
+import {
+  durableAssetsStatusKey,
+  durableStatusView,
+  parseDurableAssetsStatus,
+  removeDurableEntry,
+} from "@tot/public-runtime/durable-assets";
+
+export interface DurableRouteDeps {
+  tenantId: string;
+  servingProvider: string | null | undefined;
+  /** The tenant's public origin (`https://<canonical host>`), where `/_a/<entry>` is served. */
+  publicOrigin: string | null;
+  kv: { get(key: string): Promise<string | null>; put(key: string, value: string): Promise<void> };
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json", "cache-control": "no-store" } });
+}
+
+export async function handleDurableStatus(deps: DurableRouteDeps): Promise<Response> {
+  const raw = await deps.kv.get(durableAssetsStatusKey(deps.tenantId));
+  const record = parseDurableAssetsStatus(raw, deps.tenantId);
+  if (raw && !record) return json({ ok: false, error: "The durable image record could not be read." }, 503);
+  if (!record) return json({ ok: true, images: [], removals: [] });
+  return json({
+    ok: true,
+    images: durableStatusView(record, { provider: deps.servingProvider, publicOrigin: deps.publicOrigin }),
+    // Who removed what, and when — opaque actor ids only.
+    removals: record.removals,
+  });
+}
+
+export async function handleDurableRemove(deps: DurableRouteDeps & { actorId: string; body: unknown; now?: () => Date }): Promise<Response> {
+  const entry = (deps.body as { entry?: unknown } | null)?.entry;
+  if (typeof entry !== "string" || !/^[0-9a-f]{64}\.[A-Za-z0-9]+$/.test(entry)) {
+    return json({ ok: false, error: "entry must be the image's <sha256><ext> (the tail of its /_a/ URL)." }, 400);
+  }
+  const key = durableAssetsStatusKey(deps.tenantId);
+  const raw = await deps.kv.get(key);
+  const record = parseDurableAssetsStatus(raw, deps.tenantId);
+  if (!record) {
+    return json({ ok: false, error: raw ? "The durable image record could not be read." : "No durable images are designated." }, raw ? 503 : 404);
+  }
+  const decision = removeDurableEntry(record, { entry, actorId: deps.actorId, at: (deps.now ?? (() => new Date()))().toISOString() });
+  if (!decision.ok) {
+    const message = {
+      "unknown-entry": "That image is not designated as durable.",
+      "still-declared": "The published declaration still lists this image. Remove it from content/durable-assets.json and publish, then remove it here.",
+      "invalid-actor": "The removal could not be attributed to an owner.",
+    }[decision.reason];
+    return json({ ok: false, reason: decision.reason, error: message }, decision.reason === "unknown-entry" ? 404 : 409);
+  }
+  await deps.kv.put(key, JSON.stringify(decision.record));
+  return json({ ok: true, removed: entry, releasedAfter: "the normal collection grace (about one day)" });
+}

package/apps/storefront/src/lib/assets/durableR2.ts

@@ -0,0 +1,294 @@
+/**
+ * The Cloudflare (R2) half of captured-original staging and durable images (ADR 0038). Worker-safe:
+ * R2 bindings, KV and Web Crypto only. The S3 half is `scripts/publish/lib/hosted-original-publication*.mjs`;
+ * both obey the same hold, lease and status rules (`@tot/public-runtime/retention-holds`,
+ * `@tot/public-runtime/durable-assets`).
+ *
+ * Order, always: write the references (version manifest already in R2, or the holds), wait while a
+ * bundle-GC sweep holds its lease, then stage and verify every object those references name.
+ */
+import { sha256Hex } from "@tot/public-runtime";
+import { PINNED_ASSET_MEDIA_TYPE_BY_EXTENSION } from "@tot/public-runtime/hosted-image-media-types";
+import {
+  durableAssetsStatusKey,
+  durableCaptureRevisionId,
+  durableHoldKey,
+  emptyDurableAssetsStatus,
+  mergeDurableDesignations,
+  parseDurableAssetsStatus,
+  type DurableAssetRecord,
+} from "@tot/public-runtime/durable-assets";
+import { GC_LEASE_KEY, awaitGcQuiescence } from "@tot/public-runtime/retention-holds";
+
+const MAX_IMAGE = 8 * 1024 * 1024;
+const MAX_MANIFEST = 1024 * 1024;
+const POOL_ENTRY_RE = /^([0-9a-f]{64})(\.[A-Za-z0-9]+)$/;
+const IMMUTABLE = "public, max-age=31536000, immutable";
+
+export interface R2ObjectLike {
+  size: number;
+  body?: ReadableStream<Uint8Array> | null;
+  arrayBuffer?(): Promise<ArrayBuffer>;
+}
+
+export interface R2BucketLike {
+  get(key: string): Promise<R2ObjectLike | null>;
+  put?(key: string, body: Uint8Array, options: {
+    httpMetadata: { contentType: string; cacheControl: string };
+    onlyIf?: Headers;
+  }): Promise<unknown>;
+}
+
+export interface StatusKvLike {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string): Promise<void>;
+}
+
+export type QuiescenceWaiter = (opts: { readLease(): Promise<Uint8Array | null> }) => Promise<{ waited: boolean }>;
+
+export class R2StagingError extends Error {
+  constructor(readonly code: string) {
+    super(`Cloudflare original staging refused (${code}).`);
+    this.name = "R2StagingError";
+  }
+}
+
+export async function readBounded(bucket: R2BucketLike, key: string, limit: number): Promise<Uint8Array | null> {
+  const object = await bucket.get(key);
+  if (!object) return null;
+  if (!Number.isSafeInteger(object.size) || object.size < 0 || object.size > limit) return null;
+  if (!object.body) {
+    if (!object.arrayBuffer) return null;
+    const whole = new Uint8Array(await object.arrayBuffer());
+    return whole.byteLength === object.size ? whole : null;
+  }
+  const reader = object.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > object.size || size > limit) {
+        await reader.cancel();
+        return null;
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  if (size !== object.size) return null;
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+
+/** Wait while a bundle-GC sweep holds its lease in `bucket`. */
+export function awaitR2Quiescence(bucket: R2BucketLike, waiter: QuiescenceWaiter = awaitGcQuiescence): Promise<{ waited: boolean }> {
+  return waiter({ readLease: () => readBounded(bucket, GC_LEASE_KEY, 64 * 1024) });
+}
+
+/** Present with exactly `bytes`, writing it create-only when absent; refuses a mismatched object. */
+export async function ensurePoolObject(bucket: R2BucketLike, key: string, bytes: Uint8Array, mediaType: string): Promise<void> {
+  const address = POOL_ENTRY_RE.exec(key.replace(/^assets\//, ""))?.[1];
+  if (!address) throw new R2StagingError("pool-key");
+  const existing = await readBounded(bucket, key, MAX_IMAGE);
+  if (existing && await sha256Hex(existing) !== address) throw new R2StagingError("store-mismatch");
+  if (!existing) {
+    if (!bucket.put) throw new R2StagingError("store-unwritable");
+    await bucket.put(key, bytes, {
+      httpMetadata: { contentType: mediaType, cacheControl: IMMUTABLE },
+      onlyIf: new Headers({ "If-None-Match": "*" }),
+    });
+  }
+  const readback = await readBounded(bucket, key, MAX_IMAGE);
+  if (!readback || readback.byteLength !== bytes.byteLength || await sha256Hex(readback) !== address) {
+    throw new R2StagingError("store-mismatch");
+  }
+}
+
+/** Create a retention hold create-only (an existing hold is left as it is) and prove it exists. */
+export async function createHold(bucket: R2BucketLike, key: string, body: unknown): Promise<void> {
+  if (!bucket.put) throw new R2StagingError("store-unwritable");
+  await bucket.put(key, new TextEncoder().encode(JSON.stringify(body)), {
+    httpMetadata: { contentType: "application/json", cacheControl: "no-store" },
+    onlyIf: new Headers({ "If-None-Match": "*" }),
+  });
+  if (!(await bucket.get(key))) throw new R2StagingError("hold-missing");
+}
+
+function mediaTypeOf(entry: string): string {
+  const ext = POOL_ENTRY_RE.exec(entry)?.[2] ?? "";
+  const mediaType = PINNED_ASSET_MEDIA_TYPE_BY_EXTENSION[ext];
+  if (!mediaType) throw new R2StagingError("media-type");
+  return mediaType;
+}
+
+/** The exact captured bytes for `<sha256><ext>` from the tenant's capture store. */
+async function capturedBytes(captureBucket: R2BucketLike, tenant: string, entry: string): Promise<Uint8Array> {
+  const address = POOL_ENTRY_RE.exec(entry)?.[1];
+  if (!address) throw new R2StagingError("pool-key");
+  const bytes = await readBounded(captureBucket, `original-images/${tenant}/objects/${address}`, MAX_IMAGE);
+  if (!bytes || bytes.byteLength < 1 || await sha256Hex(bytes) !== address) throw new R2StagingError("original-missing");
+  return bytes;
+}
+
+/**
+ * Stage every captured original a version manifest records (`capturedOriginals`) into the public
+ * pool. The caller has already established the reference (the version manifest in this bucket) and
+ * waited at the fence.
+ */
+export async function stageCapturedOriginalsR2(input: {
+  tenant: string;
+  entries: readonly string[];
+  captureBucket: R2BucketLike;
+  publicBucket: R2BucketLike;
+}): Promise<number> {
+  let staged = 0;
+  for (const entry of input.entries) {
+    const key = `assets/${entry}`;
+    const present = await readBounded(input.publicBucket, key, MAX_IMAGE);
+    const address = POOL_ENTRY_RE.exec(entry)?.[1];
+    if (present && address && await sha256Hex(present) === address) continue;
+    await ensurePoolObject(input.publicBucket, key, await capturedBytes(input.captureBucket, input.tenant, entry), mediaTypeOf(entry));
+    staged++;
+  }
+  return staged;
+}
+
+export interface DeclaredDurableImage {
+  index: number;
+  name: string | null;
+  source: string;
+  locator: string;
+}
+
+/** Read-modify-write the status record; FAIL CLOSED on a record that exists but cannot be read. */
+export async function recordDurableStatusKv(kv: StatusKvLike, tenant: string, update: {
+  revision: string;
+  at: string;
+  designated: Array<Omit<DurableAssetRecord, "designatedAt" | "designatedRevision" | "removalRequested">>;
+  declared: readonly string[];
+}): Promise<void> {
+  const key = durableAssetsStatusKey(tenant);
+  const raw = await kv.get(key);
+  const parsed = parseDurableAssetsStatus(raw, tenant);
+  if (raw && !parsed) throw new R2StagingError("status-unreadable");
+  if (!parsed && update.designated.length === 0) return;
+  const next = mergeDurableDesignations(parsed ?? emptyDurableAssetsStatus(tenant), update);
+  await kv.put(key, JSON.stringify(next));
+}
+
+export type DurableDesignationResult =
+  | { ok: true; designated: string[] }
+  | { ok: false; reason: "durable-uncaptured"; unresolved: number[] };
+
+/**
+ * Designate the declared durable images in R2 (ADR 0038): resolve each to its sealed
+ * `durable.<revision>` capture, create its hold, record the designation, wait at the fence, then
+ * stage and verify each object (re-asserting its hold) and record it verified in `r2`.
+ */
+export async function designateDurableR2(input: {
+  tenant: string;
+  revision: string;
+  images: readonly DeclaredDurableImage[];
+  captureBucket: R2BucketLike;
+  publicBucket: R2BucketLike;
+  kv: StatusKvLike;
+  now?: () => Date;
+  awaitQuiescence?: QuiescenceWaiter;
+}): Promise<DurableDesignationResult> {
+  if (input.images.length === 0) return { ok: true, designated: [] };
+  const revision = durableCaptureRevisionId(input.revision);
+  const manifestBytes = await readBounded(input.captureBucket, `original-images/${input.tenant}/revisions/${revision}/manifest.json`, MAX_MANIFEST);
+  const byLocator = new Map<string, { address: string; byteLength: number; mediaType: string }>();
+  if (manifestBytes) {
+    const manifest = JSON.parse(new TextDecoder().decode(manifestBytes)) as {
+      version?: unknown; revisionId?: unknown;
+      entries?: Array<{ address?: unknown; byteLength?: unknown; mediaType?: unknown; provenance?: { locator?: unknown } }>;
+    };
+    if (manifest.version !== 1 || manifest.revisionId !== revision || !Array.isArray(manifest.entries)) {
+      throw new R2StagingError("manifest-invalid");
+    }
+    for (const entry of manifest.entries) {
+      if (typeof entry?.address !== "string" || !/^[0-9a-f]{64}$/.test(entry.address) ||
+        typeof entry.byteLength !== "number" || typeof entry.mediaType !== "string" ||
+        typeof entry.provenance?.locator !== "string") throw new R2StagingError("manifest-invalid");
+      byLocator.set(entry.provenance.locator, { address: entry.address, byteLength: entry.byteLength, mediaType: entry.mediaType });
+    }
+  }
+  const unresolved = input.images.filter((image) => !byLocator.has(image.locator)).map((image) => image.index);
+  if (unresolved.length > 0) return { ok: false, reason: "durable-uncaptured", unresolved };
+
+  const extByType = Object.fromEntries(Object.entries(PINNED_ASSET_MEDIA_TYPE_BY_EXTENSION).map(([ext, type]) => [type, ext]));
+  const now = input.now ?? (() => new Date());
+  const at = now().toISOString();
+  const prepared = input.images.map((image) => {
+    const captured = byLocator.get(image.locator)!;
+    const ext = extByType[captured.mediaType];
+    if (!ext) throw new R2StagingError("media-type");
+    const entry = `${captured.address}${ext}`;
+    return { image, entry, mediaType: captured.mediaType, holdKey: durableHoldKey(input.tenant, entry),
+      holdBody: { version: 1, class: "durable", tenant: input.tenant, object: `assets/${entry}`, designatedRevision: input.revision, designatedAt: at } };
+  });
+  for (const item of prepared) await createHold(input.publicBucket, item.holdKey, item.holdBody);
+  const declared = prepared.map((item) => item.entry);
+  await recordDurableStatusKv(input.kv, input.tenant, { revision: input.revision, at, declared,
+    designated: prepared.map((item) => ({ entry: item.entry, name: item.image.name, source: item.image.source, verifiedStores: [] })) });
+  await awaitR2Quiescence(input.publicBucket, input.awaitQuiescence);
+  for (const item of prepared) {
+    await createHold(input.publicBucket, item.holdKey, item.holdBody);
+    await ensurePoolObject(input.publicBucket, `assets/${item.entry}`,
+      await capturedBytes(input.captureBucket, input.tenant, item.entry), item.mediaType);
+  }
+  await recordDurableStatusKv(input.kv, input.tenant, { revision: input.revision, at: now().toISOString(), declared,
+    designated: prepared.map((item) => ({ entry: item.entry, name: item.image.name, source: item.image.source, verifiedStores: ["r2"] })) });
+  return { ok: true, designated: declared };
+}
+
+/**
+ * The `worker-r2-pointer` go-live/rollback step that runs BEFORE the pointer moves: the target
+ * version's manifest (already staged in R2) is the reference; once no sweep is in flight, every
+ * captured original it records is staged into the public pool, and its declared durable images are
+ * designated. Without this, a pointer-served page would 404 its captured images (CI never stages
+ * captured originals into R2 for this provider).
+ */
+export function makeWorkerR2PinnedOriginalStager(deps: {
+  publicBucket: R2BucketLike;
+  captureBucket: R2BucketLike;
+  kv: StatusKvLike;
+  now?: () => Date;
+  awaitQuiescence?: QuiescenceWaiter;
+}) {
+  return async ({ tenantId, treeDigest }: { tenantId: string; versionId: string; treeDigest?: string | null }): Promise<void> => {
+    if (!treeDigest) return;
+    const bytes = await readBounded(deps.publicBucket, `versions/${treeDigest}/manifest.json`, 8 * MAX_MANIFEST);
+    if (!bytes) throw new R2StagingError("version-manifest-missing");
+    const manifest = JSON.parse(new TextDecoder().decode(bytes)) as {
+      tenant?: unknown; sourceSha?: unknown; capturedOriginals?: unknown;
+      durableAssets?: { images?: DeclaredDurableImage[] };
+    };
+    if (manifest.tenant !== tenantId) throw new R2StagingError("version-tenant-mismatch");
+    const entries = manifest.capturedOriginals ?? [];
+    if (!Array.isArray(entries) || entries.some((entry) => typeof entry !== "string" || !POOL_ENTRY_RE.test(entry))) {
+      throw new R2StagingError("manifest-invalid");
+    }
+    await awaitR2Quiescence(deps.publicBucket, deps.awaitQuiescence);
+    await stageCapturedOriginalsR2({ tenant: tenantId, entries: entries as string[],
+      captureBucket: deps.captureBucket, publicBucket: deps.publicBucket });
+    const images = manifest.durableAssets?.images ?? [];
+    if (images.length > 0) {
+      if (typeof manifest.sourceSha !== "string") throw new R2StagingError("manifest-invalid");
+      const result = await designateDurableR2({ tenant: tenantId, revision: manifest.sourceSha, images,
+        captureBucket: deps.captureBucket, publicBucket: deps.publicBucket, kv: deps.kv,
+        ...(deps.now ? { now: deps.now } : {}), ...(deps.awaitQuiescence ? { awaitQuiescence: deps.awaitQuiescence } : {}) });
+      if (!result.ok) throw new R2StagingError(result.reason);
+    }
+  };
+}

package/apps/storefront/src/lib/assets/durableR2Bindings.ts

@@ -0,0 +1,31 @@
+/**
+ * The runtime bindings for `makeWorkerR2PinnedOriginalStager`: the public pool (STATIC_BUNDLES), the
+ * capture store (PRODUCT_IMAGES, else TENANT_ASSETS — the same resolution hosted capture writes
+ * with) and TENANT_CACHE for the durable-image status record. Unbound ⇒ every pre-flip stage
+ * refuses, so a pointer-served version can never go live missing its captured images.
+ */
+import { readKv, readR2 } from "@/lib/env";
+import { makeWorkerR2PinnedOriginalStager, R2StagingError, type R2BucketLike, type StatusKvLike } from "./durableR2.js";
+
+export async function workerR2PinnedOriginalStagerFromEnv(): Promise<
+  (args: { tenantId: string; versionId: string; treeDigest?: string | null }) => Promise<void>
+> {
+  const [publicBucket, productImages, tenantAssets, kv] = await Promise.all([
+    readR2("STATIC_BUNDLES"), readR2("PRODUCT_IMAGES"), readR2("TENANT_ASSETS"), readKv("TENANT_CACHE"),
+  ]);
+  // No capture store bound: a version that records captured originals or durable images refuses
+  // when the stage reads one; a version with none needs no capture store at all.
+  const captureBucket = productImages ?? tenantAssets ?? {
+    async get() { throw new R2StagingError("capture-store-unbound"); },
+  };
+  if (!publicBucket || !kv) {
+    return async ({ treeDigest }) => {
+      if (treeDigest) throw new R2StagingError("bindings-unavailable");
+    };
+  }
+  return makeWorkerR2PinnedOriginalStager({
+    publicBucket: publicBucket as unknown as R2BucketLike,
+    captureBucket: captureBucket as unknown as R2BucketLike,
+    kv: kv as unknown as StatusKvLike,
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.2.24",
+  "version": "2.2.26",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/package.json

@@ -16,6 +16,8 @@
     "./image-finding-acceptance": "./src/image-finding-acceptance.ts",
     "./image-preview-rewrite-overlay": "./src/image-preview-rewrite-overlay.ts",
     "./hosted-image-media-types": "./src/hosted-image-media-types.ts",
+    "./durable-assets": "./src/durable-assets.ts",
+    "./retention-holds": "./src/retention-holds.ts",
     "./tenant-embed-defaults": "./src/tenant-embed-defaults.mjs",
     "./integration/lifecycle-host-asset": "./src/integration/lifecycle-host-asset.mjs",
     "./integration/native-ga4-sandbox-asset": "./src/integration/native-ga4-sandbox-asset.mjs"

package/packages/public-runtime/src/durable-assets.ts

@@ -0,0 +1,296 @@
+/**
+ * Durable public images (ADR 0038): the tenant's declaration, and the names every plane shares.
+ *
+ * A tenant lists images in `content/durable-assets.json` that must stay publicly reachable at their
+ * content-addressed `/_a/<sha256><ext>` URL until an owner explicitly removes them. Capture seals
+ * them under `durable.<revision>`; publish stages each into the pool beside a create-only retention
+ * hold that both pool GCs honour. Pure: no I/O, safe on the Worker and in Node.
+ */
+
+export const DURABLE_ASSETS_PATH = "content/durable-assets.json";
+export const DURABLE_ASSETS_MAX_IMAGES = 200;
+const MAX_DECLARATION_BYTES = 64 * 1024;
+const MAX_NAME = 120;
+const LOCAL_RE = /^(?:public|content)\/(?:[A-Za-z0-9._@~-]+\/)*[A-Za-z0-9._@~-]+\.(?:png|jpe?g|gif|webp|avif)$/i;
+const DNS_NAME = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
+const CONTROL = /[\u0000-\u001f\u007f]/;
+const POOL_ENTRY_RE = /^[0-9a-f]{64}(?:\.[A-Za-z0-9]+)?$/;
+
+export type DurableImageSource =
+  | { kind: "local"; path: string }
+  | { kind: "remote"; url: string };
+
+export interface DurableImageDeclaration {
+  /** Position in the declaration (0-based); the only handle reported back to operators. */
+  index: number;
+  name: string | null;
+  source: DurableImageSource;
+  /** The provenance locator a capture manifest records for this source. */
+  locator: string;
+}
+
+export type DurableDeclarationParse =
+  | { ok: true; images: DurableImageDeclaration[] }
+  | { ok: false; error: string };
+
+/** The capture revision durable images seal under — separate from the page manifest. */
+export function durableCaptureRevisionId(revisionId: string): string {
+  return `durable.${revisionId.replace(/^sha256:/, "sha256-")}`;
+}
+
+/** The retention hold that keeps the pool object `assets/<poolEntry>` (`<sha256><ext>`). */
+export function durableHoldKey(tenant: string, poolEntry: string): string {
+  if (!POOL_ENTRY_RE.test(poolEntry)) throw new Error("durable hold needs a <sha256><ext> pool entry");
+  return `retention/durable/${tenant}/${poolEntry}`;
+}
+
+/** KV key of the tenant's durable-image status record (status, removals with actor ids). */
+export function durableAssetsStatusKey(tenant: string): string {
+  return `durable-assets:${tenant}`;
+}
+
+function remoteLocator(url: URL): string {
+  return `${url.origin}${url.pathname}`;
+}
+
+function parseSource(raw: unknown): DurableImageSource | null {
+  if (typeof raw !== "string" || !raw || CONTROL.test(raw)) return null;
+  if (/^https:\/\//i.test(raw)) {
+    if (raw.length > 2048) return null;
+    let url: URL;
+    try {
+      url = new URL(raw);
+    } catch {
+      return null;
+    }
+    if (url.protocol !== "https:" || url.username || url.password || url.port || url.search || url.hash ||
+      raw.includes("?") || raw.includes("#") || !DNS_NAME.test(url.hostname) || url.pathname === "/") return null;
+    return { kind: "remote", url: url.href };
+  }
+  if (raw.length > 512 || raw.includes("\\") || raw.split("/").some((part) => part === "." || part === "..")) return null;
+  return LOCAL_RE.test(raw) ? { kind: "local", path: raw } : null;
+}
+
+/** The provenance locator a capture manifest records for `source` (no leading slash for local). */
+export function durableSourceLocator(source: DurableImageSource): string {
+  return source.kind === "local" ? source.path : remoteLocator(new URL(source.url));
+}
+
+/**
+ * Parse `content/durable-assets.json`. Strict: an unknown key, a malformed or duplicate source,
+ * or more than {@link DURABLE_ASSETS_MAX_IMAGES} images refuses the whole declaration, so a typo
+ * can never silently leave an image undesignated. Errors name positions, never values.
+ */
+export function parseDurableAssetsDeclaration(text: string): DurableDeclarationParse {
+  if (text.length > MAX_DECLARATION_BYTES) return { ok: false, error: "declaration is too large" };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { ok: false, error: "declaration is not valid JSON" };
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { ok: false, error: "declaration must be an object" };
+  const root = parsed as Record<string, unknown>;
+  if (Object.keys(root).some((key) => key !== "version" && key !== "images")) {
+    return { ok: false, error: "declaration has an unknown top-level key" };
+  }
+  if (root.version !== 1) return { ok: false, error: "declaration version must be 1" };
+  if (!Array.isArray(root.images)) return { ok: false, error: "declaration images must be an array" };
+  if (root.images.length > DURABLE_ASSETS_MAX_IMAGES) {
+    return { ok: false, error: `declaration lists more than ${DURABLE_ASSETS_MAX_IMAGES} images` };
+  }
+  const images: DurableImageDeclaration[] = [];
+  const seen = new Set<string>();
+  for (const [index, raw] of root.images.entries()) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { ok: false, error: `image ${index + 1} must be an object` };
+    const entry = raw as Record<string, unknown>;
+    if (Object.keys(entry).some((key) => key !== "source" && key !== "name")) {
+      return { ok: false, error: `image ${index + 1} has an unknown key` };
+    }
+    const source = parseSource(entry.source);
+    if (!source) return { ok: false, error: `image ${index + 1} has an unsupported source` };
+    if (entry.name !== undefined && (typeof entry.name !== "string" || !entry.name.trim() ||
+      entry.name.length > MAX_NAME || CONTROL.test(entry.name))) {
+      return { ok: false, error: `image ${index + 1} has an invalid name` };
+    }
+    const locator = durableSourceLocator(source);
+    if (seen.has(locator)) return { ok: false, error: `image ${index + 1} repeats an earlier source` };
+    seen.add(locator);
+    images.push({ index, name: typeof entry.name === "string" ? entry.name.trim() : null, source, locator });
+  }
+  return { ok: true, images };
+}
+
+export type DurableImageStatus = "preview-only" | "release-managed" | "durable" | "removal-requested";
+
+/** One designated image in the tenant's status record. */
+export interface DurableAssetRecord {
+  /** `<sha256><ext>` — the pool entry and the tail of its `/_a/` URL. */
+  entry: string;
+  name: string | null;
+  /** The declared source, as written in the declaration. */
+  source: string;
+  designatedAt: string;
+  /** Tenant source revision whose publish first designated it. */
+  designatedRevision: string;
+  /** Stores the object and its hold were verified in (`s3`, `r2`). */
+  verifiedStores: Array<"s3" | "r2">;
+  /** True when the latest published declaration no longer lists it (removal may be requested). */
+  removalRequested: boolean;
+}
+
+export interface DurableAssetRemoval {
+  entry: string;
+  /** Opaque actor id of the owner who removed it — never an email or name. */
+  actorId: string;
+  at: string;
+}
+
+/** `durable-assets:<tenant>` in TENANT_CACHE. */
+export interface DurableAssetsStatusRecord {
+  version: 1;
+  tenant: string;
+  updatedAt: string;
+  /** Revision of the latest publish that recorded this document. */
+  latestRevision: string | null;
+  entries: DurableAssetRecord[];
+  removals: DurableAssetRemoval[];
+}
+
+export function emptyDurableAssetsStatus(tenant: string): DurableAssetsStatusRecord {
+  return { version: 1, tenant, updatedAt: new Date(0).toISOString(), latestRevision: null, entries: [], removals: [] };
+}
+
+/** Parse a stored status record; null when absent or malformed (callers treat malformed as unknown). */
+export function parseDurableAssetsStatus(raw: string | null, tenant: string): DurableAssetsStatusRecord | null {
+  if (!raw) return null;
+  try {
+    const value = JSON.parse(raw) as Partial<DurableAssetsStatusRecord>;
+    if (value.version !== 1 || value.tenant !== tenant || !Array.isArray(value.entries) || !Array.isArray(value.removals)) return null;
+    if (value.entries.some((entry) => !entry || !POOL_ENTRY_RE.test(String(entry.entry)))) return null;
+    if (value.removals.some((removal) => !removal || !POOL_ENTRY_RE.test(String(removal.entry)) ||
+      typeof removal.actorId !== "string" || !removal.actorId || typeof removal.at !== "string")) return null;
+    return value as DurableAssetsStatusRecord;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Merge one publisher's designations into the status record. Monotonic: an entry is never dropped
+ * here — one this publish's declaration no longer lists is marked `removalRequested`, and only the
+ * owner removal operation takes it out. `verifiedStores` accumulate across publishers (each store's
+ * publisher verifies its own), and a store is only ever added by a verification.
+ * `declared` is the publish's full declaration (by entry); null when this publisher did not read
+ * the declaration (it then never marks anything removal-requested).
+ */
+export function mergeDurableDesignations(
+  current: DurableAssetsStatusRecord,
+  publish: {
+    revision: string;
+    at: string;
+    designated: Array<Omit<DurableAssetRecord, "designatedAt" | "designatedRevision" | "removalRequested">>;
+    declared?: readonly string[] | null;
+  },
+): DurableAssetsStatusRecord {
+  const byEntry = new Map(current.entries.map((entry) => [entry.entry, entry]));
+  for (const item of publish.designated) {
+    const previous = byEntry.get(item.entry);
+    byEntry.set(item.entry, {
+      ...item,
+      verifiedStores: [...new Set([...(previous?.verifiedStores ?? []), ...item.verifiedStores])].sort() as Array<"s3" | "r2">,
+      designatedAt: previous?.designatedAt ?? publish.at,
+      designatedRevision: previous?.designatedRevision ?? publish.revision,
+      removalRequested: false,
+    });
+  }
+  const declared = publish.declared === undefined
+    ? new Set(publish.designated.map((item) => item.entry))
+    : publish.declared === null ? null : new Set(publish.declared);
+  if (declared) {
+    for (const [entry, record] of byEntry) {
+      if (!declared.has(entry)) byEntry.set(entry, { ...record, removalRequested: true });
+    }
+  }
+  return {
+    ...current,
+    updatedAt: publish.at,
+    latestRevision: publish.revision,
+    entries: [...byEntry.values()].sort((a, b) => (a.entry < b.entry ? -1 : a.entry > b.entry ? 1 : 0)),
+  };
+}
+
+export type DurableRemovalDecision =
+  | { ok: true; record: DurableAssetsStatusRecord }
+  | { ok: false; reason: "unknown-entry" | "still-declared" | "invalid-actor" };
+
+/**
+ * The owner removal operation (ADR 0038 §5), as a pure step: refuse an entry the record does not
+ * hold or that the latest published declaration still lists; otherwise drop it from `entries` and
+ * append `{entry, actorId, at}` to `removals`. Both pool GCs release the hold once the removal is
+ * older than the normal grace; the object is then ordinary.
+ */
+export function removeDurableEntry(
+  record: DurableAssetsStatusRecord,
+  removal: { entry: string; actorId: string; at: string },
+): DurableRemovalDecision {
+  if (!/^[A-Za-z0-9_:.-]{1,128}$/.test(removal.actorId) || removal.actorId.includes("@")) {
+    return { ok: false, reason: "invalid-actor" };
+  }
+  const current = record.entries.find((entry) => entry.entry === removal.entry);
+  if (!current) return { ok: false, reason: "unknown-entry" };
+  if (!current.removalRequested) return { ok: false, reason: "still-declared" };
+  return {
+    ok: true,
+    record: {
+      ...record,
+      updatedAt: removal.at,
+      entries: record.entries.filter((entry) => entry.entry !== removal.entry),
+      removals: [...record.removals, { entry: removal.entry, actorId: removal.actorId, at: removal.at }],
+    },
+  };
+}
+
+export interface DurableImageStatusView {
+  entry: string;
+  name: string | null;
+  source: string;
+  status: DurableImageStatus;
+  /** Issued only once verified in every store the tenant's declared provider serves from. */
+  publicUrl: string | null;
+  designatedAt: string;
+  verifiedStores: Array<"s3" | "r2">;
+}
+
+/**
+ * The owner-facing status of every designated image: `durable` (with its public URL) once verified
+ * in every store `serving.provider` uses; `removal-requested` when the latest declaration dropped it
+ * (still held until an owner removes it); otherwise `release-managed` — published, not yet verified
+ * as durable, so only retained releases keep it.
+ */
+export function durableStatusView(
+  record: DurableAssetsStatusRecord,
+  { provider, publicOrigin }: { provider: string | null | undefined; publicOrigin: string | null },
+): DurableImageStatusView[] {
+  const required = durableRequiredStores(provider);
+  return record.entries.map((entry) => {
+    const verified = required !== null && required.every((store) => entry.verifiedStores.includes(store));
+    const status: DurableImageStatus = entry.removalRequested ? "removal-requested" : verified ? "durable" : "release-managed";
+    return {
+      entry: entry.entry,
+      name: entry.name,
+      source: entry.source,
+      status,
+      publicUrl: verified && publicOrigin ? `${publicOrigin.replace(/\/+$/, "")}/_a/${entry.entry}` : null,
+      designatedAt: entry.designatedAt,
+      verifiedStores: entry.verifiedStores,
+    };
+  });
+}
+
+/** Required stores for a declared serving provider; null when the provider cannot verify durable images. */
+export function durableRequiredStores(provider: string | null | undefined): Array<"s3" | "r2"> | null {
+  if (provider === "s3-overwrite") return ["s3"];
+  if (provider === "worker-r2-pointer") return ["r2"];
+  return null;
+}

package/packages/public-runtime/src/image-dependencies.ts

@@ -1428,9 +1428,12 @@ function collectDeclaredCustomProperties(artifacts: readonly ImageDependencyArti
 
 /** Scan a revision's already-read artifacts with no network or filesystem I/O. */
 export function scanImageDependencies(
-  artifacts: readonly ImageDependencyArtifact[],
+  scanned: readonly ImageDependencyArtifact[],
   options: ImageDependencyScanOptions,
 ): ImageDependencyScan {
+  // The durable-image declaration (ADR 0038) lists images to keep, not images a page renders; its
+  // sources are captured by the durable pass. Scanning it would turn each into a page finding.
+  const artifacts = scanned.filter((artifact) => !isDurableAssetsDeclarationPath(artifact.path));
   const dependencies: ImageDependency[] = [];
   const platformHosted = preparePlatformHostedConfig(options.platformHosted);
   const tenantOrigins = prepareTenantOrigins(options.tenantOrigins);
@@ -1548,3 +1551,8 @@ export function scanImageDependencies(
     })(),
   };
 }
+
+/** `content/durable-assets.json`, however a caller spells the artifact path. */
+export function isDurableAssetsDeclarationPath(path: string): boolean {
+  return path.replace(/^\/+/, "") === "content/durable-assets.json";
+}

package/packages/public-runtime/src/retention-holds.ts

@@ -0,0 +1,227 @@
+/**
+ * Retention holds and the pool-GC lease (ADR 0038) — ONE implementation for both stores.
+ *
+ * The S3 pool GC (`scripts/publish/gc-asset-pool.mjs`) and the R2 bundle GC
+ * (`apps/storefront/src/lib/publish/bundleGc.ts`) both import these rules, so the two CDNs cannot
+ * drift on what a hold protects, when it is released, or how a sweep and a publish order their steps.
+ *
+ * Hold keys (objects in the same bucket as the pool, `assets/<sha256><ext>`):
+ *   retention/durable/<tenant>/<sha256><ext>                              durable image (owner-removed)
+ *   retention/publication-space/<tenant>/<space>/<version>/<sha256><ext>  a publication-space version's
+ *                                                                          reference (release-managed)
+ * Any other well-formed `retention/<class>/…/<sha256><ext>` key is still a reference (fail closed):
+ * it is never released by these rules and never deleted.
+ *
+ * Lease protocol (a publish or designation never loses to a concurrent sweep):
+ *   GC        1. write the lease (expiry = now + TTL)   2. read every reference source
+ *             3. delete only while `leaseAllowsDelete`  4. remove the lease
+ *   publisher 1. write its references (version manifest, holds)
+ *             2. wait while a lease is live (`awaitGcQuiescence`)
+ *             3. verify every referenced object, re-creating any that is missing
+ * A sweep that starts after step 1 sees the references; one already running finishes (or can no
+ * longer delete) before the publisher's verification, which is therefore the last word.
+ */
+import type { DurableAssetsStatusRecord } from "./durable-assets.js";
+import type { PublicationVersionStateV1 } from "./publication-version.js";
+
+export const GC_LEASE_KEY = "retention/gc-lease.json";
+export const GC_LEASE_TTL_MS = 10 * 60 * 1000;
+/** Clock skew absorbed on both sides (the GC and the publisher run on different machines). */
+export const GC_LEASE_SKEW_MS = 60 * 1000;
+export const GC_LEASE_MAX_WAIT_MS = GC_LEASE_TTL_MS + 2 * GC_LEASE_SKEW_MS;
+/** The grace an unreferenced object gets before collection (matches both GCs' asset grace). */
+export const RELEASE_GRACE_MS = 24 * 60 * 60 * 1000;
+
+const SEG = "[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?";
+const ENTRY = "([0-9a-f]{64})(\\.[A-Za-z0-9]+)?";
+const DURABLE_RE = new RegExp(`^retention/durable/(${SEG})/${ENTRY}$`, "i");
+const SPACE_RE = new RegExp(`^retention/publication-space/(${SEG})/([A-Za-z0-9._-]{1,128})/([A-Za-z0-9._-]{1,128})/${ENTRY}$`, "i");
+const ANY_HOLD_RE = new RegExp(`^retention/[a-z][a-z-]*/.+/${ENTRY}$`, "i");
+
+export type ParsedRetentionKey =
+  | { kind: "durable"; tenant: string; hash: string; entry: string }
+  | { kind: "publication-space"; tenant: string; spaceId: string; versionId: string; hash: string; entry: string }
+  | { kind: "other-hold"; hash: string; entry: string }
+  | { kind: "lease" }
+  | { kind: "unrecognized" };
+
+export function parseRetentionKey(key: string): ParsedRetentionKey {
+  if (key === GC_LEASE_KEY) return { kind: "lease" };
+  let m = DURABLE_RE.exec(key);
+  if (m) return { kind: "durable", tenant: m[1]!, hash: m[2]!.toLowerCase(), entry: `${m[2]!.toLowerCase()}${m[3] ?? ""}` };
+  m = SPACE_RE.exec(key);
+  if (m) {
+    return { kind: "publication-space", tenant: m[1]!, spaceId: m[2]!, versionId: m[3]!,
+      hash: m[4]!.toLowerCase(), entry: `${m[4]!.toLowerCase()}${m[5] ?? ""}` };
+  }
+  m = ANY_HOLD_RE.exec(key);
+  if (m) return { kind: "other-hold", hash: m[1]!.toLowerCase(), entry: `${m[1]!.toLowerCase()}${m[2] ?? ""}` };
+  return { kind: "unrecognized" };
+}
+
+export function publicationSpaceHoldKey(tenant: string, spaceId: string, versionId: string, poolEntry: string): string {
+  return `retention/publication-space/${tenant}/${spaceId}/${versionId}/${poolEntry}`;
+}
+
+export interface HoldObject {
+  key: string;
+  /** Epoch ms the hold object was written; null when unknown (never released). */
+  createdAt: number | null;
+}
+
+export interface HoldPlanInput {
+  holds: readonly HoldObject[];
+  /** `durable-assets:<tenant>` per tenant; null = absent or unreadable (nothing released). */
+  durableRecords: ReadonlyMap<string, DurableAssetsStatusRecord | null>;
+  /** `cust:publication-state:<tenant>` per tenant; null = absent or unreadable (nothing released). */
+  spaceStates: ReadonlyMap<string, PublicationVersionStateV1 | null>;
+  now: number;
+  graceMs?: number;
+  keep?: number;
+  graceDays?: number;
+}
+
+export interface HoldPlan {
+  /** Pool hashes every kept hold references. */
+  referencedHashes: Set<string>;
+  /** Hold keys to delete this run. */
+  releaseKeys: string[];
+  /** Why each released hold goes, for the run log. */
+  reasons: Record<string, string>;
+}
+
+/**
+ * The publication-space versions still retained for `tenant`, as `<space>/<version>`: per space, the
+ * newest `keep` by creation, every version created within `graceDays` plus the newest one before the
+ * cutoff, every version a channel pointer names, and every transition's previous version (a
+ * rollback target). The same rule the whole-site planes apply to their versions.
+ */
+export function retainedPublicationVersions(
+  state: PublicationVersionStateV1,
+  { now, keep = 30, graceDays = 7 }: { now: number; keep?: number; graceDays?: number },
+): Set<string> {
+  const retained = new Set<string>();
+  const bySpace = new Map<string, Array<{ versionId: string; created: number }>>();
+  for (const version of state.versions) {
+    const list = bySpace.get(version.spaceId) ?? bySpace.set(version.spaceId, []).get(version.spaceId)!;
+    list.push({ versionId: version.versionId, created: Date.parse(version.createdAt) || 0 });
+  }
+  const cutoff = now - graceDays * 24 * 60 * 60 * 1000;
+  for (const [spaceId, list] of bySpace) {
+    list.sort((a, b) => b.created - a.created || (a.versionId < b.versionId ? 1 : -1));
+    for (const v of list.slice(0, Math.max(1, keep))) retained.add(`${spaceId}/${v.versionId}`);
+    for (const v of list) {
+      retained.add(`${spaceId}/${v.versionId}`);
+      if (!(v.created >= cutoff)) break;
+    }
+  }
+  for (const pointer of state.pointers) retained.add(`${pointer.spaceId}/${pointer.versionId}`);
+  for (const transition of state.transitions) {
+    retained.add(`${transition.spaceId}/${transition.next.versionId}`);
+    if (transition.previous) retained.add(`${transition.spaceId}/${transition.previous.versionId}`);
+  }
+  return retained;
+}
+
+/**
+ * Decide which holds stay (their hashes are references) and which are released.
+ *
+ * - durable: released only for a recorded owner removal of that entry that is older than the grace,
+ *   when the hold was created before the removal and the entry was not designated again after it.
+ * - publication-space: released when its version is no longer retained by the tenant's space state
+ *   and the hold is older than the grace. An absent or unreadable state releases nothing.
+ * - any other hold: never released.
+ */
+export function planRetentionHolds(input: HoldPlanInput): HoldPlan {
+  const graceMs = input.graceMs ?? RELEASE_GRACE_MS;
+  const referencedHashes = new Set<string>();
+  const releaseKeys: string[] = [];
+  const reasons: Record<string, string> = {};
+  const retainedByTenant = new Map<string, Set<string> | null>();
+  for (const hold of input.holds) {
+    const parsed = parseRetentionKey(hold.key);
+    if (parsed.kind === "lease" || parsed.kind === "unrecognized") continue;
+    let release = false;
+    if (parsed.kind === "durable") {
+      const record = input.durableRecords.get(parsed.tenant) ?? null;
+      const removedAt = latest(record?.removals.filter((r) => r.entry === parsed.entry).map((r) => r.at));
+      const designatedAt = latest(record?.entries.filter((e) => e.entry === parsed.entry).map((e) => e.designatedAt));
+      release = removedAt !== null && input.now >= removedAt + graceMs &&
+        (designatedAt === null || designatedAt <= removedAt) &&
+        hold.createdAt !== null && hold.createdAt < removedAt;
+      if (release) reasons[hold.key] = "durable hold released by a recorded owner removal";
+    } else if (parsed.kind === "publication-space") {
+      if (!retainedByTenant.has(parsed.tenant)) {
+        const state = input.spaceStates.get(parsed.tenant) ?? null;
+        retainedByTenant.set(parsed.tenant, state
+          ? retainedPublicationVersions(state, { now: input.now, keep: input.keep, graceDays: input.graceDays })
+          : null);
+      }
+      const retained = retainedByTenant.get(parsed.tenant);
+      release = retained != null && !retained.has(`${parsed.spaceId}/${parsed.versionId}`) &&
+        hold.createdAt !== null && input.now >= hold.createdAt + graceMs;
+      if (release) reasons[hold.key] = "publication-space version no longer retained";
+    }
+    if (release) releaseKeys.push(hold.key);
+    else referencedHashes.add(parsed.hash);
+  }
+  return { referencedHashes, releaseKeys: releaseKeys.sort(), reasons };
+}
+
+function latest(values: readonly string[] | undefined): number | null {
+  let best: number | null = null;
+  for (const value of values ?? []) {
+    const at = Date.parse(value);
+    if (Number.isFinite(at) && (best === null || at > best)) best = at;
+  }
+  return best;
+}
+
+export function newGcLease(now: number, ttlMs = GC_LEASE_TTL_MS): { version: 1; startedAt: string; expiresAt: string } {
+  return { version: 1, startedAt: new Date(now).toISOString(), expiresAt: new Date(now + ttlMs).toISOString() };
+}
+
+/** The lease's expiry, null for no lease. An unparseable lease is live for one TTL (fail closed). */
+export function gcLeaseExpiry(raw: Uint8Array | string | null, now: number): number | null {
+  if (raw == null) return null;
+  try {
+    const text = typeof raw === "string" ? raw : new TextDecoder().decode(raw);
+    const value = JSON.parse(text) as { version?: unknown; expiresAt?: unknown };
+    const expires = Date.parse(String(value?.expiresAt));
+    if (value?.version === 1 && Number.isFinite(expires)) return expires;
+  } catch {
+    // unparseable: live
+  }
+  return now + GC_LEASE_TTL_MS;
+}
+
+/** GC side: may this sweep still delete? */
+export function leaseAllowsDelete(expiresAt: number, now: number): boolean {
+  return now < expiresAt - GC_LEASE_SKEW_MS;
+}
+
+/**
+ * Publisher side: wait while a sweep's lease is live; resolves once none is. Throws when one stays
+ * live past `maxWaitMs` — the caller refuses rather than guess.
+ */
+export async function awaitGcQuiescence({
+  readLease,
+  now = Date.now,
+  sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)),
+  maxWaitMs = GC_LEASE_MAX_WAIT_MS,
+}: {
+  readLease(): Promise<Uint8Array | string | null>;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  maxWaitMs?: number;
+}): Promise<{ waited: boolean }> {
+  const started = now();
+  let waited = false;
+  for (;;) {
+    const expiry = gcLeaseExpiry(await readLease(), now());
+    if (expiry == null || now() >= expiry + GC_LEASE_SKEW_MS) return { waited };
+    if (now() - started >= maxWaitMs) throw new Error("a pool GC sweep held its lease past the publisher's wait");
+    waited = true;
+    await sleep(Math.min(5000, Math.max(250, expiry + GC_LEASE_SKEW_MS - now())));
+  }
+}