@decocms/blocks 8.6.0 → 8.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (168) hide show
  1. package/dist/index.d.ts +1 -1
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js +1 -1
  4. package/dist/index.js.map +1 -1
  5. package/dist/protocol/conformance/cases/changes.d.ts.map +1 -1
  6. package/dist/protocol/conformance/cases/changes.js +14 -3
  7. package/dist/protocol/conformance/cases/changes.js.map +1 -1
  8. package/dist/protocol/conformance/cases/guards.d.ts.map +1 -1
  9. package/dist/protocol/conformance/cases/guards.js +19 -42
  10. package/dist/protocol/conformance/cases/guards.js.map +1 -1
  11. package/dist/protocol/conformance/cases/overlay.d.ts +3 -0
  12. package/dist/protocol/conformance/cases/overlay.d.ts.map +1 -0
  13. package/dist/protocol/conformance/cases/overlay.js +164 -0
  14. package/dist/protocol/conformance/cases/overlay.js.map +1 -0
  15. package/dist/protocol/conformance/cases/reads.js +5 -5
  16. package/dist/protocol/conformance/cases/reads.js.map +1 -1
  17. package/dist/protocol/conformance/cases/writes.d.ts.map +1 -1
  18. package/dist/protocol/conformance/cases/writes.js +15 -3
  19. package/dist/protocol/conformance/cases/writes.js.map +1 -1
  20. package/dist/protocol/conformance/context.d.ts +0 -10
  21. package/dist/protocol/conformance/context.d.ts.map +1 -1
  22. package/dist/protocol/conformance/context.js.map +1 -1
  23. package/dist/protocol/conformance/index.d.ts.map +1 -1
  24. package/dist/protocol/conformance/index.js +2 -0
  25. package/dist/protocol/conformance/index.js.map +1 -1
  26. package/dist/protocol/server/content.d.ts +8 -1
  27. package/dist/protocol/server/content.d.ts.map +1 -1
  28. package/dist/protocol/server/content.js +18 -3
  29. package/dist/protocol/server/content.js.map +1 -1
  30. package/dist/protocol/server/core.d.ts +0 -6
  31. package/dist/protocol/server/core.d.ts.map +1 -1
  32. package/dist/protocol/server/core.js +0 -2
  33. package/dist/protocol/server/core.js.map +1 -1
  34. package/dist/protocol/server/methods/apply.d.ts +16 -5
  35. package/dist/protocol/server/methods/apply.d.ts.map +1 -1
  36. package/dist/protocol/server/methods/apply.js +42 -38
  37. package/dist/protocol/server/methods/apply.js.map +1 -1
  38. package/dist/protocol/server/methods/changes.d.ts.map +1 -1
  39. package/dist/protocol/server/methods/changes.js +31 -3
  40. package/dist/protocol/server/methods/changes.js.map +1 -1
  41. package/dist/protocol/server/methods/read.d.ts.map +1 -1
  42. package/dist/protocol/server/methods/read.js +2 -23
  43. package/dist/protocol/server/methods/read.js.map +1 -1
  44. package/dist/protocol/storage/fs/index.d.ts.map +1 -1
  45. package/dist/protocol/storage/fs/index.js +0 -18
  46. package/dist/protocol/storage/fs/index.js.map +1 -1
  47. package/dist/protocol/storage/memory.d.ts +11 -3
  48. package/dist/protocol/storage/memory.d.ts.map +1 -1
  49. package/dist/protocol/storage/memory.js +114 -45
  50. package/dist/protocol/storage/memory.js.map +1 -1
  51. package/dist/protocol/storage.d.ts +68 -18
  52. package/dist/protocol/storage.d.ts.map +1 -1
  53. package/dist/protocol/storage.js +7 -0
  54. package/dist/protocol/storage.js.map +1 -1
  55. package/dist/protocol/types.d.ts +51 -8
  56. package/dist/protocol/types.d.ts.map +1 -1
  57. package/dist/protocol/types.js +5 -3
  58. package/dist/protocol/types.js.map +1 -1
  59. package/dist/v8/builtins/index.d.ts +1 -4
  60. package/dist/v8/builtins/index.d.ts.map +1 -1
  61. package/dist/v8/builtins/index.js +1 -6
  62. package/dist/v8/builtins/index.js.map +1 -1
  63. package/dist/v8/builtins/legacy.d.ts +4 -4
  64. package/dist/v8/builtins/legacy.d.ts.map +1 -1
  65. package/dist/v8/builtins/legacy.js +4 -5
  66. package/dist/v8/builtins/legacy.js.map +1 -1
  67. package/dist/v8/cli/builtins.d.ts.map +1 -1
  68. package/dist/v8/cli/builtins.js +0 -1
  69. package/dist/v8/cli/builtins.js.map +1 -1
  70. package/dist/v8/cli/check/index.d.ts +1 -1
  71. package/dist/v8/cli/check/index.d.ts.map +1 -1
  72. package/dist/v8/cli/check/index.js +13 -33
  73. package/dist/v8/cli/check/index.js.map +1 -1
  74. package/dist/v8/cli/schema/builtinSchemas.d.ts.map +1 -1
  75. package/dist/v8/cli/schema/builtinSchemas.js +0 -8
  76. package/dist/v8/cli/schema/builtinSchemas.js.map +1 -1
  77. package/dist/v8/cli/schema/generate.d.ts.map +1 -1
  78. package/dist/v8/cli/schema/generate.js +1 -8
  79. package/dist/v8/cli/schema/generate.js.map +1 -1
  80. package/dist/v8/cli/schema/typeToSchema.d.ts +0 -1
  81. package/dist/v8/cli/schema/typeToSchema.d.ts.map +1 -1
  82. package/dist/v8/cli/schema/typeToSchema.js +5 -30
  83. package/dist/v8/cli/schema/typeToSchema.js.map +1 -1
  84. package/dist/v8/client.d.ts +1 -1
  85. package/dist/v8/client.d.ts.map +1 -1
  86. package/dist/v8/cms.d.ts.map +1 -1
  87. package/dist/v8/cms.js +31 -21
  88. package/dist/v8/cms.js.map +1 -1
  89. package/dist/v8/content.d.ts +35 -1
  90. package/dist/v8/content.d.ts.map +1 -1
  91. package/dist/v8/content.js +81 -2
  92. package/dist/v8/content.js.map +1 -1
  93. package/dist/v8/index.d.ts +1 -1
  94. package/dist/v8/index.d.ts.map +1 -1
  95. package/dist/v8/preview/DraftBadge.d.ts +9 -1
  96. package/dist/v8/preview/DraftBadge.d.ts.map +1 -1
  97. package/dist/v8/preview/DraftBadge.js +42 -2
  98. package/dist/v8/preview/DraftBadge.js.map +1 -1
  99. package/dist/v8/remoteLoader.d.ts.map +1 -1
  100. package/dist/v8/remoteLoader.js +3 -1
  101. package/dist/v8/remoteLoader.js.map +1 -1
  102. package/dist/v8/resolver.d.ts +1 -1
  103. package/dist/v8/resolver.d.ts.map +1 -1
  104. package/dist/v8/telemetry.d.ts +0 -2
  105. package/dist/v8/telemetry.d.ts.map +1 -1
  106. package/dist/v8/telemetry.js +5 -20
  107. package/dist/v8/telemetry.js.map +1 -1
  108. package/dist/v8/types.d.ts +37 -10
  109. package/dist/v8/types.d.ts.map +1 -1
  110. package/package.json +1 -6
  111. package/src/index.ts +1 -2
  112. package/src/protocol/conformance/cases/changes.ts +16 -4
  113. package/src/protocol/conformance/cases/guards.ts +19 -55
  114. package/src/protocol/conformance/cases/overlay.ts +195 -0
  115. package/src/protocol/conformance/cases/reads.ts +4 -4
  116. package/src/protocol/conformance/cases/writes.ts +15 -3
  117. package/src/protocol/conformance/context.ts +0 -7
  118. package/src/protocol/conformance/index.ts +2 -0
  119. package/src/protocol/server/content.ts +30 -4
  120. package/src/protocol/server/core.ts +0 -3
  121. package/src/protocol/server/methods/apply.ts +43 -38
  122. package/src/protocol/server/methods/changes.ts +42 -4
  123. package/src/protocol/server/methods/read.ts +2 -24
  124. package/src/protocol/storage/fs/index.ts +0 -18
  125. package/src/protocol/storage/memory.ts +124 -46
  126. package/src/protocol/storage.ts +69 -18
  127. package/src/protocol/types.ts +51 -8
  128. package/src/v8/builtins/index.ts +1 -6
  129. package/src/v8/builtins/legacy.ts +4 -5
  130. package/src/v8/cli/builtins.ts +0 -1
  131. package/src/v8/cli/check/index.ts +15 -34
  132. package/src/v8/cli/schema/builtinSchemas.ts +0 -8
  133. package/src/v8/cli/schema/generate.ts +1 -8
  134. package/src/v8/cli/schema/typeToSchema.ts +5 -31
  135. package/src/v8/client.ts +1 -1
  136. package/src/v8/cms.ts +37 -22
  137. package/src/v8/content.ts +82 -2
  138. package/src/v8/index.ts +0 -1
  139. package/src/v8/preview/DraftBadge.tsx +72 -2
  140. package/src/v8/remoteLoader.ts +3 -1
  141. package/src/v8/resolver.ts +1 -1
  142. package/src/v8/telemetry.ts +5 -20
  143. package/src/v8/types.ts +36 -7
  144. package/dist/protocol/ciphertext.d.ts +0 -7
  145. package/dist/protocol/ciphertext.d.ts.map +0 -1
  146. package/dist/protocol/ciphertext.js +0 -7
  147. package/dist/protocol/ciphertext.js.map +0 -1
  148. package/dist/protocol/secrets.d.ts +0 -22
  149. package/dist/protocol/secrets.d.ts.map +0 -1
  150. package/dist/protocol/secrets.js +0 -207
  151. package/dist/protocol/secrets.js.map +0 -1
  152. package/dist/v8/builtins/secret.d.ts +0 -7
  153. package/dist/v8/builtins/secret.d.ts.map +0 -1
  154. package/dist/v8/builtins/secret.js +0 -68
  155. package/dist/v8/builtins/secret.js.map +0 -1
  156. package/dist/v8/ciphertext.d.ts +0 -58
  157. package/dist/v8/ciphertext.d.ts.map +0 -1
  158. package/dist/v8/ciphertext.js +0 -134
  159. package/dist/v8/ciphertext.js.map +0 -1
  160. package/dist/v8/secrets.d.ts +0 -9
  161. package/dist/v8/secrets.d.ts.map +0 -1
  162. package/dist/v8/secrets.js +0 -14
  163. package/dist/v8/secrets.js.map +0 -1
  164. package/src/protocol/ciphertext.ts +0 -6
  165. package/src/protocol/secrets.ts +0 -239
  166. package/src/v8/builtins/secret.ts +0 -82
  167. package/src/v8/ciphertext.ts +0 -158
  168. package/src/v8/secrets.ts +0 -17
