Skip to content

Commit 83b1744

Browse files
committed
docs: runtime migration, record the Deno KV changes plans 18-30 must absorb
Two cache changes landed or are landing ahead of the plans that assume they own that code. #15180 keeps Deno KV stores in a v8-<branch> directory and exports v8Branch from platform.ts, because Deno 2.9 writes V8 values Deno 2.7 cannot read. The #15119 fix creates src/deno_ral/kv.ts first, with damage classification that PR 18 has to keep. The plans stay unedited until their step 0, so the findings go in as "Open decisions with an owner" rows naming PRs 18, 19, 26, 27b and 30. The store-name convention and the platform.ts/kv.ts vocabulary state the per-V8-branch rule now, since every later plan reads them. docs: runtime migration, keep PR 18's list() change and move the KV damage tests to PR 30 Dropping PR 18 Task 2 Step 2 whole would also drop the list({ prefix: [] }) to list([]) change clear() needs once the index is a KeyValueStore, so the step now shrinks to that change and keeps the clear() body #15180 shipped. The PR 26 row asked for known-failures entries for the Deno KV damage tests, but its node-unit job runs only tests/unit/ral/ and rejects an entry for a file that did not run. Those tests first meet Node in PR 32's full suite, after PR 30 removes Deno KV, so PR 30 replaces or deletes them instead.
1 parent 3a689f2 commit 83b1744

2 files changed

Lines changed: 7 additions & 1 deletion

File tree

