@volter/world-core 3.0.149 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.149",
+  "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;