@volter/world-core 3.0.148 → 3.0.150

package/dist/src/changeset.js

@@ -57,7 +57,7 @@ import { worldPaths } from "./storage.js";
 // the control root that holds it) and never learns what a world is. `volter-world` supplies
 // discovery and the CLI verbs; the state-level logic lives here, beside the ledgers it reads.
 import { createHash } from 'node:crypto';
-import { aliasesFrom, readTreeMap, wholeLog } from "./log.js";
+import { aliasesFrom, readTreeMapsAt, wholeLog } from "./log.js";
 import { appendActionIfAbsent, checkPrecondition, listActions, projectedPreconditionValue, projectResources, isTwinBookkeeping } from "./actions.js";
 import { canonicalJson, diffSubjectFields, hashFieldValue } from "./hash.js";
 import { applyTwinWrite } from "./serve.js";
@@ -173,11 +173,13 @@ export function describeActionFields(ledgers, actions) {
             if (!positions.has(e.id))
                 positions.set(e.id, e.batch ? batchStart : i);
         });
-        for (const { action, service, stateService } of actions.filter(a => a.service === ledger.service && a.stateService === ledger.stateService)) {
-            const at = positions.get(action.id);
-            if (at === undefined || !action.fields)
+        const mine = actions.filter(a => a.service === ledger.service && a.stateService === ledger.stateService && a.action.fields && positions.has(a.action.id));
+        // every write's pre-state from one capture of this twin's history (a capture per write read the whole log each time)
+        const trees = mine.length ? readTreeMapsAt(ledger.stateService, ledger.controlRoot, mine.map(a => positions.get(a.action.id))) : new Map();
+        for (const { action, service, stateService } of mine) {
+            if (!action.fields)
                 continue;
-            const subject = readTreeMap(stateService, ledger.controlRoot, { at }).get(`${action.subject.type}:${action.subject.id}`);
+            const subject = trees.get(positions.get(action.id))?.get(`${action.subject.type}:${action.subject.id}`);
             const fields = subject?.fields ?? {};
             fieldChanges[fieldDiffKey(service, stateService, action.id)] = diffSubjectFields({
                 subject: action.subject, fields, fieldHashes: Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, hashFieldValue(v)])),

package/dist/src/history.d.ts

@@ -40,6 +40,9 @@ export declare function validateHistoryOrigin(origin: HistoryOrigin, layout?: Hi
 export declare const historyEntryTime: (entry: Entry) => number;
 export declare const historyDigest: (value: unknown) => string;
 export declare function historyLength(layout: HistoryLayout, depth?: number): number;
+/** The layout of a view's first `at` entries: historyPrefix's, without the segment digests a prefix view carries (a
+ *  fold reads only the layout, and a partial segment's digest re-reads and hashes its log). */
+export declare function historyLayoutAt(layout: HistoryLayout, at: number): HistoryLayout;
 export declare function readHistoryView(directory: string, id: string): HistoryView;
 export declare function historyEntries(view: HistoryView): Entry[];
 export declare function historyPrefix(view: HistoryView, at: number): HistoryView;

package/dist/src/history.js

@@ -40,6 +40,13 @@ const viewPath = (directory, id) => {
 function rows(directory, file) {
     return getActiveWorldStore().readLines(join(directory, file)).filter(line => line.trim()).map(line => toEntry(parseExactJson(line)));
 }
+/** The layout of a view's first `at` entries: historyPrefix's, without the segment digests a prefix view carries (a
+ *  fold reads only the layout, and a partial segment's digest re-reads and hashes its log). */
+export function historyLayoutAt(layout, at) {
+    if (!Number.isInteger(at) || at < 0 || at > historyLength(layout))
+        throw new Error(`Invalid history position ${at}`);
+    return sliceLayout(layout, at);
+}
 function sliceLayout(layout, at) {
     const base = layout.base ? historyLength(layout.base) : 0;
     return { ...(layout.base ? { base: sliceLayout(layout.base, Math.min(at, base)) } : {}), parent: Math.min(Math.max(0, at - base), layout.parent), branch: Math.min(Math.max(0, at - base - layout.parent), layout.branch) };

package/dist/src/log.d.ts

@@ -183,6 +183,10 @@ export declare function treeChangesSince(service: string, root: string | undefin
     removed: string[];
     appended: string[];
 } | undefined;
+/** The tree at each of several positions of a twin's history, folded from one capture of it: what
+ *  `readTreeMap(service, root, { at })` answers for each, without capturing the history again per position (a
+ *  changeset's field changes read one position per write, and a capture reads the whole log). */
+export declare function readTreeMapsAt(service: string, root: string | undefined, positions: Iterable<number>): Map<number, Tree>;
 export declare function cutCheckpoint(service: string, root?: string): void;
 /** The branch's entries the parent does not hold: `set` rows, not reverted, not landed. */
 export declare function unpushedEntries(service: string, root?: string): Entry[];

package/dist/src/log.js

@@ -23,7 +23,7 @@ import { parseExactJson } from "./exact-json.js";
 // holds. The parent log accepts the v1 observed-event rows too (`toEntry` reads a delta event as
 // an entry; a non-delta observation folds nothing and is kept for `listEvents`), so a World whose
 // log was written in that form still reads.
-import { captureHistory, historyChanges, historyEntryTime, historyEntries, historyLength, historyPrefix, inheritedHistory, inheritedHistoryKey, originHead, readHistoryView, replaceHistoryOrigin, saveHistoryView, validateHistoryOrigin } from "./history.js";
+import { captureHistory, historyChanges, historyEntryTime, historyEntries, historyLayoutAt, historyLength, historyPrefix, inheritedHistory, inheritedHistoryKey, originHead, readHistoryView, replaceHistoryOrigin, saveHistoryView, validateHistoryOrigin } from "./history.js";
 import { dirname, join } from 'node:path';
 import { canonicalStatePath, checkParent, commitParentPin, pinParent, withAncestryLock, withHistoryLock } from "./ancestry.js";
 import { resolveReferences } from "./references.js";
@@ -569,24 +569,39 @@ export function treeChangesSince(service, root, since) {
     }
     return { stamp, changed: treeResources(present), removed, appended: [...order.keys()].filter((k) => tree.has(k)) };
 }
+/** The tree at each of several positions of a twin's history, folded from one capture of it: what
+ *  `readTreeMap(service, root, { at })` answers for each, without capturing the history again per position (a
+ *  changeset's field changes read one position per write, and a capture reads the whole log). */
+export function readTreeMapsAt(service, root, positions) {
+    return withHistoryLock(worldPaths(service, root).dir, () => {
+        const view = captureHistory(service, root).descriptor;
+        const entries = historyEntries(view);
+        const trees = new Map();
+        for (const at of positions)
+            if (!trees.has(at))
+                trees.set(at, treeAt(view, entries, at, service));
+        return trees;
+    });
+}
+/** The tree after a view's first `at` entries; a position inside an observation has none. */
+function treeAt(view, entries, at, service) {
+    if (at > 0 && at < entries.length && entries[at]?.batch && entries[at]?.batch === entries[at - 1]?.batch) {
+        let from = at;
+        let to = at;
+        const batch = entries[at].batch;
+        while (from > 0 && entries[from - 1]?.batch === batch)
+            from--;
+        while (to < entries.length && entries[to]?.batch === batch)
+            to++;
+        throw new Error(`position ${at} falls inside observation ${batch} — use ${from} or ${to}`);
+    }
+    return foldHistory(entries.slice(0, at), historyLayoutAt(view.layout, at), service);
+}
 function readTreeMapFull(service, root, opts = {}) {
     return withHistoryLock(worldPaths(service, root).dir, () => {
         if (opts.at !== undefined || opts.view !== undefined) {
             const view = opts.view ? readHistoryView(worldPaths(service, root).dir, opts.view) : captureHistory(service, root).descriptor;
-            const at = opts.at ?? historyLength(view.layout);
-            const entries = historyEntries(view);
-            if (at > 0 && at < entries.length && entries[at]?.batch && entries[at]?.batch === entries[at - 1]?.batch) {
-                let from = at;
-                let to = at;
-                const batch = entries[at].batch;
-                while (from > 0 && entries[from - 1]?.batch === batch)
-                    from--;
-                while (to < entries.length && entries[to]?.batch === batch)
-                    to++;
-                throw new Error(`position ${at} falls inside observation ${batch} — use ${from} or ${to}`);
-            }
-            const prefix = historyPrefix(view, at);
-            return foldHistory(entries.slice(0, at), prefix.layout, service);
+            return treeAt(view, historyEntries(view), opts.at ?? historyLength(view.layout), service);
         }
         // a cold read (no memo) trusts a checkpoint cut at exactly these log facts without re-hashing the logs
         const facts = opts.until === undefined ? `${parentKeyOf(service, root)}#${statKey(branchLogPath(service, root))}` : null;

package/dist/src/resource-blob.d.ts

@@ -8,6 +8,13 @@ export declare function removeResourceBlob(service: string, key: string, root?:
 /** A service's resources dir at this branch, then at each retained ancestor's: where a read resolves a payload, and
  *  what a listing that mints ids covers, so a branch serves bytes its parent received and never re-mints a parent's id. */
 export declare function resourceChain(service: string, root?: string): string[];
+/** Where a resource blob's key is kept under a resources directory. A key is a relative path, its parts joined by '/'.
+ *  On Windows a part may hold a character no file name can: a ':' there names an NTFS stream of the file before it, so
+ *  `asset:<id>` wrote into a stream of a file named `asset` and the store's rename failed (EINVAL). There each of
+ *  `<>:"|?*`, a control character and '%' itself is written as %XX, one name per key; elsewhere the key is the path. */
+export declare function resourceBlobFile(dir: string, key: string): string;
+/** The key a file under a resources directory holds: resourceBlobFile's inverse, its parts joined by '/'. */
+export declare function resourceBlobKey(dir: string, path: string): string;
 /** Size of a resource payload at this branch or its ancestors, or null. */
 export declare function resourceBlobSize(service: string, key: string, root?: string): Promise<number | null>;
 /** A byte range of a resource payload at this branch or its ancestors (a ranged read where the

package/dist/src/resource-blob.js

@@ -1,4 +1,4 @@
-import { isAbsolute, join } from 'node:path';
+import { isAbsolute, join, relative } from 'node:path';
 import { getActiveBlobStore, readBlobRange } from "./blob-store.js";
 import { readBranchMeta } from "./log.js";
 import { worldPaths } from "./storage.js";
@@ -6,7 +6,7 @@ import { worldPaths } from "./storage.js";
 export async function readResourceBlob(service, key, root) {
     assertResourceKey(key);
     for (const dir of resourceChain(service, root)) {
-        const bytes = await getActiveBlobStore().get(join(dir, key));
+        const bytes = await getActiveBlobStore().get(resourceBlobFile(dir, key));
         if (bytes !== null)
             return bytes;
     }
@@ -15,13 +15,13 @@ export async function readResourceBlob(service, key, root) {
 /** Write a resource payload on this branch (a stored object's bytes), where a read finds it first. */
 export async function writeResourceBlob(service, key, bytes, root) {
     assertResourceKey(key);
-    await getActiveBlobStore().put(join(worldPaths(service, root).resources, key), bytes);
+    await getActiveBlobStore().put(resourceBlobFile(worldPaths(service, root).resources, key), bytes);
 }
 /** Remove this branch's copy of a resource payload; an ancestor's stays its own (the row that named it is what a
  *  deletion ends). */
 export async function removeResourceBlob(service, key, root) {
     assertResourceKey(key);
-    await getActiveBlobStore().remove(join(worldPaths(service, root).resources, key));
+    await getActiveBlobStore().remove(resourceBlobFile(worldPaths(service, root).resources, key));
 }
 /** A service's resources dir at this branch, then at each retained ancestor's: where a read resolves a payload, and
  *  what a listing that mints ids covers, so a branch serves bytes its parent received and never re-mints a parent's id. */
@@ -40,6 +40,18 @@ export function resourceChain(service, root) {
         current = parent.at;
     }
 }
+/** Where a resource blob's key is kept under a resources directory. A key is a relative path, its parts joined by '/'.
+ *  On Windows a part may hold a character no file name can: a ':' there names an NTFS stream of the file before it, so
+ *  `asset:<id>` wrote into a stream of a file named `asset` and the store's rename failed (EINVAL). There each of
+ *  `<>:"|?*`, a control character and '%' itself is written as %XX, one name per key; elsewhere the key is the path. */
+export function resourceBlobFile(dir, key) {
+    return join(dir, process.platform === 'win32' ? key.replace(/[%<>:"|?*\x00-\x1f]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`) : key);
+}
+/** The key a file under a resources directory holds: resourceBlobFile's inverse, its parts joined by '/'. */
+export function resourceBlobKey(dir, path) {
+    const key = relative(dir, path).split('\\').join('/');
+    return process.platform === 'win32' ? key.replace(/%([0-9A-F]{2})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16))) : key;
+}
 function assertResourceKey(key) {
     if (isAbsolute(key) || key.includes('\0') || key.split(/[\\/]/).includes('..'))
         throw new Error('Invalid relative resource blob key');
@@ -48,7 +60,7 @@ function assertResourceKey(key) {
 async function resolveResourceBlob(service, key, root) {
     assertResourceKey(key);
     for (const dir of resourceChain(service, root)) {
-        const path = join(dir, key);
+        const path = resourceBlobFile(dir, key);
         if (await getActiveBlobStore().exists(path))
             return path;
     }

package/dist/src/runtime.d.ts

@@ -78,7 +78,7 @@ export { corsHeaders, withCors, type CorsDecl } from './cors.js';
 export { setInProcessTwins, vendorFetch, VendorUnreachableError, type InProcessTwin } from './vendor-call.js';
 export { closeManagedDatabases, databaseSession, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver, type DatabaseDriver, type DatabaseSession } from './managed-database.js';
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.js';
-export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobSize, resourceChain, writeResourceBlob } from './resource-blob.js';
+export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob } from './resource-blob.js';
 export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, withHistoryLock, withHistoryLocks, withStateLock, withStateRemoval } from './ancestry.js';
 export { captureHistory, captureParentHistory, historyChanges, historyAtInstant, historyDigest, historyEntries, historyLength, historyPrefix, inheritedHistory, originHead, publishOriginHistory, readHistoryView } from './history.js';
 export type { HistoryView, HistoryLayout, HistoryReference, HistoryOrigin } from './history.js';

package/dist/src/runtime.js

@@ -98,7 +98,7 @@ export { multipartBoundary, multipartParts, multipartEnvelope, inferMultipartBou
 export { corsHeaders, withCors } from "./cors.js";
 export { setInProcessTwins, vendorFetch, VendorUnreachableError } from "./vendor-call.js";
 export { closeManagedDatabases, databaseSession, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver } from "./managed-database.js";
-export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobSize, resourceChain, writeResourceBlob } from "./resource-blob.js";
+export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob } from "./resource-blob.js";
 export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, withHistoryLock, withHistoryLocks, withStateLock, withStateRemoval } from "./ancestry.js";
 export { captureHistory, captureParentHistory, historyChanges, historyAtInstant, historyDigest, historyEntries, historyLength, historyPrefix, inheritedHistory, originHead, publishOriginHistory, readHistoryView } from "./history.js";
 export { foldHistory } from "./log.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.148",
+  "version": "3.0.150",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",

package/src/changeset.ts

@@ -57,7 +57,7 @@ import { worldPaths } from './storage.ts';
 // the control root that holds it) and never learns what a world is. `volter-world` supplies
 // discovery and the CLI verbs; the state-level logic lives here, beside the ledgers it reads.
 import { createHash } from 'node:crypto';
-import { aliasesFrom, parentEntries, readTreeMap, wholeLog, type Entry } from './log.ts';
+import { aliasesFrom, parentEntries, readTreeMapsAt, wholeLog, type Entry } from './log.ts';
 import { appendActionIfAbsent, checkPrecondition, listActions, projectedPreconditionValue, projectResources, isTwinBookkeeping } from './actions.ts';
 import type { TwinActionRevertSpec } from './actions.ts';
 import { touchedSubjects } from './actions.ts';
@@ -351,10 +351,12 @@ export function describeActionFields(ledgers: LedgerRef[], actions: ChangesetAct
       if (!e.batch || e.batch !== entries[i - 1]?.batch) batchStart = i;
       if (!positions.has(e.id)) positions.set(e.id, e.batch ? batchStart : i);
     });
-    for (const { action, service, stateService } of actions.filter(a => a.service === ledger.service && a.stateService === ledger.stateService)) {
-      const at = positions.get(action.id);
-      if (at === undefined || !action.fields) continue;
-      const subject = readTreeMap(stateService, ledger.controlRoot, { at }).get(`${action.subject.type}:${action.subject.id}`);
+    const mine = actions.filter(a => a.service === ledger.service && a.stateService === ledger.stateService && a.action.fields && positions.has(a.action.id));
+    // every write's pre-state from one capture of this twin's history (a capture per write read the whole log each time)
+    const trees = mine.length ? readTreeMapsAt(ledger.stateService, ledger.controlRoot, mine.map(a => positions.get(a.action.id)!)) : new Map();
+    for (const { action, service, stateService } of mine) {
+      if (!action.fields) continue;
+      const subject = trees.get(positions.get(action.id)!)?.get(`${action.subject.type}:${action.subject.id}`);
       const fields = subject?.fields ?? {};
       fieldChanges[fieldDiffKey(service, stateService, action.id)] = diffSubjectFields({
         subject: action.subject, fields, fieldHashes: Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, hashFieldValue(v)])),

package/src/history.ts

@@ -37,6 +37,12 @@ const viewPath = (directory: string, id: string) => {
 function rows(directory: string, file: Segment['file']): Entry[] {
   return getActiveWorldStore().readLines(join(directory, file)).filter(line => line.trim()).map(line => toEntry(parseExactJson(line)));
 }
+/** The layout of a view's first `at` entries: historyPrefix's, without the segment digests a prefix view carries (a
+ *  fold reads only the layout, and a partial segment's digest re-reads and hashes its log). */
+export function historyLayoutAt(layout: HistoryLayout, at: number): HistoryLayout {
+  if (!Number.isInteger(at) || at < 0 || at > historyLength(layout)) throw new Error(`Invalid history position ${at}`);
+  return sliceLayout(layout, at);
+}
 function sliceLayout(layout: HistoryLayout, at: number): HistoryLayout {
   const base = layout.base ? historyLength(layout.base) : 0;
   return { ...(layout.base ? { base: sliceLayout(layout.base, Math.min(at, base)) } : {}), parent: Math.min(Math.max(0, at - base), layout.parent), branch: Math.min(Math.max(0, at - base - layout.parent), layout.branch) };

package/src/log.ts

@@ -23,7 +23,7 @@ import { parseExactJson } from './exact-json.ts';
 // holds. The parent log accepts the v1 observed-event rows too (`toEntry` reads a delta event as
 // an entry; a non-delta observation folds nothing and is kept for `listEvents`), so a World whose
 // log was written in that form still reads.
-import { captureHistory, historyChanges, historyEntryTime, historyEntries, historyLength, historyPrefix, inheritedHistory, inheritedHistoryKey, originHead, readHistoryView, replaceHistoryOrigin, saveHistoryView, validateHistoryOrigin, type HistoryLayout } from './history.ts';
+import { captureHistory, historyChanges, historyEntryTime, historyEntries, historyLayoutAt, historyLength, historyPrefix, inheritedHistory, inheritedHistoryKey, originHead, readHistoryView, replaceHistoryOrigin, saveHistoryView, validateHistoryOrigin, type HistoryLayout } from './history.ts';
 import { dirname, join } from 'node:path';
 import { canonicalStatePath, checkParent, commitParentPin, pinParent, withAncestryLock, withHistoryLock } from './ancestry.ts';
 import { resolveReferences } from './references.ts';
@@ -591,20 +591,35 @@ export function treeChangesSince(service: string, root: string | undefined, sinc
   return { stamp, changed: treeResources(present), removed, appended: [...order.keys()].filter((k) => tree.has(k)) };
 }
 
+/** The tree at each of several positions of a twin's history, folded from one capture of it: what
+ *  `readTreeMap(service, root, { at })` answers for each, without capturing the history again per position (a
+ *  changeset's field changes read one position per write, and a capture reads the whole log). */
+export function readTreeMapsAt(service: string, root: string | undefined, positions: Iterable<number>): Map<number, Tree> {
+  return withHistoryLock(worldPaths(service, root).dir, () => {
+    const view = captureHistory(service, root).descriptor;
+    const entries = historyEntries(view);
+    const trees = new Map<number, Tree>();
+    for (const at of positions) if (!trees.has(at)) trees.set(at, treeAt(view, entries, at, service));
+    return trees;
+  });
+}
+
+/** The tree after a view's first `at` entries; a position inside an observation has none. */
+function treeAt(view: ReturnType<typeof captureHistory>['descriptor'], entries: Entry[], at: number, service: string): Tree {
+  if (at > 0 && at < entries.length && entries[at]?.batch && entries[at]?.batch === entries[at - 1]?.batch) {
+    let from = at; let to = at; const batch = entries[at]!.batch;
+    while (from > 0 && entries[from - 1]?.batch === batch) from--;
+    while (to < entries.length && entries[to]?.batch === batch) to++;
+    throw new Error(`position ${at} falls inside observation ${batch} — use ${from} or ${to}`);
+  }
+  return foldHistory(entries.slice(0, at), historyLayoutAt(view.layout, at), service);
+}
+
 function readTreeMapFull(service: string, root?: string, opts: { until?: string; at?: number; view?: string } = {}): Tree {
   return withHistoryLock(worldPaths(service, root).dir, () => {
   if (opts.at !== undefined || opts.view !== undefined) {
     const view = opts.view ? readHistoryView(worldPaths(service, root).dir, opts.view) : captureHistory(service, root).descriptor;
-    const at = opts.at ?? historyLength(view.layout);
-    const entries = historyEntries(view);
-    if (at > 0 && at < entries.length && entries[at]?.batch && entries[at]?.batch === entries[at - 1]?.batch) {
-      let from = at; let to = at; const batch = entries[at]!.batch;
-      while (from > 0 && entries[from - 1]?.batch === batch) from--;
-      while (to < entries.length && entries[to]?.batch === batch) to++;
-      throw new Error(`position ${at} falls inside observation ${batch} — use ${from} or ${to}`);
-    }
-    const prefix = historyPrefix(view, at);
-    return foldHistory(entries.slice(0, at), prefix.layout, service);
+    return treeAt(view, historyEntries(view), opts.at ?? historyLength(view.layout), service);
   }
   // a cold read (no memo) trusts a checkpoint cut at exactly these log facts without re-hashing the logs
   const facts = opts.until === undefined ? `${parentKeyOf(service, root)}#${statKey(branchLogPath(service, root))}` : null;

package/src/resource-blob.ts

@@ -1,4 +1,4 @@
-import { isAbsolute, join } from 'node:path';
+import { isAbsolute, join, relative } from 'node:path';
 import { getActiveBlobStore, readBlobRange } from './blob-store.ts';
 import { readBranchMeta } from './log.ts';
 import { worldPaths } from './storage.ts';
@@ -7,7 +7,7 @@ import { worldPaths } from './storage.ts';
 export async function readResourceBlob(service: string, key: string, root?: string): Promise<Uint8Array | null> {
   assertResourceKey(key);
   for (const dir of resourceChain(service, root)) {
-    const bytes = await getActiveBlobStore().get(join(dir, key));
+    const bytes = await getActiveBlobStore().get(resourceBlobFile(dir, key));
     if (bytes !== null) return bytes;
   }
   return null;
@@ -16,14 +16,14 @@ export async function readResourceBlob(service: string, key: string, root?: stri
 /** Write a resource payload on this branch (a stored object's bytes), where a read finds it first. */
 export async function writeResourceBlob(service: string, key: string, bytes: Uint8Array, root?: string): Promise<void> {
   assertResourceKey(key);
-  await getActiveBlobStore().put(join(worldPaths(service, root).resources, key), bytes);
+  await getActiveBlobStore().put(resourceBlobFile(worldPaths(service, root).resources, key), bytes);
 }
 
 /** Remove this branch's copy of a resource payload; an ancestor's stays its own (the row that named it is what a
  *  deletion ends). */
 export async function removeResourceBlob(service: string, key: string, root?: string): Promise<void> {
   assertResourceKey(key);
-  await getActiveBlobStore().remove(join(worldPaths(service, root).resources, key));
+  await getActiveBlobStore().remove(resourceBlobFile(worldPaths(service, root).resources, key));
 }
 
 /** A service's resources dir at this branch, then at each retained ancestor's: where a read resolves a payload, and
@@ -42,6 +42,20 @@ export function resourceChain(service: string, root?: string): string[] {
   }
 }
 
+/** Where a resource blob's key is kept under a resources directory. A key is a relative path, its parts joined by '/'.
+ *  On Windows a part may hold a character no file name can: a ':' there names an NTFS stream of the file before it, so
+ *  `asset:<id>` wrote into a stream of a file named `asset` and the store's rename failed (EINVAL). There each of
+ *  `<>:"|?*`, a control character and '%' itself is written as %XX, one name per key; elsewhere the key is the path. */
+export function resourceBlobFile(dir: string, key: string): string {
+  return join(dir, process.platform === 'win32' ? key.replace(/[%<>:"|?*\x00-\x1f]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`) : key);
+}
+
+/** The key a file under a resources directory holds: resourceBlobFile's inverse, its parts joined by '/'. */
+export function resourceBlobKey(dir: string, path: string): string {
+  const key = relative(dir, path).split('\\').join('/');
+  return process.platform === 'win32' ? key.replace(/%([0-9A-F]{2})/g, (_, hex: string) => String.fromCharCode(parseInt(hex, 16))) : key;
+}
+
 function assertResourceKey(key: string): void {
   if (isAbsolute(key) || key.includes('\0') || key.split(/[\\/]/).includes('..')) throw new Error('Invalid relative resource blob key');
 }
@@ -50,7 +64,7 @@ function assertResourceKey(key: string): void {
 async function resolveResourceBlob(service: string, key: string, root?: string): Promise<string | null> {
   assertResourceKey(key);
   for (const dir of resourceChain(service, root)) {
-    const path = join(dir, key);
+    const path = resourceBlobFile(dir, key);
     if (await getActiveBlobStore().exists(path)) return path;
   }
   return null;

package/src/runtime.ts

@@ -335,7 +335,7 @@ export { corsHeaders, withCors, type CorsDecl } from './cors.ts';
 export { setInProcessTwins, vendorFetch, VendorUnreachableError, type InProcessTwin } from './vendor-call.ts';
 export { closeManagedDatabases, databaseSession, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver, type DatabaseDriver, type DatabaseSession } from './managed-database.ts';
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.ts';
-export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobSize, resourceChain, writeResourceBlob } from './resource-blob.ts';
+export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob } from './resource-blob.ts';
 
 export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, withHistoryLock, withHistoryLocks, withStateLock, withStateRemoval } from './ancestry.ts';