‎dev-docs/runtime-migration/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@ Change them in the plan that decides them, not downstream.
7373
--use-env-proxy --disable-warning=MODULE_TYPELESS_PACKAGE_JSON`.
7474
- Environment contract (PR 33/34): `QUARTO_NODE`, `QUARTO_NODE_OPTIONS`, `QUARTO_NODE_VERSION`; `NODE_OPTIONS`/`NODE_PATH` are saved into `QUARTO_SAVED_*` for Quarto's own process and restored for children; `QUARTO_DENO*` are ignored or translated with a one-time warning and `QUARTO_DENO` is never aliased to the Node binary; `QUARTO_RUN_RUNTIME=deno` or the project key `script-runtime` selects the Deno tool for `.ts` scripts (PR 35); `QUARTO_RUN_DENO_NOTICE=0` silences the notice (PR 00c, 35).
7575
- Store names: project cache `index`, Sass cache `sass-index`; the backend picks the file (`<name>.kv` for PR 18's `Deno.openKv` backend, which Quarto 1.11 ships; `<name>.json` for PR 30's JSON backend, the only one on both runtimes from PR 30 on) so Quarto versions on different backends never share a file (PRs 18, 30).
76+
Until PR 30, Deno KV stores also stay per V8 release branch, in a `v8-<v8Branch>` directory (`src/deno_ral/platform.ts`, #15180), because a Deno with a newer V8 writes values an older one cannot read.
7677
- `src/deno_ral/` keeps its name.
7778
`src/core/puppeteer.ts` keeps its name.
7879
- Ratchet exclusions for the `src` scope (`kSrcExclusions`, PR 02): `src/deno_ral/`, `src/vendor/`, `src/resources/extension-subtrees/`, `src/resources/scripts/`, `src/resources/create/`, `src/webui/quarto-preview/build.ts` (allow-listed until PR 33).
@@ -128,6 +129,10 @@ The rows below are the ones that still need a named person or an external answer
128129
| PRs 06 and 07 Decision 1 | the optional renames (`@cliffy/command` import style, `src/core/puppeteer.ts`) | coordinator | after PR 26 and after Phase 1 respectively; dropped if nobody asks |
129130
| PR 33 and PR 35 size | whether PR 33 lands as one PR or as 33a (Tasks 1, 11, 12, 16) + 33b (the flip), and PR 35 as one PR or 35a (Task 1 builder) + 35b (scripts) | maintainer | before Phase 3 starts |
130131
| User breakage after the flip | issue label, weekly triage owner during the soak, criterion to extend the dual-runtime window or the shim | release manager | before the first 1.12 prerelease |
132+
| PR 18, all tasks (from #15180) | the Deno backend keeps the `v8-<v8Branch>` store directory; reconcile it with the store names `index`/`sass-index` and the `<identifierHash>-<inputHash>.css` naming. Task 2 Step 2 shrinks to the API change: `this.index.list({ prefix: [] })` becomes `this.index.list([])`, and the `clear()` body #15180 shipped stays as is (`storeDir` paths, `safeRemoveSync`, immediate entries skipped; test `projectCache - clear() removes disk and immediate entries of a populated cache`). Drop the Context sentence saying `join` throws in `clear()`, and the Risks lines about that throwing path; one `cache.ts` `Deno.removeSync` is now `safeRemoveSync`. Refresh every Verified usage line number | coordinator | PR 18 step 0 |
133+
| PR 18 Tasks 1–3 (from the #15119 fix, once `src/deno_ral/kv.ts` is on `main`) | `kv.ts` already exists (`openKv`, `getKv`, `kvOp`, `KvDamagedError`) and both caches go through it, so Task 1 extends the file instead of creating it and its "Module not found" RED step no longer holds. `openKeyValueStore` keeps the damage mapping: a damaged value reads as a miss with one warning, a damaged file fails with `KvDamagedError` naming the folder to delete, any other error is wrapped with the path. The `src` baseline drops by 5, not 7 (the two `Deno.openKv` calls are already in the layer). The `Deno.openKv` grep acceptance check covers `src` and `package` only, since three cache tests build damaged fixtures with `Deno.openKv` on purpose. The `kv.ts` row in `.claude/rules/typescript/deno-ral.md` exists: update it | coordinator | PR 18 step 0 |
134+
| PR 19 Task 1, PR 27b | both replace the whole body of `platform.ts`: keep the `v8Branch` export (`_TEMPLATE.md`, "`platform.ts`"); PR 27b computes it from `process.versions.v8` | coordinator | step 0 of each |
135+
| PR 30 | tagged `v8-<branch>/` directories are left behind like the untagged `.kv` files; remove `v8Branch` and its contract-test line together with its last consumer. What "damaged" means for the JSON index (unparsable or truncated file): keep the miss-with-warning versus fail-naming-the-folder split or not. The Deno KV damage tests (`tests/unit/kv-damage.test.ts` and the damaged-store cases in `sass-cache.test.ts` and `project-cache.test.ts`, from the #15119 fix) build real SQLite damage: they are replaced or deleted here, because PR 32 runs the full unit suite on Node, where neither `Deno.openKv` nor its damage exists, and "`sass-cache.test.ts` stays green" is restated accordingly | maintainer (damage semantics), coordinator (the rest) | PR 30 step 0 |
131136

132137
## Shared rules and tables
133138

‎dev-docs/runtime-migration/_TEMPLATE.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -282,14 +282,15 @@ export interface KeyValueStore {
282282
list<T>(prefix: KvKey): AsyncIterable<KvEntry<T>>;
283283
close(): void;
284284
}
285-
export function openKeyValueStore(dir: string, name: string): Promise<KeyValueStore>; // the backend chooses the file: `<dir>/<name>.kv` for PR 18's Deno.openKv backend (Quarto <= 1.11), `<dir>/<name>.json` for PR 30's JSON backend, the only one on both runtimes from PR 30 on; Quarto versions on different backends never share a file. Writes take the owned lock directory `<name>.json.lock` (PR 30, Interfaces, "Lock ownership": owner marker, liveness probe, guarded release; PR 33's build lock copies the rule)
285+
export function openKeyValueStore(dir: string, name: string): Promise<KeyValueStore>; // the backend chooses the file: `<dir>/<name>.kv` for PR 18's Deno.openKv backend (Quarto <= 1.11), `<dir>/<name>.json` for PR 30's JSON backend, the only one on both runtimes from PR 30 on; Quarto versions on different backends never share a file. The Deno backend also keeps each store per V8 release branch (`v8-<v8Branch>` directory, `platform.ts`, #15180), since Deno KV files written by a newer V8 cannot be read by an older one; the JSON backend needs no tag. Writes take the owned lock directory `<name>.json.lock` (PR 30, Interfaces, "Lock ownership": owner marker, liveness probe, guarded release; PR 33's build lock copies the rule)
286286
// Contract (PR 18 tests): a second handle on the same store sees a committed `set`; two processes writing different keys both persist (Node: lock + read-modify-rename).
287287
```
288288

289289
### `platform.ts` (extended in PR 19)
290290

291291
```ts
292292
export const isWindows: boolean; export const isMac: boolean; export const isLinux: boolean; export const os: string; export const arch: string; // existing
293+
export const v8Branch: string; // existing (#15180): V8 release branch "<major>.<minor>"; Deno KV stores live under `v8-<v8Branch>/` because the V8 serializer format changes between branches. Every plan that rewrites platform.ts keeps it (PR 27b: from `process.versions.v8`); PR 30 removes it with its last consumer
293294
export function runtime(): { name: "deno" | "node" | "bun"; version: string }; // real detection from PR 19: Deno when `typeof Deno !== "undefined" && "version" in Deno`, Bun when `process.versions.bun`, else Node
294295
export function consoleColumns(): number | undefined;
295296
export function inspect(value: unknown, options?: { depth?: number; colors?: boolean }): string;

0 commit comments

Comments
 (0)