@volter/world-runtime 3.0.25 → 3.0.26

package/dist/src/served-world.js

@@ -19,6 +19,7 @@ import { getActiveWorldStore, withHistoryLocks, captureHistory, historyAtInstant
 //   GET/PUT clock, POST clock/advance   the frozen instant every twin stamps from, forward only
 //   GET/POST branches, DELETE branches/<org>/<world>   the host's branches of this World ("as of" views)
 //   GET  history?at=<instant>        each twin's history cut at an instant (where such a branch starts)
+//   GET/POST marks                   where the World's changes count from; POST { note? } marks it now
 //   GET  /<org>/<world>/<vendor>/<path>   the vendor's own screens, the pack's workspaces (its `GET /twin` lists them)
 // Tokens ride `x-volter-token`: the token opens everything, the read token only reads — on the vendor
 // wire, a twin that enforces it (`requestScopes: ['read']`) is handed the read token's other requests
@@ -33,7 +34,7 @@ import { grantOf, presentedSecrets, sameSecret, spentPasses, verifyPass } from '
 import { createHash } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
 import { appendActionIfAbsent, branchEntries, branchLogPath, branchMetaPath, changesetContentHash, changesetReadiness, confirmAction, parentLogPath, readTree, stateDirName, wholeLog, worldNow, parentEntries, readBranchMeta, rebaseBranch, } from '@volter/world-core/runtime';
-import { approveWorldChangeset, createWorldChangeset, diffWorld, findWorldChangeset, listWorldChangesets, pushWorldChangeset, verifyWorldChangeset, worldChangesetsDir } from "./changeset.js";
+import { approveWorldChangeset, createWorldChangeset, diffWorld, findWorldChangeset, listWorldChangesets, listWorldMarks, markWorld, MARK_NOTE_MAX, pushWorldChangeset, verifyWorldChangeset, worldChangesetsDir } from "./changeset.js";
 import { fetchFromOrigin } from "./origin.js";
 import { CONSOLE_BASE, consoleRedirect, serveConsoleApart } from "./console-apart.js";
 import { loadWorldConfig, worldChangesetRules, writeWorldConfig } from "./configs.js";
@@ -1543,6 +1544,30 @@ export class WorldDoors {
                 views[vendor] = historyAtInstant(this.stateOf(vendor), instant, this.controlRoot(vendor)); });
             return Response.json({ world: this.served, at: new Date(Date.parse(instant)).toISOString(), views });
         }
+        // THE WORLD'S MARKS (`GET marks`, `POST marks { note? }`): where its changes count from. A World seeded through its
+        // doors (a hosted one has no seed run to land its starting data as already there) is marked once it is set up, so
+        // what it starts with is not counted as its changes; the latest mark is the base of the diff, the board's Changes
+        // and a new changeset, as `volter-world mark <world>` makes it on this machine
+        if (kind === 'marks' && !name && request.method === 'GET')
+            return Response.json({ world: this.served, marks: listWorldMarks(this.name, this.worldRoot) });
+        if (kind === 'marks' && !name && request.method === 'POST') {
+            const body = (await request.json().catch(() => ({})));
+            if (!body || typeof body !== 'object' || Array.isArray(body))
+                return Response.json({ error: 'a mark is sent as a JSON object' }, { status: 400 });
+            if (body.note !== undefined && (typeof body.note !== 'string' || body.note.length > MARK_NOTE_MAX))
+                return Response.json({ error: `a mark's note is a string of at most ${MARK_NOTE_MAX} characters` }, { status: 400 });
+            const vendors = Object.keys(this.up().services);
+            // taken while no twin writes, so it stands at one position of every log
+            const { mark, passed } = withHistoryLocks(vendors.map((vendor) => worldPaths(this.stateOf(vendor), this.controlRoot(vendor)).dir), () => {
+                const delta = diffWorld(this.name, { root: this.worldRoot });
+                // what another World pushed here is in its changeset already: never this World's uncut changes
+                const received = new Set(listWorldChangesets({ root: this.worldRoot, world: this.name }).filter((l) => l.changeset.pushedBy).flatMap((l) => l.changeset.actions.map((a) => a.action.id)));
+                const passed = delta.actions.filter((a) => !received.has(a.action.id)).length;
+                const mark = markWorld(this.name, { root: this.worldRoot, ...(typeof body.note === 'string' && body.note.trim() ? { note: body.note } : {}) });
+                return { mark, passed };
+            });
+            return Response.json({ world: this.served, mark, passed }, { status: 201 });
+        }
         if (kind === 'map' && !name && request.method === 'GET')
             return Response.json(await this.map());
         if (kind === 'board' && !name && request.method === 'GET')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.25",
+  "version": "3.0.26",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -68,14 +68,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.25",
-    "@volter/world-console": "3.0.20"
+    "@volter/world-core": "3.0.26",
+    "@volter/world-console": "3.0.21"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "3.0.1",
-    "@volter/world-core": "3.0.25",
+    "@volter/world-core": "3.0.26",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",
     "yaml": "2.9.0"

