@valbuild/cli 0.103.0 → 0.103.1

package/cli/dist/valbuild-cli-cli.cjs.dev.js

@@ -1500,8 +1500,11 @@ async function buildSnapshot(ctx, options = {}) {
         path: p
       });
     }
-    entries[`.val/patches/${patch.parentPatchId ?? "head"}/patch.json`] = JSON.stringify(toFsPatch(patch), null, 2);
+    entries[`.val/patches/${patch.patchId}/patch.json`] = JSON.stringify(toFsPatch(patch), null, 2);
   }
+  // The order lives in the log, not in the records, so it has to be written too
+  // or the unzipped snapshot is a store with no order at all.
+  entries[".val/patches/patches.log"] = ["val-patch-log v1", ...patches.map(patch => `${patch.patchId} ${patch.createdAt} ${patch.path}`), ""].join("\n");
   let includesBinaryFiles = false;
   if (options.includeFiles) {
     includesBinaryFiles = await writeBinaryFiles(ctx, analysis.fileLastUpdatedByPatchId, patches, entries);
@@ -1568,34 +1571,29 @@ async function validateSnapshotSources(ctx, analysis) {
   return validationRes.errors;
 }
 function toSnapshotPatches(orderedPatches) {
-  return orderedPatches.map((patch, i) => ({
+  return orderedPatches.map(patch => ({
     patchId: patch.patchId,
     path: patch.path,
     createdAt: patch.createdAt,
     authorId: patch.authorId,
     baseSha: patch.baseSha,
     appliedAt: patch.appliedAt,
-    parentPatchId: i === 0 ? null : orderedPatches[i - 1].patchId,
     patch: patch.patch
   }));
 }
 
 /**
  * The shape ValOpsFS writes per patch, so an unzipped snapshot is a patch store
- * a plain ValOpsFS can read. The directory is named after the PARENT, and
- * createPatchChain walks the linked list from "head".
+ * a plain ValOpsFS can read.
+ *
+ * The directory is named after the patch itself and the record points at
+ * nothing: the order is in `patches.log` beside it. A record that named its
+ * parent is how a snapshot could carry a chain that had already lost a link.
  */
 function toFsPatch(patch) {
   return {
     patch: patch.patch,
     patchId: patch.patchId,
-    parentRef: patch.parentPatchId === null ? {
-      type: "head",
-      headBaseSha: patch.baseSha
-    } : {
-      type: "patch",
-      patchId: patch.parentPatchId
-    },
     path: patch.path,
     authorId: patch.authorId,
     sessionId: null,
@@ -1605,14 +1603,13 @@ function toFsPatch(patch) {
   };
 }
 async function writeBinaryFiles(ctx, fileLastUpdatedByPatchId, patches, entries) {
-  const parentByPatchId = new Map(patches.map(p => [p.patchId, p.parentPatchId ?? "head"]));
+  const known = new Set(patches.map(p => p.patchId));
   let wrote = false;
   for (const [filePath, data] of Object.entries(fileLastUpdatedByPatchId)) {
     if (data.isDelete) {
       continue;
     }
-    const parentPatchId = parentByPatchId.get(data.patchId);
-    if (parentPatchId === undefined) {
+    if (!known.has(data.patchId)) {
       continue;
     }
     const buffer = await ctx.serverOps.getBase64EncodedBinaryFileFromPatch(filePath, data.patchId, data.remote);
@@ -1620,7 +1617,7 @@ async function writeBinaryFiles(ctx, fileLastUpdatedByPatchId, patches, entries)
       continue;
     }
     // Base64 so the snapshot stays a text-only entry map; the replay decodes it.
-    entries[`.val/patches/${parentPatchId}/files${filePath}/${path__default["default"].posix.basename(filePath)}.base64`] = buffer.toString("base64");
+    entries[`.val/patches/${data.patchId}/files${filePath}/${path__default["default"].posix.basename(filePath)}.base64`] = buffer.toString("base64");
     wrote = true;
   }
   return wrote;

package/cli/dist/valbuild-cli-cli.cjs.prod.js

@@ -1500,8 +1500,11 @@ async function buildSnapshot(ctx, options = {}) {
         path: p
       });
     }
-    entries[`.val/patches/${patch.parentPatchId ?? "head"}/patch.json`] = JSON.stringify(toFsPatch(patch), null, 2);
+    entries[`.val/patches/${patch.patchId}/patch.json`] = JSON.stringify(toFsPatch(patch), null, 2);
   }
+  // The order lives in the log, not in the records, so it has to be written too
+  // or the unzipped snapshot is a store with no order at all.
+  entries[".val/patches/patches.log"] = ["val-patch-log v1", ...patches.map(patch => `${patch.patchId} ${patch.createdAt} ${patch.path}`), ""].join("\n");
   let includesBinaryFiles = false;
   if (options.includeFiles) {
     includesBinaryFiles = await writeBinaryFiles(ctx, analysis.fileLastUpdatedByPatchId, patches, entries);
@@ -1568,34 +1571,29 @@ async function validateSnapshotSources(ctx, analysis) {
   return validationRes.errors;
 }
 function toSnapshotPatches(orderedPatches) {
-  return orderedPatches.map((patch, i) => ({
+  return orderedPatches.map(patch => ({
     patchId: patch.patchId,
     path: patch.path,
     createdAt: patch.createdAt,
     authorId: patch.authorId,
     baseSha: patch.baseSha,
     appliedAt: patch.appliedAt,
-    parentPatchId: i === 0 ? null : orderedPatches[i - 1].patchId,
     patch: patch.patch
   }));
 }
 
 /**
  * The shape ValOpsFS writes per patch, so an unzipped snapshot is a patch store
- * a plain ValOpsFS can read. The directory is named after the PARENT, and
- * createPatchChain walks the linked list from "head".
+ * a plain ValOpsFS can read.
+ *
+ * The directory is named after the patch itself and the record points at
+ * nothing: the order is in `patches.log` beside it. A record that named its
+ * parent is how a snapshot could carry a chain that had already lost a link.
  */
 function toFsPatch(patch) {
   return {
     patch: patch.patch,
     patchId: patch.patchId,
-    parentRef: patch.parentPatchId === null ? {
-      type: "head",
-      headBaseSha: patch.baseSha
-    } : {
-      type: "patch",
-      patchId: patch.parentPatchId
-    },
     path: patch.path,
     authorId: patch.authorId,
     sessionId: null,
@@ -1605,14 +1603,13 @@ function toFsPatch(patch) {
   };
 }
 async function writeBinaryFiles(ctx, fileLastUpdatedByPatchId, patches, entries) {
-  const parentByPatchId = new Map(patches.map(p => [p.patchId, p.parentPatchId ?? "head"]));
+  const known = new Set(patches.map(p => p.patchId));
   let wrote = false;
   for (const [filePath, data] of Object.entries(fileLastUpdatedByPatchId)) {
     if (data.isDelete) {
       continue;
     }
-    const parentPatchId = parentByPatchId.get(data.patchId);
-    if (parentPatchId === undefined) {
+    if (!known.has(data.patchId)) {
       continue;
     }
     const buffer = await ctx.serverOps.getBase64EncodedBinaryFileFromPatch(filePath, data.patchId, data.remote);
@@ -1620,7 +1617,7 @@ async function writeBinaryFiles(ctx, fileLastUpdatedByPatchId, patches, entries)
       continue;
     }
     // Base64 so the snapshot stays a text-only entry map; the replay decodes it.
-    entries[`.val/patches/${parentPatchId}/files${filePath}/${path__default["default"].posix.basename(filePath)}.base64`] = buffer.toString("base64");
+    entries[`.val/patches/${data.patchId}/files${filePath}/${path__default["default"].posix.basename(filePath)}.base64`] = buffer.toString("base64");
     wrote = true;
   }
   return wrote;

package/cli/dist/valbuild-cli-cli.esm.js

@@ -1468,8 +1468,11 @@ async function buildSnapshot(ctx, options = {}) {
         path: p
       });
     }
-    entries[`.val/patches/${patch.parentPatchId ?? "head"}/patch.json`] = JSON.stringify(toFsPatch(patch), null, 2);
+    entries[`.val/patches/${patch.patchId}/patch.json`] = JSON.stringify(toFsPatch(patch), null, 2);
   }
+  // The order lives in the log, not in the records, so it has to be written too
+  // or the unzipped snapshot is a store with no order at all.
+  entries[".val/patches/patches.log"] = ["val-patch-log v1", ...patches.map(patch => `${patch.patchId} ${patch.createdAt} ${patch.path}`), ""].join("\n");
   let includesBinaryFiles = false;
   if (options.includeFiles) {
     includesBinaryFiles = await writeBinaryFiles(ctx, analysis.fileLastUpdatedByPatchId, patches, entries);
@@ -1536,34 +1539,29 @@ async function validateSnapshotSources(ctx, analysis) {
   return validationRes.errors;
 }
 function toSnapshotPatches(orderedPatches) {
-  return orderedPatches.map((patch, i) => ({
+  return orderedPatches.map(patch => ({
     patchId: patch.patchId,
     path: patch.path,
     createdAt: patch.createdAt,
     authorId: patch.authorId,
     baseSha: patch.baseSha,
     appliedAt: patch.appliedAt,
-    parentPatchId: i === 0 ? null : orderedPatches[i - 1].patchId,
     patch: patch.patch
   }));
 }
 
 /**
  * The shape ValOpsFS writes per patch, so an unzipped snapshot is a patch store
- * a plain ValOpsFS can read. The directory is named after the PARENT, and
- * createPatchChain walks the linked list from "head".
+ * a plain ValOpsFS can read.
+ *
+ * The directory is named after the patch itself and the record points at
+ * nothing: the order is in `patches.log` beside it. A record that named its
+ * parent is how a snapshot could carry a chain that had already lost a link.
  */
 function toFsPatch(patch) {
   return {
     patch: patch.patch,
     patchId: patch.patchId,
-    parentRef: patch.parentPatchId === null ? {
-      type: "head",
-      headBaseSha: patch.baseSha
-    } : {
-      type: "patch",
-      patchId: patch.parentPatchId
-    },
     path: patch.path,
     authorId: patch.authorId,
     sessionId: null,
@@ -1573,14 +1571,13 @@ function toFsPatch(patch) {
   };
 }
 async function writeBinaryFiles(ctx, fileLastUpdatedByPatchId, patches, entries) {
-  const parentByPatchId = new Map(patches.map(p => [p.patchId, p.parentPatchId ?? "head"]));
+  const known = new Set(patches.map(p => p.patchId));
   let wrote = false;
   for (const [filePath, data] of Object.entries(fileLastUpdatedByPatchId)) {
     if (data.isDelete) {
       continue;
     }
-    const parentPatchId = parentByPatchId.get(data.patchId);
-    if (parentPatchId === undefined) {
+    if (!known.has(data.patchId)) {
       continue;
     }
     const buffer = await ctx.serverOps.getBase64EncodedBinaryFileFromPatch(filePath, data.patchId, data.remote);
@@ -1588,7 +1585,7 @@ async function writeBinaryFiles(ctx, fileLastUpdatedByPatchId, patches, entries)
       continue;
     }
     // Base64 so the snapshot stays a text-only entry map; the replay decodes it.
-    entries[`.val/patches/${parentPatchId}/files${filePath}/${path.posix.basename(filePath)}.base64`] = buffer.toString("base64");
+    entries[`.val/patches/${data.patchId}/files${filePath}/${path.posix.basename(filePath)}.base64`] = buffer.toString("base64");
     wrote = true;
   }
   return wrote;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@valbuild/cli",
   "private": false,
-  "version": "0.103.0",
+  "version": "0.103.1",
   "description": "Val CLI tools",
   "repository": {
     "type": "git",
@@ -29,8 +29,8 @@
     "zod": "^4.3.5",
     "@valbuild/core": "0.103.0",
     "@valbuild/eslint-plugin": "0.93.0",
-    "@valbuild/language-server": "0.103.0",
-    "@valbuild/server": "0.103.0",
+    "@valbuild/language-server": "0.103.1",
+    "@valbuild/server": "0.103.1",
     "@valbuild/shared": "0.103.0"
   },
   "peerDependencies": {

package/src/__fixtures__/debug-snapshot/.val/patches/11111111-1111-4111-8111-111111111111/patch.json

@@ -1,19 +1,16 @@
 {
   "patch": [
     {
-      "op": "remove",
-      "path": ["BBL", "summary", "services", "2"]
+      "op": "replace",
+      "path": ["BBL", "title"],
+      "value": "BBL Housing"
     }
   ],
-  "patchId": "22222222-2222-4222-8222-222222222222",
-  "parentRef": {
-    "type": "patch",
-    "patchId": "11111111-1111-4111-8111-111111111111"
-  },
+  "patchId": "11111111-1111-4111-8111-111111111111",
   "path": "/content/projects.val.ts",
-  "authorId": "author-b",
+  "authorId": "author-a",
   "sessionId": null,
   "baseSha": "0000000000000000000000000000000000000000000000000000000000000000",
   "coreVersion": null,
-  "createdAt": "2026-08-11T09:00:00.000Z"
+  "createdAt": "2026-08-10T12:00:00.000Z"
 }

package/src/__fixtures__/debug-snapshot/.val/patches/22222222-2222-4222-8222-222222222222/patch.json

@@ -1,20 +1,15 @@
 {
   "patch": [
     {
-      "op": "replace",
-      "path": ["BBL", "summary", "services", "2"],
-      "value": "Development U"
+      "op": "remove",
+      "path": ["BBL", "summary", "services", "2"]
     }
   ],
-  "patchId": "33333333-3333-4333-8333-333333333333",
-  "parentRef": {
-    "type": "patch",
-    "patchId": "22222222-2222-4222-8222-222222222222"
-  },
+  "patchId": "22222222-2222-4222-8222-222222222222",
   "path": "/content/projects.val.ts",
-  "authorId": "author-a",
+  "authorId": "author-b",
   "sessionId": null,
   "baseSha": "0000000000000000000000000000000000000000000000000000000000000000",
   "coreVersion": null,
-  "createdAt": "2026-08-11T09:00:05.000Z"
+  "createdAt": "2026-08-11T09:00:00.000Z"
 }

package/src/__fixtures__/debug-snapshot/.val/patches/33333333-3333-4333-8333-333333333333/patch.json

@@ -0,0 +1,16 @@
+{
+  "patch": [
+    {
+      "op": "replace",
+      "path": ["BBL", "summary", "services", "2"],
+      "value": "Development U"
+    }
+  ],
+  "patchId": "33333333-3333-4333-8333-333333333333",
+  "path": "/content/projects.val.ts",
+  "authorId": "author-a",
+  "sessionId": null,
+  "baseSha": "0000000000000000000000000000000000000000000000000000000000000000",
+  "coreVersion": null,
+  "createdAt": "2026-08-11T09:00:05.000Z"
+}

package/src/__fixtures__/debug-snapshot/.val/patches/patches.log

@@ -0,0 +1,4 @@
+val-patch-log v1
+11111111-1111-4111-8111-111111111111 2026-08-10T12:00:00.000Z /content/projects.val.ts
+22222222-2222-4222-8222-222222222222 2026-08-11T09:00:00.000Z /content/projects.val.ts
+33333333-3333-4333-8333-333333333333 2026-08-11T09:00:05.000Z /content/projects.val.ts

package/src/debug/snapshot.ts

@@ -22,8 +22,6 @@ export type SnapshotPatch = {
   authorId: string | null;
   baseSha: string;
   appliedAt: { commitSha: string } | null;
-  /** Parent in the chain: null means it is the first ("head"). */
-  parentPatchId: PatchId | null;
   patch: unknown;
 };
 
@@ -199,9 +197,21 @@ export async function buildSnapshot(
     for (const p of elided.elided) {
       elidedPatchValues.push({ patchId: patch.patchId, path: p });
     }
-    entries[`.val/patches/${patch.parentPatchId ?? "head"}/patch.json`] =
-      JSON.stringify(toFsPatch(patch), null, 2);
+    entries[`.val/patches/${patch.patchId}/patch.json`] = JSON.stringify(
+      toFsPatch(patch),
+      null,
+      2,
+    );
   }
+  // The order lives in the log, not in the records, so it has to be written too
+  // or the unzipped snapshot is a store with no order at all.
+  entries[".val/patches/patches.log"] = [
+    "val-patch-log v1",
+    ...patches.map(
+      (patch) => `${patch.patchId} ${patch.createdAt} ${patch.path}`,
+    ),
+    "",
+  ].join("\n");
 
   let includesBinaryFiles = false;
   if (options.includeFiles) {
@@ -296,31 +306,29 @@ function toSnapshotPatches(
     appliedAt: { commitSha: string } | null;
   }[],
 ): SnapshotPatch[] {
-  return orderedPatches.map((patch, i) => ({
+  return orderedPatches.map((patch) => ({
     patchId: patch.patchId,
     path: patch.path,
     createdAt: patch.createdAt,
     authorId: patch.authorId,
     baseSha: patch.baseSha,
     appliedAt: patch.appliedAt,
-    parentPatchId: i === 0 ? null : orderedPatches[i - 1].patchId,
     patch: patch.patch,
   }));
 }
 
 /**
  * The shape ValOpsFS writes per patch, so an unzipped snapshot is a patch store
- * a plain ValOpsFS can read. The directory is named after the PARENT, and
- * createPatchChain walks the linked list from "head".
+ * a plain ValOpsFS can read.
+ *
+ * The directory is named after the patch itself and the record points at
+ * nothing: the order is in `patches.log` beside it. A record that named its
+ * parent is how a snapshot could carry a chain that had already lost a link.
  */
 function toFsPatch(patch: SnapshotPatch) {
   return {
     patch: patch.patch,
     patchId: patch.patchId,
-    parentRef:
-      patch.parentPatchId === null
-        ? { type: "head", headBaseSha: patch.baseSha }
-        : { type: "patch", patchId: patch.parentPatchId },
     path: patch.path,
     authorId: patch.authorId,
     sessionId: null,
@@ -339,16 +347,13 @@ async function writeBinaryFiles(
   patches: SnapshotPatch[],
   entries: Record<string, string>,
 ): Promise<boolean> {
-  const parentByPatchId = new Map(
-    patches.map((p) => [p.patchId, p.parentPatchId ?? "head"]),
-  );
+  const known = new Set(patches.map((p) => p.patchId));
   let wrote = false;
   for (const [filePath, data] of Object.entries(fileLastUpdatedByPatchId)) {
     if (data.isDelete) {
       continue;
     }
-    const parentPatchId = parentByPatchId.get(data.patchId);
-    if (parentPatchId === undefined) {
+    if (!known.has(data.patchId)) {
       continue;
     }
     const buffer = await ctx.serverOps.getBase64EncodedBinaryFileFromPatch(
@@ -361,7 +366,7 @@ async function writeBinaryFiles(
     }
     // Base64 so the snapshot stays a text-only entry map; the replay decodes it.
     entries[
-      `.val/patches/${parentPatchId}/files${filePath}/${path.posix.basename(filePath)}.base64`
+      `.val/patches/${data.patchId}/files${filePath}/${path.posix.basename(filePath)}.base64`
     ] = buffer.toString("base64");
     wrote = true;
   }

package/src/debug.test.ts

@@ -1,5 +1,8 @@
+import fs from "fs";
+import os from "os";
 import path from "path";
 import { ModuleFilePath } from "@valbuild/core";
+import { readPatchStore } from "@valbuild/server";
 import { createDebugContext } from "./debug/context";
 import { buildSnapshot } from "./debug/snapshot";
 
@@ -71,25 +74,43 @@ describe("val debug snapshot", () => {
     expect(entries["val.modules.original.ts"]).toContain("unrelated");
   });
 
-  test("writes the patch chain in the layout ValOpsFS reads back", async () => {
+  test("writes a patch store ValOpsFS can actually read back", async () => {
     const { entries } = await build();
 
-    // The directory is named after the PARENT patch; the first is "head".
-    const head = JSON.parse(entries[".val/patches/head/patch.json"]);
-    expect(head.patchId).toBe("11111111-1111-4111-8111-111111111111");
-    expect(head.parentRef.type).toBe("head");
-    // A head ref without headBaseSha does not parse, so the snapshot would be
-    // unreadable.
-    expect(typeof head.parentRef.headBaseSha).toBe("string");
-
-    const second = JSON.parse(
-      entries[".val/patches/11111111-1111-4111-8111-111111111111/patch.json"],
-    );
-    expect(second.patchId).toBe("22222222-2222-4222-8222-222222222222");
-    expect(second.parentRef).toEqual({
-      type: "patch",
-      patchId: "11111111-1111-4111-8111-111111111111",
-    });
+    // Materialise it and read it with the real store, rather than asserting on
+    // path strings: "the layout ValOpsFS reads back" is the property, and a
+    // snapshot that merely looks right is exactly what a debug tool must not
+    // produce.
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "val-snapshot-"));
+    for (const [name, content] of Object.entries(entries)) {
+      const file = path.join(dir, name);
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, content);
+    }
+
+    const read = readPatchStore(path.join(dir, ".val", "patches"));
+    if (read.status !== "ok") {
+      throw new Error(`expected ok, got ${read.status}`);
+    }
+    expect(read.problems).toEqual([]);
+    expect(read.entries.map((entry) => entry.patchId)).toEqual([
+      "11111111-1111-4111-8111-111111111111",
+      "22222222-2222-4222-8222-222222222222",
+      "33333333-3333-4333-8333-333333333333",
+    ]);
+
+    // Each record sits under its own id and points at nothing. A record that
+    // named its parent is how a snapshot could carry a chain that had already
+    // lost a link.
+    for (const entry of read.entries) {
+      const raw = JSON.parse(
+        entries[`.val/patches/${entry.patchId}/patch.json`],
+      );
+      expect(raw.patchId).toBe(entry.patchId);
+      expect(raw).not.toHaveProperty("parentRef");
+    }
+
+    fs.rmSync(dir, { recursive: true, force: true });
   });
 
   test("records why the snapshot may be incomplete rather than failing silently", async () => {

package/src/__fixtures__/debug-snapshot/.val/patches/head/patch.json

@@ -1,20 +0,0 @@
-{
-  "patch": [
-    {
-      "op": "replace",
-      "path": ["BBL", "title"],
-      "value": "BBL Housing"
-    }
-  ],
-  "patchId": "11111111-1111-4111-8111-111111111111",
-  "parentRef": {
-    "type": "head",
-    "headBaseSha": "0000000000000000000000000000000000000000000000000000000000000000"
-  },
-  "path": "/content/projects.val.ts",
-  "authorId": "author-a",
-  "sessionId": null,
-  "baseSha": "0000000000000000000000000000000000000000000000000000000000000000",
-  "coreVersion": null,
-  "createdAt": "2026-08-10T12:00:00.000Z"
-}