@@ -27,6 +27,7 @@ import {
27
27
  limitExceeded,
28
28
  readOnly,
29
29
  unavailable,
30
+ type VersionMismatch,
30
31
  } from "../../errors.ts";
31
32
  import {
32
33
  blockFileName,
@@ -60,7 +61,7 @@ import type {
60
61
  import { type ParsedBody, parseBody } from "../bodyCache.ts";
61
62
  import { type LoadedContent, loadCurrentContent } from "../content.ts";
62
63
  import { type Core, MAX_BLOCK_BYTES, MAX_NAMES_PER_GET, MAX_OPS_PER_APPLY } from "../core.ts";
63
- import { checkIfMatch, type EntriesBySpelling, entriesBySpelling } from "./apply.ts";
64
+ import { type EntriesBySpelling, entriesBySpelling } from "./apply.ts";
64
65
 
65
66
  const keyOf = (file: string) => fullyDecodeFileName(file).name;
66
67
 
@@ -71,7 +72,10 @@ const byFile = (a: { file: string }, b: { file: string }) =>
71
72
  interface EntryChange {
72
73
  name: string;
73
74
  kind: "set" | "delete";
74
- /** The current winner's version; `null` when no file of the entry exists now. */
75
+ /**
76
+ * The current winner's version; for an entry no file of which exists now,
77
+ * an overlay's tombstone version, else `null`.
78
+ */
75
79
  version: string | null;
76
80
  baseVersion: string | null;
77
81
  /** The current winning file, when it was readable as a candidate. */
@@ -165,6 +169,9 @@ async function storageChanges(
165
169
  const answer = await core.storage.changes(base, snapshot);
166
170
  const changes: StorageChanges = {
167
171
  files: [...new Set(answer.files.filter(isBlockFileName))].sort(),
172
+ ...(answer.tombstones
173
+ ? { tombstones: answer.tombstones.filter((f) => isBlockFileName(f.file)) }
174
+ : {}),
168
175
  baseFiles: answer.baseFiles.filter((f) => isBlockFileName(f.file)),
169
176
  };
170
177
  core.changesMemo = { revision, changes };
@@ -197,6 +204,12 @@ async function loadChanges(core: Core): Promise<ChangesState> {
197
204
  else baseByKey.set(key, [file]);
198
205
  }
199
206
 
207
+ // An overlay's deletion is versioned by its first tombstone, as `blocks.apply`'s guard sees it.
208
+ const tombstoneByKey = new Map<string, string>();
209
+ for (const t of [...(answer.tombstones ?? [])].sort(byFile)) {
210
+ if (!tombstoneByKey.has(keyOf(t.file))) tombstoneByKey.set(keyOf(t.file), t.version);
211
+ }
212
+
200
213
  const bySpelling = entriesBySpelling(content!);
201
214
  const changes = new Map<string, EntryChange>();
202
215
  for (const [key, changedFiles] of changedByKey) {
@@ -210,7 +223,9 @@ async function loadChanges(core: Core): Promise<ChangesState> {
210
223
  current?.name ??
211
224
  (winner ? blockNameFromFile(winner.file) : blockNameFromFile(changedFiles[0]!)),
212
225
  kind: exists ? "set" : "delete",
213
- version: current?.entry.version ?? (exists ? currentFiles[0]!.version : null),
226
+ version:
227
+ current?.entry.version ??
228
+ (exists ? currentFiles[0]!.version : (tombstoneByKey.get(key) ?? null)),
214
229
  baseVersion: winner?.version ?? null,
215
230
  currentFile: current?.entry.file ?? null,
216
231
  baseFile: winner?.file ?? null,
@@ -403,6 +418,29 @@ function guardExpectations(
403
418
  return expected;
404
419
  }
405
420
 
421
+ /**
422
+ * `changes.discard`'s guard: each name's version as `changes.list` shows it,
423
+ * so an overlay's deletion is guarded by its tombstone version (no file of
424
+ * it exists, so the content alone would say `null`).
425
+ */
426
+ function discardMismatches(
427
+ state: ChangesState,
428
+ ifMatch: Array<[string, string | null]>,
429
+ ): Record<string, VersionMismatch> | null {
430
+ const mismatches: Record<string, VersionMismatch> = {};
431
+ let failed = false;
432
+ for (const [name, expected] of ifMatch) {
433
+ const key = spellingKey(name);
434
+ const actual =
435
+ state.bySpelling.get(key)?.entry.version ?? state.changes.get(key)?.version ?? null;
436
+ if (actual !== expected) {
437
+ mismatches[name] = { expected, actual };
438
+ failed = true;
439
+ }
440
+ }
441
+ return failed ? mismatches : null;
442
+ }
443
+
406
444
  export async function changesDiscard(
407
445
  core: Core,
408
446
  params: ChangesDiscardParams,
@@ -420,7 +458,7 @@ export async function changesDiscard(
420
458
 
421
459
  for (let attempt = 1; attempt <= core.maxCommitAttempts; attempt++) {
422
460
  const state = await loadChanges(core);
423
- const mismatches = checkIfMatch(state.bySpelling, { ifMatch });
461
+ const mismatches = discardMismatches(state, ifMatch);
424
462
  if (mismatches) throw conflict({ entries: mismatches });
425
463
 
426
464
  const restore = new Map<string, StorageFile>();
@@ -1,7 +1,6 @@
1
1
  /**
2
2
  * The three read methods: `describe`, `schema.get` and `blocks.list`.
3
3
  */
4
- import { publicKeyDerFromPem } from "../../ciphertext.ts";
5
4
  import { unavailable } from "../../errors.ts";
6
5
  import {
7
6
  ASSETS_URL_PREFIX,
@@ -19,30 +18,8 @@ import type { Core } from "../core.ts";
19
18
 
20
19
  const DEFAULT_SERVER = { name: "deco-blocks", version: "unknown" };
21
20
 
22
- /** The largest `.deco/secrets.pub` served (a 16384-bit key's PEM is under 3 KiB). */
23
- const MAX_PUBLIC_KEY_BYTES = 16 * 1024;
24
-
25
- /**
26
- * The public key `describe` may serve: a single `PUBLIC KEY` PEM block of at
27
- * most 16 KiB. Anything else (a private key committed by mistake, two
28
- * blocks, stray text) is never broadcast to the site editor.
29
- */
30
- function servablePublicKey(text: string | null): string | null {
31
- if (text === null) return null;
32
- if (new TextEncoder().encode(text).byteLength > MAX_PUBLIC_KEY_BYTES) return null;
33
- if (text.includes("PRIVATE KEY")) return null;
34
- return publicKeyDerFromPem(text) === null ? null : text;
35
- }
36
-
37
21
  export async function describe(core: Core): Promise<DescribeResult> {
38
22
  const description = await core.description();
39
- const stored = await core.storage.readSecretsPublicKey();
40
- const publicKey = servablePublicKey(stored);
41
- if (stored !== null && publicKey === null) {
42
- core.options.onError?.(
43
- new Error(".deco/secrets.pub isn't a single PUBLIC KEY PEM block; describe reports no key"),
44
- );
45
- }
46
23
  const readOnly = description.readOnly;
47
24
  return {
48
25
  protocol: PROTOCOL_NAME,
@@ -62,7 +39,8 @@ export async function describe(core: Core): Promise<DescribeResult> {
62
39
  urlPrefix: ASSETS_URL_PREFIX,
63
40
  maxBytes: description.assets.maxBytes,
64
41
  },
65
- secrets: publicKey === null ? null : { publicKey },
42
+ secrets: null,
43
+ ...(typeof core.storage.writeSnapshot === "function" ? { overlay: true as const } : {}),
66
44
  };
67
45
  }
68
46
 
@@ -5,7 +5,6 @@
5
5
  * Inside the app root (the folder that contains `.deco/`):
6
6
  * - `.deco/blocks/*.json` — the saved blocks; the only thing it writes.
7
7
  * - `.deco/schema.gen.json`, falling back to `.deco/meta.gen.json` — read only.
8
- * - `.deco/secrets.pub` — read only, reported by `describe`.
9
8
  * - `.deco/index.ts` is code and is never written.
10
9
  * - Uploads go to `public/assets` (or `assetsDir`), never overwriting a file.
11
10
  *
@@ -106,15 +105,6 @@ async function findRepoRoot(start: string): Promise<string> {
106
105
  }
107
106
  }
108
107
 
109
- async function readTextOrNull(path: string): Promise<string | null> {
110
- try {
111
- return await readFile(path, "utf8");
112
- } catch (error) {
113
- if (isMissing(error)) return null;
114
- throw error;
115
- }
116
- }
117
-
118
108
  async function readBytesOrNull(path: string): Promise<Uint8Array | null> {
119
109
  try {
120
110
  return await readFile(path);
@@ -274,8 +264,6 @@ export function createFsStorage(options: FsStorageOptions): FsStorage {
274
264
 
275
265
  readSchema,
276
266
 
277
- readSecretsPublicKey: () => readTextOrNull(join(decoDir, "secrets.pub")),
278
-
279
267
  async commit(attempt): Promise<CommitResult> {
280
268
  if (readOnly) throw new StorageUnavailableError("the storage is read-only");
281
269
  for (const file of [
@@ -299,12 +287,6 @@ export function createFsStorage(options: FsStorageOptions): FsStorage {
299
287
  ) {
300
288
  return { status: "stale" } as const;
301
289
  }
302
- if (attempt.expectedSchemaVersion !== undefined) {
303
- const schema = await readSchema();
304
- if ((schema?.version ?? null) !== attempt.expectedSchemaVersion) {
305
- return { status: "stale" } as const;
306
- }
307
- }
308
290
  for (const [file, expected] of Object.entries(attempt.expected)) {
309
291
  if ((await freshVersion(file)) !== expected) return { status: "stale" } as const;
310
292
  }
@@ -13,22 +13,23 @@ import {
13
13
  type CommitResult,
14
14
  type ContentStorage,
15
15
  type StorageDescription,
16
+ type StorageFile,
16
17
  StorageInvalidFileError,
17
18
  StorageNotFoundError,
18
19
  type StorageSnapshot,
19
20
  type StoredFileBody,
20
21
  type StoredSchema,
22
+ TOMBSTONE_VERSION,
21
23
  } from "../storage.ts";
22
24
 
23
25
  /** Everything a memory storage holds; JSON-serializable, so it survives a "restart". */
24
26
  export interface MemoryStorageState {
25
- /** Saved-block files, by file name, with their content. */
27
+ /** Saved-block files, by file name, with their content (an overlay's own files, for an overlay). */
26
28
  files: Record<string, string>;
27
29
  /** The content of `schema.gen.json`, or `null` without one. */
28
30
  schema: string | null;
29
31
  /** The content of `meta.gen.json`, the fallback schema, or `null`. */
30
32
  legacySchema?: string | null;
31
- secretsPublicKey: string | null;
32
33
  assets: Record<string, string>;
33
34
  /** `false` simulates an app root with no `.deco` folder at all. */
34
35
  hasDecoFolder: boolean;
@@ -38,6 +39,15 @@ export interface MemoryStorageState {
38
39
  baseRevision: string;
39
40
  /** The base's branch. Default `null`. */
40
41
  baseRef: string | null;
42
+ /**
43
+ * An overlay storage (`writeSnapshot()`, `describe.overlay`), like a hosted
44
+ * draft: `files` is then the overlay alone, laid over `base`, and
45
+ * `deleted` the base files it deletes (its tombstones, which
46
+ * `writeSnapshot()` lists at `TOMBSTONE_VERSION`). Default `false`.
47
+ */
48
+ overlay: boolean;
49
+ /** For an overlay: base files the overlay deletes. */
50
+ deleted: string[];
41
51
  }
42
52
 
43
53
  export interface MemoryStorageOptions {
@@ -59,7 +69,7 @@ export interface MemoryStorage extends ContentStorage {
59
69
  setSchema(schema: string | object | null): void;
60
70
  /** Replaces the base's files, as a publish (or an outside commit) would. */
61
71
  setBase(files: Record<string, string>): void;
62
- /** Makes the current files the base, as a commit of every change would. */
72
+ /** Makes the current content the base (emptying an overlay), as a commit of every change would. */
63
73
  commitBase(): void;
64
74
  /** How many commits landed. */
65
75
  readonly commits: number;
@@ -72,12 +82,13 @@ export function createMemoryStorage(options: MemoryStorageOptions = {}): MemoryS
72
82
  files: {},
73
83
  schema: null,
74
84
  legacySchema: null,
75
- secretsPublicKey: null,
76
85
  assets: {},
77
86
  hasDecoFolder: true,
78
87
  base: {},
79
88
  baseRevision: "base-0",
80
89
  baseRef: null,
90
+ overlay: false,
91
+ deleted: [],
81
92
  ...options.state,
82
93
  });
83
94
  // structuredClone keeps shared references: the base is never the files object.
@@ -91,18 +102,83 @@ export function createMemoryStorage(options: MemoryStorageOptions = {}): MemoryS
91
102
  };
92
103
  let commits = 0;
93
104
 
94
- async function currentVersions(): Promise<Map<string, string>> {
105
+ /** The content `snapshot()` lists: the files, or for an overlay its files laid over the base. */
106
+ function content(): Record<string, string> {
107
+ if (!state.overlay) return state.files;
108
+ const out: Record<string, string> = Object.create(null);
109
+ for (const [file, text] of Object.entries(state.base)) {
110
+ if (!state.deleted.includes(file)) out[file] = text;
111
+ }
112
+ return Object.assign(out, state.files);
113
+ }
114
+
115
+ async function versionsOf(files: Record<string, string>): Promise<Map<string, string>> {
95
116
  const entries = await Promise.all(
96
- Object.entries(state.files).map(
97
- async ([file, content]) => [file, await version(content)] as const,
98
- ),
117
+ Object.entries(files).map(async ([file, text]) => [file, await version(text)] as const),
99
118
  );
100
119
  return new Map(entries);
101
120
  }
102
121
 
103
- async function schemaVersion(): Promise<string | null> {
104
- const text = state.schema ?? state.legacySchema ?? null;
105
- return text === null ? null : version(text);
122
+ const currentVersions = () => versionsOf(content());
123
+
124
+ /**
125
+ * The revision `snapshot()` reports. An overlay's also moves with the
126
+ * overlay itself, even when the content it shows doesn't (an entry saved
127
+ * with the base's value), so `changes.*` never answers from a stale memo.
128
+ */
129
+ async function contentRevision(): Promise<string> {
130
+ const revision = await revisionOf(await currentVersions());
131
+ if (!state.overlay) return revision;
132
+ const own = await revisionOf(await versionsOf(state.files));
133
+ return sha256Hex(`${revision}\n${own}\n${[...state.deleted].sort().join("\n")}`);
134
+ }
135
+
136
+ async function snapshotOf(
137
+ files: Record<string, string>,
138
+ revision?: () => Promise<string>,
139
+ ): Promise<StorageSnapshot> {
140
+ if (!state.hasDecoFolder) throw new StorageNotFoundError("no .deco folder");
141
+ const versions = await versionsOf(files);
142
+ return {
143
+ revision: revision ? await revision() : await revisionOf(versions),
144
+ resolvedRef: null,
145
+ files: [...versions].map(([file, v]) => ({
146
+ file,
147
+ version: v,
148
+ size: new TextEncoder().encode(files[file]).byteLength,
149
+ })),
150
+ };
151
+ }
152
+
153
+ /** The overlay's tombstones: the base files it deletes. */
154
+ const tombstones = (): StorageFile[] =>
155
+ state.deleted
156
+ .filter((file) => file in state.base)
157
+ .map((file) => ({ file, version: TOMBSTONE_VERSION, deleted: true }));
158
+
159
+ /** The overlay alone, as `writeSnapshot()` lists it: its files and its tombstones. */
160
+ async function overlaySnapshot(): Promise<StorageSnapshot> {
161
+ const own = await snapshotOf(state.files);
162
+ return { ...own, revision: await contentRevision(), files: [...own.files, ...tombstones()] };
163
+ }
164
+
165
+ /**
166
+ * An overlay's commit: `apply` writes the overlay and records deletions
167
+ * (returning their tombstone versions); `discard` drops files from it.
168
+ */
169
+ function commitToOverlay(attempt: CommitAttempt): Record<string, string> {
170
+ const touched = [...Object.keys(attempt.put), ...attempt.delete];
171
+ state.deleted = state.deleted.filter((file) => !touched.includes(file));
172
+ for (const file of touched) delete state.files[file];
173
+ const recorded: Record<string, string> = {};
174
+ if (attempt.reason === "discard") return recorded;
175
+ for (const file of attempt.delete) {
176
+ if (!(file in state.base)) continue;
177
+ state.deleted.push(file);
178
+ recorded[file] = TOMBSTONE_VERSION;
179
+ }
180
+ for (const [file, text] of Object.entries(attempt.put)) state.files[file] = text;
181
+ return recorded;
106
182
  }
107
183
 
108
184
  async function revisionOf(versions: Map<string, string>): Promise<string> {
@@ -125,25 +201,23 @@ export function createMemoryStorage(options: MemoryStorageOptions = {}): MemoryS
125
201
  if (attempt.expectedBase !== undefined && attempt.expectedBase !== state.baseRevision) {
126
202
  return { status: "stale" };
127
203
  }
128
- if (
129
- attempt.expectedSchemaVersion !== undefined &&
130
- (await schemaVersion()) !== attempt.expectedSchemaVersion
131
- ) {
132
- return { status: "stale" };
133
- }
134
- const versions = await currentVersions();
204
+ // An overlay's apply is guarded against the overlay (its tombstones too);
205
+ // anything else against the content.
206
+ const overlayApply = state.overlay && attempt.reason !== "discard";
207
+ const versions = await versionsOf(overlayApply ? state.files : content());
208
+ if (overlayApply) for (const t of tombstones()) versions.set(t.file, t.version);
135
209
  for (const [file, expected] of Object.entries(attempt.expected)) {
136
210
  if ((versions.get(file) ?? null) !== expected) return { status: "stale" };
137
211
  }
138
212
  // Validate everything before mutating, so the commit is all or nothing.
139
213
  const written: Record<string, string> = {};
140
- for (const [file, content] of Object.entries(attempt.put))
141
- written[file] = await version(content);
142
- for (const file of attempt.delete) delete state.files[file];
143
- for (const [file, content] of Object.entries(attempt.put)) state.files[file] = content;
144
- for (const [file, v] of Object.entries(written)) versions.set(file, v);
145
- for (const file of attempt.delete) if (!(file in attempt.put)) versions.delete(file);
146
- const revision = await revisionOf(versions);
214
+ for (const [file, text] of Object.entries(attempt.put)) written[file] = await version(text);
215
+ if (state.overlay) Object.assign(written, commitToOverlay(attempt));
216
+ else {
217
+ for (const file of attempt.delete) delete state.files[file];
218
+ for (const [file, text] of Object.entries(attempt.put)) state.files[file] = text;
219
+ }
220
+ const revision = await contentRevision();
147
221
  commits++;
148
222
  return { status: "committed", revision, versions: written };
149
223
  }
@@ -155,25 +229,16 @@ export function createMemoryStorage(options: MemoryStorageOptions = {}): MemoryS
155
229
 
156
230
  describe: () => description,
157
231
 
158
- async snapshot(): Promise<StorageSnapshot> {
159
- if (!state.hasDecoFolder) throw new StorageNotFoundError("no .deco folder");
160
- const versions = await currentVersions();
161
- return {
162
- revision: await revisionOf(versions),
163
- resolvedRef: null,
164
- files: [...versions].map(([file, v]) => ({
165
- file,
166
- version: v,
167
- size: new TextEncoder().encode(state.files[file]).byteLength,
168
- })),
169
- };
170
- },
232
+ snapshot: () => snapshotOf(content(), contentRevision),
233
+
234
+ ...(state.overlay ? { writeSnapshot: overlaySnapshot } : {}),
171
235
 
172
236
  async readFiles(_snapshot, files) {
173
237
  const out: Record<string, StoredFileBody> = Object.create(null);
238
+ const current = content();
174
239
  for (const file of files) {
175
- if (!(file in state.files)) continue;
176
- const text = state.files[file];
240
+ if (!(file in current)) continue;
241
+ const text = current[file]!;
177
242
  out[file] = { text, version: await version(text) };
178
243
  await options.afterRead?.(file, storage);
179
244
  }
@@ -187,10 +252,6 @@ export function createMemoryStorage(options: MemoryStorageOptions = {}): MemoryS
187
252
  return { version: await version(text), text, resolvedRef: null };
188
253
  },
189
254
 
190
- async readSecretsPublicKey() {
191
- return state.secretsPublicKey;
192
- },
193
-
194
255
  async base() {
195
256
  return { revision: state.baseRevision, resolvedRef: state.baseRef };
196
257
  },
@@ -203,6 +264,15 @@ export function createMemoryStorage(options: MemoryStorageOptions = {}): MemoryS
203
264
  size: new TextEncoder().encode(content).byteLength,
204
265
  })),
205
266
  );
267
+ if (state.overlay) {
268
+ // The overlay's own files are the changes, even one equal to the base.
269
+ const deleted = tombstones();
270
+ return {
271
+ files: [...Object.keys(state.files), ...deleted.map((t) => t.file)],
272
+ tombstones: deleted,
273
+ baseFiles,
274
+ };
275
+ }
206
276
  const baseVersion = new Map(baseFiles.map((f) => [f.file, f.version]));
207
277
  const current = new Map(snapshot.files.map((f) => [f.file, f.version]));
208
278
  const files = new Set<string>();
@@ -239,7 +309,11 @@ export function createMemoryStorage(options: MemoryStorageOptions = {}): MemoryS
239
309
 
240
310
  setFile(file, content) {
241
311
  if (content === null) delete state.files[file];
242
- else state.files[file] = content;
312
+ else {
313
+ state.files[file] = content;
314
+ // An overlay's file replaces its tombstone.
315
+ state.deleted = state.deleted.filter((deleted) => deleted !== file);
316
+ }
243
317
  },
244
318
 
245
319
  setBase(files) {
@@ -248,7 +322,11 @@ export function createMemoryStorage(options: MemoryStorageOptions = {}): MemoryS
248
322
  },
249
323
 
250
324
  commitBase() {
251
- storage.setBase(state.files);
325
+ storage.setBase(content());
326
+ if (state.overlay) {
327
+ state.files = {};
328
+ state.deleted = [];
329
+ }
252
330
  },
253
331
 
254
332
  setSchema(schema) {
@@ -6,8 +6,7 @@
6
6
  * base (what `changes.*` compares the content with: the files that differ
7
7
  * from it, and reading base bodies).
8
8
  * The protocol core (`createContentHandler`) owns everything else: the
9
- * JSON-RPC layer, validation, the file-name rule, the secret guard, limits and
10
- * retries. Storages deal in *files* inside `<root>/.deco/blocks`; entry names
9
+ * JSON-RPC layer, validation, the file-name rule, limits and retries. Storages deal in *files* inside `<root>/.deco/blocks`; entry names
11
10
  * are the core's business.
12
11
  *
13
12
  * Browser-safe: types and small error classes only.
@@ -34,8 +33,22 @@ export interface StorageFile {
34
33
  version: string;
35
34
  /** The file's size in bytes, when the storage knows it without reading the body. */
36
35
  size?: number;
36
+ /**
37
+ * `true` for a tombstone: a deletion an overlay storage records over its
38
+ * base, listed only by `writeSnapshot()`. It has no body, and its
39
+ * `version` is the tombstone's (see `TOMBSTONE_VERSION`).
40
+ */
41
+ deleted?: true;
37
42
  }
38
43
 
44
+ /**
45
+ * The version an overlay storage reports for a deletion it records (a
46
+ * tombstone), in `writeSnapshot()`, `changes()` and a commit's result. Any
47
+ * value no file content has works; the reference storage uses this one, and
48
+ * a storage that shares clients with it should too.
49
+ */
50
+ export const TOMBSTONE_VERSION = "tombstone";
51
+
39
52
  /** Every saved-block file at one point in time. */
40
53
  export interface StorageSnapshot {
41
54
  /** An opaque revision of the whole set, compared only for equality. */
@@ -67,25 +80,32 @@ export interface StoredSchema {
67
80
 
68
81
  /** One atomic commit attempt. */
69
82
  export interface CommitAttempt {
70
- /** The snapshot the core validated against. */
83
+ /**
84
+ * The snapshot the core validated against: `writeSnapshot()`'s for an
85
+ * overlay storage (`blocks.apply`), `snapshot()`'s otherwise.
86
+ */
71
87
  base: StorageSnapshot;
72
88
  /** Files to write, by file name, with their full content. */
73
89
  put: Record<string, string>;
74
- /** Files to delete. A file that's already gone is fine. */
90
+ /**
91
+ * Files to delete. A file that's already gone is fine. For an overlay
92
+ * storage, `blocks.apply` also names files the overlay doesn't hold: the
93
+ * storage records the deletion over its base (a file only the base has
94
+ * must disappear from `snapshot()`, and `writeSnapshot()` lists it as a
95
+ * tombstone). One neither side has it may drop, or record as a tombstone
96
+ * too (a storage whose write never reads the base can't tell them apart);
97
+ * the core treats such a tombstone like any other.
98
+ */
75
99
  delete: string[];
76
100
  /**
77
101
  * Versions the files must still have for the commit to land (`null` = must
78
- * not exist). A storage MUST reject the attempt as stale when any of them
79
- * changed, and MAY reject it when anything else changed since `base`.
102
+ * not exist), in the snapshot `base` came from (the overlay, for an overlay
103
+ * storage's `blocks.apply`, where a tombstone has its tombstone version
104
+ * and so is not `null`). A storage MUST reject the attempt as stale
105
+ * when any of them changed, and MAY reject it when anything else changed
106
+ * since `base`.
80
107
  */
81
108
  expected: Record<string, string | null>;
82
- /**
83
- * The schema version the core validated against (`null` = no schema), when
84
- * the write depends on it (the secret guard checks `set` against it). When set,
85
- * a storage MUST reject the attempt as stale if the schema's version at
86
- * commit time differs, checked atomically with `expected`.
87
- */
88
- expectedSchemaVersion?: string | null;
89
109
  /**
90
110
  * The base revision (`StorageBase.revision`) the core computed the write
91
111
  * from, when the write depends on it (`changes.discard` restores base
@@ -96,7 +116,9 @@ export interface CommitAttempt {
96
116
  /**
97
117
  * Why the core commits: `apply` (default) or `discard`. For logs, and a
98
118
  * storage with a staging area (the fs storage's git index) also unstages
99
- * the files a `discard` writes or deletes, in the same commit.
119
+ * the files a `discard` writes or deletes, in the same commit. An overlay
120
+ * storage applies a `discard` by dropping those files from the overlay, so
121
+ * the base shows through (`put` holds the base's own bytes).
100
122
  */
101
123
  reason?: "apply" | "discard";
102
124
  }
@@ -116,9 +138,18 @@ export interface StorageChanges {
116
138
  * in the base, in the base and not in the snapshot, or in both with
117
139
  * different content. A file whose content equals the base's (the storage
118
140
  * decides equality, such as honouring git's eol conversion) MUST NOT be
119
- * listed, so a file a discard just restored is never listed again.
141
+ * listed, so a file a discard just restored is never listed again. An
142
+ * overlay storage instead lists exactly the files its overlay holds, and
143
+ * the deletions it records of files the base has, even a file equal to the
144
+ * base's: the overlay's own entries are the changes.
120
145
  */
121
146
  files: string[];
147
+ /**
148
+ * An overlay storage: the tombstones among `files` (the deletions it
149
+ * records), with the versions `writeSnapshot()` lists them with, which
150
+ * `changes.list` reports as the deletions' versions. Absent otherwise.
151
+ */
152
+ tombstones?: StorageFile[];
122
153
  /**
123
154
  * The base's files, with their versions in the base: at least every file
124
155
  * whose spelling group (`spellingKey`) a file in `files` belongs to; more
@@ -130,8 +161,13 @@ export interface StorageChanges {
130
161
  export type CommitResult =
131
162
  | {
132
163
  status: "committed";
164
+ /** The revision `snapshot()` reports right after the commit (`blocks.list`'s). */
133
165
  revision: string;
134
- /** The new version of every file in `put`. */
166
+ /**
167
+ * The new version of every file in `put`, and for an overlay storage
168
+ * the tombstone version of every file in `delete` it recorded as a
169
+ * tombstone (not one it dropped because neither side has it).
170
+ */
135
171
  versions: Record<string, string>;
136
172
  }
137
173
  | { status: "stale" };
@@ -152,8 +188,23 @@ export interface ContentStorage {
152
188
  readFiles(snapshot: StorageSnapshot, files: string[]): Promise<Record<string, StoredFileBody>>;
153
189
  /** Reads `schema.gen.json`, falling back to `meta.gen.json`; `null` when neither exists. */
154
190
  readSchema(): Promise<StoredSchema | null>;
155
- /** Reads `<root>/.deco/secrets.pub`; `null` without one. */
156
- readSecretsPublicKey(): Promise<string | null>;
191
+ /**
192
+ * An overlay storage's own files: what it holds over its base (a hosted
193
+ * draft's blocks over the published branch), read without reading the
194
+ * base. Its presence makes the endpoint an overlay (`describe.overlay`):
195
+ * `blocks.apply` validates and checks `ifMatch` against this snapshot
196
+ * instead of `snapshot()`, and commits with it as `base`; `readFiles`
197
+ * reads its files too. A deletion the overlay records is listed as a
198
+ * tombstone (`deleted: true`, with its tombstone version): for a guard the
199
+ * overlay holds it, so `ifMatch: null` on it fails and its tombstone
200
+ * version passes. The
201
+ * revision `snapshot()` reports must move whenever the overlay does, even
202
+ * when the content it shows doesn't (an entry saved with the base's
203
+ * value). Absent
204
+ * for a storage that writes its content directly (a working tree, a
205
+ * branch).
206
+ */
207
+ writeSnapshot?(): Promise<StorageSnapshot>;
157
208
  /** One all-or-nothing commit attempt; durable when it resolves. */
158
209
  commit(attempt: CommitAttempt): Promise<CommitResult>;
159
210
  /**