@tokenoftrust/storefront-runner 2.4.5 → 2.4.6

package/apps/storefront/test/pipeline/pipeline-host.ts

@@ -16,7 +16,7 @@ import { registerPreviewJobKinds, type PreviewJobTiming } from "../../src/lib/pi
 import { configureFake, fakePreviewServices, readFakeState, type FakeFault, type FakeState } from "./fake-preview-services";
 import { readLivePointer } from "../../src/lib/pipeline/publish/live-pointer";
 import { listReleaseReceipts, readReleaseTruth } from "../../src/lib/change/store/aggregate-release-store";
-import { seedGreenAggregate, testVersionStore } from "../../src/lib/pipeline/publish/publish-test-support";
+import { projectionStore, seedGreenAggregate, testVersionStore, type TestKv } from "../../src/lib/pipeline/publish/publish-test-support";
 import {
   armedAtFaults,
   armPublishFault,
@@ -40,9 +40,31 @@ export class TenantPipeline extends DeployedTenantPipeline {
     return registerHarnessPublishKinds(
       ctx,
       registerPreviewJobKinds(syntheticJobKinds(ctx), fakePreviewServices(ctx), HARNESS_PREVIEW_TIMING),
+      this.pointers,
     );
   }
 
+  /**
+   * The pointer is projected to the harness KV (the object's SQLite), where `live` reads it as the
+   * edge would. `failPointerPuts` makes the next N puts of a pointer key fail (a KV write lost).
+   */
+  protected override async pointerKv(): Promise<TestKv | null> {
+    const { kv } = publishWorldOf(this.ctx);
+    const { sql } = this.ctx.storage;
+    sql.exec(`CREATE TABLE IF NOT EXISTS harness_pointer_faults (k INTEGER PRIMARY KEY CHECK (k = 1), remaining INTEGER NOT NULL)`);
+    return {
+      ...kv,
+      put: async (key, value) => {
+        const remaining = sql.exec<{ remaining: number }>(`SELECT remaining FROM harness_pointer_faults`).toArray()[0]?.remaining ?? 0;
+        if (key.startsWith("cust:pointer:") && remaining > 0) {
+          sql.exec(`UPDATE harness_pointer_faults SET remaining = remaining - 1`);
+          throw new Error("synthetic KV put failure");
+        }
+        await kv.put(key, value);
+      },
+    };
+  }
+
   /** Harness-only: open candidates and arm faults for the fake preview services. */
   async configureFake(config: {
     open?: { changeId: string; headSha: string }[];
@@ -65,7 +87,10 @@ export class TenantPipeline extends DeployedTenantPipeline {
   /** Harness-only: arrange and read the publish stand-in world inside this object's storage. */
   async publishHarness(op: string, args: Record<string, unknown> = {}): Promise<unknown> {
     const { kv, world } = publishWorldOf(this.ctx);
-    const store = testVersionStore(kv);
+    // Arranging goes through the object's own pointer authority; `live` and `pointer` read the KV
+    // projection — what the edge serves.
+    const store = testVersionStore(kv, this.pointers);
+    const projection = projectionStore(kv);
     const tenantId = String(args.tenantId ?? "");
     switch (op) {
       case "configure":
@@ -84,11 +109,20 @@ export class TenantPipeline extends DeployedTenantPipeline {
       case "promotionStatus":
         return world.promotionStatus();
       case "live":
-        return readLivePointer(store, tenantId);
+        return readLivePointer(projection, tenantId);
+      case "pointer":
+        return projection.getPointer(tenantId);
       case "receipts":
         return (await listReleaseReceipts(kv, tenantId, "preview")).map((r) => r.receiptId);
       case "truth":
         return readReleaseTruth(kv, tenantId, "preview");
+      case "failPointerPuts":
+        this.ctx.storage.sql.exec(`CREATE TABLE IF NOT EXISTS harness_pointer_faults (k INTEGER PRIMARY KEY CHECK (k = 1), remaining INTEGER NOT NULL)`);
+        this.ctx.storage.sql.exec(
+          `INSERT INTO harness_pointer_faults (k, remaining) VALUES (1, ?) ON CONFLICT(k) DO UPDATE SET remaining = excluded.remaining`,
+          Number(args.times ?? 1),
+        );
+        return null;
       case "armFault":
         armPublishFault(this.ctx, args as unknown as PublishFault);
         return null;

package/apps/storefront/test/pipeline/publish-kinds.ts

@@ -11,13 +11,26 @@
  * Faults are armed per object (each test uses its own tenant) at a named step — or `on-terminal`, the
  * kind's compensation after a terminal transition — `before` its work or `after` it (once the work
  * is done, before the engine records the step): `evict` aborts the
- * object, `throw` fails the attempt. A fault's remaining count is persisted (and flushed) before it
- * acts, so it survives the eviction it causes.
+ * object, `throw` fails the attempt, `preview-write` moves the shared preview channel to `versionId`
+ * through the object's pointer authority (what a preview job does) and lets the step go on. A fault's
+ * remaining count is persisted (and flushed) before it acts, so it survives the eviction it causes.
+ *
+ * The job's version store writes the pointer through the object's own pointer authority (its
+ * SQLite record, projected to the harness KV) — the production writer.
  */
 import type { DurableObjectState } from "cloudflare:workers";
 import { JobKindRegistry, type JobKindDefinition, type StepDefinition } from "../../src/lib/pipeline/job-runner";
 import { registerPublishJobKinds, type PublishKindTuning, type PublishTiming } from "../../src/lib/pipeline/publish/publish-job";
-import { PublishWorld, standInPublishEnvironment, type TestKv } from "../../src/lib/pipeline/publish/publish-test-support";
+import {
+  PublishWorld,
+  movePreview,
+  standInPublishEnvironment,
+  testVersionStore,
+  type TestKv,
+} from "../../src/lib/pipeline/publish/publish-test-support";
+
+type SiteVersionStore = ReturnType<typeof testVersionStore>;
+type PointerWriter = NonNullable<Parameters<typeof testVersionStore>[1]>;
 
 export const PUBLISH_HARNESS_TIMING: PublishTiming = {
   awaitWindowMs: 1_500,
@@ -39,7 +52,9 @@ export const PUBLISH_HARNESS_TUNING: PublishKindTuning = {
 export interface PublishFault {
   step: string;
   at: "before" | "after";
-  mode: "evict" | "throw";
+  mode: "evict" | "throw" | "preview-write";
+  /** `preview-write`: the version the preview channel moves to. */
+  versionId?: string;
   /** How many times it fires (default 1). */
   times?: number;
 }
@@ -47,7 +62,7 @@ export interface PublishFault {
 function tables(state: DurableObjectState): void {
   const { sql } = state.storage;
   sql.exec(`CREATE TABLE IF NOT EXISTS harness_kv (key TEXT PRIMARY KEY, value TEXT NOT NULL)`);
-  sql.exec(`CREATE TABLE IF NOT EXISTS harness_publish_faults (id INTEGER PRIMARY KEY AUTOINCREMENT, step TEXT, at TEXT, mode TEXT, remaining INTEGER)`);
+  sql.exec(`CREATE TABLE IF NOT EXISTS harness_publish_faults (id INTEGER PRIMARY KEY AUTOINCREMENT, step TEXT, at TEXT, mode TEXT, remaining INTEGER, version_id TEXT)`);
   sql.exec(`CREATE TABLE IF NOT EXISTS harness_publish_fired (seq INTEGER PRIMARY KEY AUTOINCREMENT, step TEXT, at TEXT, mode TEXT)`);
   sql.exec(`CREATE TABLE IF NOT EXISTS harness_publish_armed (seq INTEGER PRIMARY KEY AUTOINCREMENT, step TEXT, at TEXT, armed INTEGER)`);
 }
@@ -87,11 +102,12 @@ export function sqlKv(state: DurableObjectState): TestKv {
 export function armPublishFault(state: DurableObjectState, fault: PublishFault): void {
   tables(state);
   state.storage.sql.exec(
-    `INSERT INTO harness_publish_faults (step, at, mode, remaining) VALUES (?, ?, ?, ?)`,
+    `INSERT INTO harness_publish_faults (step, at, mode, remaining, version_id) VALUES (?, ?, ?, ?, ?)`,
     fault.step,
     fault.at,
     fault.mode,
     fault.times ?? 1,
+    fault.versionId ?? null,
   );
 }
 
@@ -100,10 +116,19 @@ export function firedPublishFaults(state: DurableObjectState): { step: string; a
   return state.storage.sql.exec<{ step: string; at: string; mode: string }>(`SELECT step, at, mode FROM harness_publish_fired ORDER BY seq`).toArray();
 }
 
-async function maybeFault(state: DurableObjectState, step: string, at: "before" | "after"): Promise<void> {
+interface FaultScope {
+  tenantId: string;
+  store: SiteVersionStore;
+}
+
+async function maybeFault(state: DurableObjectState, step: string, at: "before" | "after", scope: FaultScope | null): Promise<void> {
   const { sql } = state.storage;
   const fault = sql
-    .exec<{ id: number; mode: string }>(`SELECT id, mode FROM harness_publish_faults WHERE step = ? AND at = ? AND remaining > 0 ORDER BY id LIMIT 1`, step, at)
+    .exec<{ id: number; mode: string; version_id: string | null }>(
+      `SELECT id, mode, version_id FROM harness_publish_faults WHERE step = ? AND at = ? AND remaining > 0 ORDER BY id LIMIT 1`,
+      step,
+      at,
+    )
     .toArray()[0];
   if (!fault) return;
   sql.exec(`UPDATE harness_publish_faults SET remaining = remaining - 1 WHERE id = ?`, fault.id);
@@ -112,6 +137,11 @@ async function maybeFault(state: DurableObjectState, step: string, at: "before"
   // Everything written so far — including a step's own effect, for an `after` fault — is made
   // durable first, exactly as a real crash after the write would leave it.
   await state.storage.sync();
+  if (fault.mode === "preview-write") {
+    if (!scope || !fault.version_id) throw new Error(`a preview-write fault needs a job step and a version (${at} ${step})`);
+    await movePreview(scope.store, scope.tenantId, fault.version_id);
+    return;
+  }
   if (fault.mode === "evict") {
     state.abort(`synthetic eviction ${at} ${step}`);
     throw new Error("abort() returned");
@@ -119,7 +149,7 @@ async function maybeFault(state: DurableObjectState, step: string, at: "before"
   throw new Error(`synthetic fault ${at} ${step}`);
 }
 
-function withFaults(state: DurableObjectState, definition: JobKindDefinition<unknown>): JobKindDefinition<unknown> {
+function withFaults(state: DurableObjectState, definition: JobKindDefinition<unknown>, store: SiteVersionStore): JobKindDefinition<unknown> {
   const onTerminal = definition.onTerminal;
   return {
     ...definition,
@@ -127,7 +157,7 @@ function withFaults(state: DurableObjectState, definition: JobKindDefinition<unk
     ...(onTerminal
       ? {
           onTerminal: async (info: Parameters<NonNullable<JobKindDefinition<unknown>["onTerminal"]>>[0]) => {
-            await maybeFault(state, "on-terminal", "before");
+            await maybeFault(state, "on-terminal", "before", null);
             await onTerminal(info);
           },
         }
@@ -136,9 +166,9 @@ function withFaults(state: DurableObjectState, definition: JobKindDefinition<unk
       (step): StepDefinition<unknown> => ({
         ...step,
         async run(ctx) {
-          await maybeFault(state, step.name, "before");
+          await maybeFault(state, step.name, "before", { tenantId: ctx.tenantId, store });
           const outcome = await step.run(ctx);
-          await maybeFault(state, step.name, "after");
+          await maybeFault(state, step.name, "after", { tenantId: ctx.tenantId, store });
           return outcome;
         },
       }),
@@ -152,11 +182,12 @@ export function publishWorldOf(state: DurableObjectState): { kv: TestKv; world:
   return { kv, world: new PublishWorld(kv) };
 }
 
-/** Register the publish kinds (fault-wrapped, over the stand-in world) into `registry`. */
-export function registerHarnessPublishKinds(state: DurableObjectState, registry: JobKindRegistry): JobKindRegistry {
+/** Register the publish kinds (fault-wrapped, over the stand-in world) into `registry`; `pointers` is the object's authority. */
+export function registerHarnessPublishKinds(state: DurableObjectState, registry: JobKindRegistry, pointers: PointerWriter): JobKindRegistry {
   const { kv, world } = publishWorldOf(state);
-  const environment = standInPublishEnvironment({ kv, world, now: () => Date.now(), timing: PUBLISH_HARNESS_TIMING });
+  const store = testVersionStore(kv, pointers);
+  const environment = standInPublishEnvironment({ kv, world, store, now: () => Date.now(), timing: PUBLISH_HARNESS_TIMING });
   const kinds = registerPublishJobKinds(new JobKindRegistry(), async () => environment, PUBLISH_HARNESS_TUNING);
-  for (const name of kinds.list()) registry.register(withFaults(state, kinds.get(name)!));
+  for (const name of kinds.list()) registry.register(withFaults(state, kinds.get(name)!, store));
   return registry;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.4.5",
+  "version": "2.4.6",
   "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/src/customization-versioning.ts

@@ -46,7 +46,13 @@ export type ChannelPointers = Partial<Record<ChannelName, string>>;
  *   — and are written in the SAME CAS pointer write (`setChannel`), so they can
  *   never drift. Absent for a hosted tenant (which only ever sets/reads
  *   `channels`).
- * - `rev`: optimistic-concurrency token, incremented on every successful write.
+ * - `rev`: the record's revision, incremented on every successful write. The CAS token for a
+ *   write of the per-path `live` / `test` selections.
+ * - `channelRevs`: each channel's own revision, incremented only when that channel moves (absent
+ *   = 0). The CAS token for a write of that channel, so a `preview` move never conflicts with —
+ *   or stands down — a `live` write, and the reverse.
+ *
+ * The edge reads this record from KV; the tenant's pipeline Durable Object is its only writer.
  */
 export interface PointerRecord {
   tenantId: string;
@@ -55,6 +61,7 @@ export interface PointerRecord {
   test: Selection;
   channels?: ChannelPointers;
   channelDigests?: ChannelPointers;
+  channelRevs?: Partial<Record<ChannelName, number>>;
 }
 
 export function emptyPointer(tenantId: string): PointerRecord {

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

@@ -91,12 +91,22 @@ export const ASSET_SHA256_METADATA_KEY = "sha256";
 /** Per-tenant asset pointer: the live/test snapshot versionId + a CAS token. */
 export interface AssetsPointer {
   tenantId: string;
-  /** Optimistic-concurrency token; bumped on every successful write. */
+  /** The record's revision; bumped on every successful write. */
   rev: number;
   /** Snapshot versionId selected for the live channel (null = none published). */
   live: string | null;
   /** Snapshot versionId selected for the test channel. */
   test: string | null;
+  /**
+   * Each channel's own revision, bumped only when that channel moves (absent = 0): the CAS token
+   * for a write of that channel, so a `test` move never conflicts with a `live` write.
+   */
+  channelRevs?: Partial<Record<CustomizationEnv, number>>;
+}
+
+/** A channel's own revision (0 before its first write) — the token a write of that channel presents. */
+export function assetsChannelRev(pointer: AssetsPointer, channel: CustomizationEnv): number {
+  return pointer.channelRevs?.[channel] ?? 0;
 }
 
 export function emptyAssetsPointer(tenantId: string): AssetsPointer {
@@ -397,6 +407,7 @@ export async function readAssetsPointer(
       rev: typeof p.rev === "number" ? p.rev : 0,
       live: typeof p.live === "string" ? p.live : null,
       test: typeof p.test === "string" ? p.test : null,
+      ...(p.channelRevs && typeof p.channelRevs === "object" ? { channelRevs: { ...p.channelRevs } } : {}),
     };
   } catch {
     // Fail safe: a malformed record reads as empty (never wedges writes).
@@ -416,62 +427,65 @@ export class AssetsPointerConflictError extends Error {
     readonly tenantId: string,
     readonly expectedRev: number,
     readonly foundRev: number,
+    readonly channel?: CustomizationEnv,
   ) {
     super(
-      `Assets pointer for "${tenantId}" changed (expected rev ${expectedRev}, found ${foundRev}).`,
+      `Assets pointer for "${tenantId}" changed (${channel ? `channel ${channel}: ` : ""}expected rev ${expectedRev}, found ${foundRev}).`,
     );
     this.name = "AssetsPointerConflictError";
   }
 }
 
+/** The record a write of `channel` stores over `current`: that channel, its revision and the record's bumped. */
+function movedChannel(current: AssetsPointer, channel: CustomizationEnv, versionId: string | null): AssetsPointer {
+  return {
+    ...current,
+    rev: current.rev + 1,
+    [channel]: versionId,
+    channelRevs: { ...current.channelRevs, [channel]: assetsChannelRev(current, channel) + 1 },
+  };
+}
+
 /**
- * Point a channel at a snapshot versionId — or unset it with `null` (CAS on `rev`). KV has no hardware CAS,
- * so the caller reads the pointer once, passes its `rev` as `expectedRev`, and
- * this rejects the write if the stored `rev` has since moved — two concurrent
- * asset-promotions for one tenant can no longer silently clobber each other
- * (last-write-wins on the whole record). Same shape as
- * `KVVersionStore.setChannel(..., expectedRev)`.
+ * Point a channel at a snapshot versionId — or unset it with `null` — CAS on THAT CHANNEL's
+ * revision (`assetsChannelRev`). KV has no hardware CAS, so the caller reads the pointer once,
+ * passes the channel's revision as `expectedChannelRev`, and this rejects the write if it has since
+ * moved — two concurrent writes of one channel can no longer silently clobber each other, while a
+ * write of the other channel never refuses this one. Same shape as `KVVersionStore.setChannel`.
  */
 export async function setAssetsChannel(
   kv: AssetsKv,
   tenantId: string,
   channel: CustomizationEnv,
   versionId: string | null,
-  expectedRev: number,
+  expectedChannelRev: number,
 ): Promise<AssetsPointer> {
   const current = await readAssetsPointer(kv, tenantId);
-  if (current.rev !== expectedRev) {
-    throw new AssetsPointerConflictError(tenantId, expectedRev, current.rev);
+  const found = assetsChannelRev(current, channel);
+  if (found !== expectedChannelRev) {
+    throw new AssetsPointerConflictError(tenantId, expectedChannelRev, found, channel);
   }
-  const next: AssetsPointer = {
-    ...current,
-    rev: current.rev + 1,
-    [channel]: versionId,
-  };
+  const next = movedChannel(current, channel, versionId);
   await kv.put(assetsPointerKey(tenantId), JSON.stringify(next));
   return next;
 }
 
 /**
- * Promote the test snapshot to live (atomic pointer flip), CAS-guarded on `rev`.
- * The caller supplies `expectedRev` from a single prior `readAssetsPointer`; a
- * concurrent write that lands in between throws `AssetsPointerConflictError`
- * rather than being silently overwritten.
+ * Promote the test snapshot to live (atomic pointer flip), CAS-guarded on the `live` channel's
+ * revision. The caller supplies it from a single prior `readAssetsPointer`; a `live` write that
+ * lands in between throws `AssetsPointerConflictError` rather than being silently overwritten.
  */
 export async function promoteAssets(
   kv: AssetsKv,
   tenantId: string,
-  expectedRev: number,
+  expectedLiveRev: number,
 ): Promise<AssetsPointer> {
   const current = await readAssetsPointer(kv, tenantId);
-  if (current.rev !== expectedRev) {
-    throw new AssetsPointerConflictError(tenantId, expectedRev, current.rev);
+  const found = assetsChannelRev(current, "live");
+  if (found !== expectedLiveRev) {
+    throw new AssetsPointerConflictError(tenantId, expectedLiveRev, found, "live");
   }
-  const next: AssetsPointer = {
-    ...current,
-    rev: current.rev + 1,
-    live: current.test,
-  };
+  const next = movedChannel(current, "live", current.test);
   await kv.put(assetsPointerKey(tenantId), JSON.stringify(next));
   return next;
 }