package/src/served-world.ts

@@ -19,6 +19,7 @@ import { getActiveWorldStore, withHistoryLocks, captureHistory, historyAtInstant
 //   GET/PUT clock, POST clock/advance   the frozen instant every twin stamps from, forward only
 //   GET/POST branches, DELETE branches/<org>/<world>   the host's branches of this World ("as of" views)
 //   GET  history?at=<instant>        each twin's history cut at an instant (where such a branch starts)
+//   GET/POST marks                   where the World's changes count from; POST { note? } marks it now
 //   GET  /<org>/<world>/<vendor>/<path>   the vendor's own screens, the pack's workspaces (its `GET /twin` lists them)
 // Tokens ride `x-volter-token`: the token opens everything, the read token only reads — on the vendor
 // wire, a twin that enforces it (`requestScopes: ['read']`) is handed the read token's other requests
@@ -36,7 +37,7 @@ import {
   appendActionIfAbsent, branchEntries, branchLogPath, branchMetaPath, changesetContentHash, changesetReadiness, confirmAction, parentLogPath, readTree, stateDirName, wholeLog, worldNow,
   parentEntries, readBranchMeta, rebaseBranch, type Changeset, type Entry, type Receipt, type RootConfig,
 } from '@volter/world-core/runtime';
-import { approveWorldChangeset, createWorldChangeset, diffWorld, findWorldChangeset, listWorldChangesets, pushWorldChangeset, verifyWorldChangeset, worldChangesetsDir } from './changeset.ts';
+import { approveWorldChangeset, createWorldChangeset, diffWorld, findWorldChangeset, listWorldChangesets, listWorldMarks, markWorld, MARK_NOTE_MAX, pushWorldChangeset, verifyWorldChangeset, worldChangesetsDir } from './changeset.ts';
 import { fetchFromOrigin } from './origin.ts';
 import { CONSOLE_BASE, consoleRedirect, serveConsoleApart, type ConsoleMount } from './console-apart.ts';
 import { loadWorldConfig, worldChangesetRules, writeWorldConfig } from './configs.ts';
@@ -1340,6 +1341,27 @@ export class WorldDoors {
       withHistoryLocks(vendors.map((vendor) => worldPaths(this.stateOf(vendor), this.controlRoot(vendor)).dir), () => { for (const vendor of vendors) views[vendor] = historyAtInstant(this.stateOf(vendor), instant, this.controlRoot(vendor)); });
       return Response.json({ world: this.served, at: new Date(Date.parse(instant)).toISOString(), views });
     }
+    // THE WORLD'S MARKS (`GET marks`, `POST marks { note? }`): where its changes count from. A World seeded through its
+    // doors (a hosted one has no seed run to land its starting data as already there) is marked once it is set up, so
+    // what it starts with is not counted as its changes; the latest mark is the base of the diff, the board's Changes
+    // and a new changeset, as `volter-world mark <world>` makes it on this machine
+    if (kind === 'marks' && !name && request.method === 'GET') return Response.json({ world: this.served, marks: listWorldMarks(this.name, this.worldRoot) });
+    if (kind === 'marks' && !name && request.method === 'POST') {
+      const body = (await request.json().catch(() => ({}))) as { note?: unknown };
+      if (!body || typeof body !== 'object' || Array.isArray(body)) return Response.json({ error: 'a mark is sent as a JSON object' }, { status: 400 });
+      if (body.note !== undefined && (typeof body.note !== 'string' || body.note.length > MARK_NOTE_MAX)) return Response.json({ error: `a mark's note is a string of at most ${MARK_NOTE_MAX} characters` }, { status: 400 });
+      const vendors = Object.keys(this.up().services);
+      // taken while no twin writes, so it stands at one position of every log
+      const { mark, passed } = withHistoryLocks(vendors.map((vendor) => worldPaths(this.stateOf(vendor), this.controlRoot(vendor)).dir), () => {
+        const delta = diffWorld(this.name, { root: this.worldRoot });
+        // what another World pushed here is in its changeset already: never this World's uncut changes
+        const received = new Set(listWorldChangesets({ root: this.worldRoot, world: this.name }).filter((l) => l.changeset.pushedBy).flatMap((l) => l.changeset.actions.map((a) => a.action.id)));
+        const passed = delta.actions.filter((a) => !received.has(a.action.id)).length;
+        const mark = markWorld(this.name, { root: this.worldRoot, ...(typeof body.note === 'string' && body.note.trim() ? { note: body.note } : {}) });
+        return { mark, passed };
+      });
+      return Response.json({ world: this.served, mark, passed }, { status: 201 });
+    }
     if (kind === 'map' && !name && request.method === 'GET') return Response.json(await this.map());
     if (kind === 'board' && !name && request.method === 'GET') return Response.json(await this.board(url));
     if (kind === 'board' && name === 'changes' && !verb && request.method === 'GET') return await this.boardChanges(url);