mikser-io 9.47.0 → 9.49.0

package/docs/api-reference.md

@@ -601,8 +601,31 @@ clearChangeSets(['req-42'])
 | `withChangeSet({ changeSet, summary, principal }, fn)` | run `fn` with a set in effect |
 | `currentChangeSet()` | the set in effect, or null |
 | `recordChangeSetWrite({ changeSet, summary, principal, uri, operation, undoOf })` | attach one path to a set |
-| `pendingChangeSets()` | sets with unconsumed writes, oldest first |
-| `clearChangeSets(ids)` | drop what a consumer has committed |
+| `listChangeSets({ limit })` | the log, newest first |
+| `findChangeSet(id)` | resolve one id |
+| `pendingChangeSets()` | sets no consumer has recorded yet, oldest first |
+| `markChangeSetsRecorded(ids, recordedAs)` | mark recorded, and say what as |
+| `closeChangeSet(id)` | the writer is finished with this set |
+
+`withChangeSet` takes `closeOnReturn` for the case where the call IS the whole
+request — true whenever the id was minted for it rather than supplied. That is
+exact, not a heuristic: an id nobody else can name cannot grow after the call
+that owns it returns, so a consumer can act on it at once instead of waiting to
+see whether more writes arrive. A caller-supplied id exists so several calls
+can join one set, so it stays open and closes on going quiet. Closing happens
+even when the request throws — work that landed before the failure is real, and
+a set left open forever holds it out of reach.
+
+The log is **durable** and survives a restart: nothing else can reconstruct
+which writes belonged to one request. Not the files, which show the result and
+not the grouping — and not a consumer's own history, which may not exist yet,
+or at all. It keeps the most recent 200 sets.
+
+`recordedAs` is what a consumer recorded the set as — a commit sha. Its absence
+is meaningful: the set is real and listable, but there is nothing to revert
+from yet. `mikser_undo` reports that as `not-yet-committed`, which is a
+different answer from `unknown-change-set` and sends a reader somewhere
+different.
 
 ### Ambient, not threaded
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.47.0",
+  "version": "9.49.0",
   "description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
   "main": "index.js",
   "exports": {

package/src/changeset.js

@@ -27,6 +27,52 @@
 import path from 'node:path'
 import { AsyncLocalStorage } from 'node:async_hooks'
 import runtime from './runtime.js'
+import { registerSchema } from './database/index.js'
+
+// The log is DURABLE. It records which writes belonged to which request, and
+// nothing can reconstruct that: not the files, which show the result and not
+// the grouping, and not a consumer's own history, which may not exist yet or
+// at all. Losing it turns every id already handed to an agent into a dangling
+// handle.
+registerSchema('change_sets', `
+    CREATE TABLE IF NOT EXISTS mikser_change_sets (
+        id          TEXT PRIMARY KEY,
+        summary     TEXT,
+        principal   TEXT,
+        undo_of     TEXT,
+        created_at  INTEGER NOT NULL,
+        -- Set when the writer said it was finished. A set that closed is
+        -- committable now; one still open is waiting to see whether more
+        -- writes join it.
+        closed_at   INTEGER,
+        -- When the set last grew. A set is one request, and a request is
+        -- finished when it stops writing — which is the only signal available,
+        -- since a caller grouping several tool calls under one id has not said
+        -- which call is the last.
+        updated_at  INTEGER,
+        -- Set when a consumer has durably recorded the set somewhere of its
+        -- own — a commit, a snapshot. Until then the set is real and listable
+        -- but there is nothing to revert FROM, which is a different answer
+        -- from "no such change set".
+        recorded_at INTEGER,
+        recorded_as TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_mikser_change_sets_created
+        ON mikser_change_sets (created_at DESC);
+
+    CREATE TABLE IF NOT EXISTS mikser_change_set_paths (
+        change_set TEXT NOT NULL,
+        path       TEXT NOT NULL,
+        operation  TEXT NOT NULL,
+        entity_id  TEXT,
+        PRIMARY KEY (change_set, path)
+    );
+`, { durable: true })
+
+// How many sets to keep. An undo log is only useful while the change is
+// recent enough to be worth taking back, and unbounded growth in a durable
+// table is a leak nothing cleans up.
+const KEEP_SETS = 200
 
 // The change set in effect for the current call.
 //
@@ -40,23 +86,140 @@ const changeSetContext = new AsyncLocalStorage()
 
 // Run `fn` with a change set in effect. Writes inside it are attributed to
 // that set unless they name a different one explicitly.
+//
+// `closeOnReturn` says this call IS the whole request — which is true whenever
+// the id was minted for it rather than supplied by the caller. That is a
+// precise signal, not a heuristic: a set nobody else can name cannot grow
+// after the call that owns it returns, so it is committable immediately.
+//
+// A caller-supplied id is the opposite: it exists so several calls can join
+// one set, and nothing in this call knows whether another is coming. Those
+// close on going quiet instead.
 export function withChangeSet(set, fn) {
     if (!set?.changeSet) return fn()
-    return changeSetContext.run({
+    const context = {
         changeSet: set.changeSet,
         summary: set.summary ?? null,
         principal: set.principal ?? null,
         undoOf: set.undoOf ?? null,
-    }, fn)
+    }
+    if (!set.closeOnReturn) return changeSetContext.run(context, fn)
+    return changeSetContext.run(context, async () => {
+        try {
+            return await fn()
+        } finally {
+            // In `finally`: a request that failed part way still wrote what it
+            // wrote, and leaving that set open forever would hold real work
+            // out of the log's committable half.
+            closeChangeSet(set.changeSet)
+        }
+    })
+}
+
+// Mark a set finished. Idempotent, and silent for an id nothing recorded —
+// a request that wrote nothing has no set to close.
+export function closeChangeSet(id) {
+    if (!id) return
+    const at = Date.now()
+    const set = memory.get(id)
+    if (set) set.closedAt = at
+    const handle = db()
+    if (!handle) return
+    try {
+        handle.prepare('UPDATE mikser_change_sets SET closed_at = COALESCE(closed_at, ?) WHERE id = ?').run(at, id)
+    } catch { /* memory still holds it */ }
 }
 
 export function currentChangeSet() {
     return changeSetContext.getStore() ?? null
 }
 
-function store() {
-    runtime.changeSets ??= new Map()
-    return runtime.changeSets
+// The database when there is one, memory when there is not.
+//
+// A write can happen before the engine opens its database — a plugin acting at
+// load time, a unit test — and losing the attribution then would be worse than
+// keeping it somewhere weaker. Both back ends answer the same questions, so no
+// caller has to know which is in play.
+const memory = new Map()
+
+function db() {
+    // Read off the runtime rather than calling useDatabase(): this module is
+    // reached from utils.js, which loads before the database module can be
+    // imported without closing a cycle.
+    const handle = runtime.database?.handle
+    return handle?.prepare ? handle : null
+}
+
+function persist(handle, set, rel, operation, entityId) {
+    handle.prepare(`
+        INSERT INTO mikser_change_sets (id, summary, principal, undo_of, created_at, updated_at)
+        VALUES (@id, @summary, @principal, @undoOf, @createdAt, @updatedAt)
+        ON CONFLICT(id) DO UPDATE SET
+            summary    = COALESCE(mikser_change_sets.summary, excluded.summary),
+            principal  = COALESCE(mikser_change_sets.principal, excluded.principal),
+            undo_of    = COALESCE(mikser_change_sets.undo_of, excluded.undo_of),
+            updated_at = excluded.updated_at
+    `).run({
+        id: set.id, summary: set.summary, principal: set.principal,
+        undoOf: set.undoOf, createdAt: set.startedAt, updatedAt: set.updatedAt,
+    })
+    handle.prepare(`
+        INSERT INTO mikser_change_set_paths (change_set, path, operation, entity_id)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT(change_set, path) DO UPDATE SET operation = excluded.operation
+    `).run(set.id, rel, operation, entityId ?? null)
+    prune(handle)
+}
+
+function prune(handle) {
+    handle.prepare(`
+        DELETE FROM mikser_change_set_paths WHERE change_set IN (
+            SELECT id FROM mikser_change_sets
+            ORDER BY created_at DESC LIMIT -1 OFFSET ?
+        )
+    `).run(KEEP_SETS)
+    handle.prepare(`
+        DELETE FROM mikser_change_sets WHERE id IN (
+            SELECT id FROM mikser_change_sets ORDER BY created_at DESC LIMIT -1 OFFSET ?
+        )
+    `).run(KEEP_SETS)
+}
+
+function rowsToSets(handle, rows) {
+    const stmt = handle.prepare(
+        'SELECT path, operation FROM mikser_change_set_paths WHERE change_set = ? ORDER BY path')
+    return rows.map(row => {
+        const paths = stmt.all(row.id)
+        return {
+            id: row.id,
+            summary: row.summary,
+            principal: row.principal,
+            undoOf: row.undo_of,
+            startedAt: row.created_at,
+            updatedAt: row.updated_at ?? row.created_at,
+            closed: row.closed_at != null,
+            recordedAt: row.recorded_at ?? null,
+            recordedAs: row.recorded_as ?? null,
+            paths: paths.map(p => p.path),
+            deletions: paths.filter(p => p.operation === 'delete').map(p => p.path),
+        }
+    })
+}
+
+function memorySets(filter = () => true) {
+    return [...memory.values()].filter(set => set.paths.size).filter(filter).map(set => ({
+        id: set.id,
+        summary: set.summary,
+        principal: set.principal,
+        undoOf: set.undoOf,
+        startedAt: set.startedAt,
+        updatedAt: set.updatedAt ?? set.startedAt,
+        closed: Boolean(set.closedAt),
+        recordedAt: set.recordedAt ?? null,
+        recordedAs: set.recordedAs ?? null,
+        paths: [...set.paths.keys()],
+        deletions: [...set.paths.entries()].filter(([, op]) => op === 'delete').map(([p]) => p),
+    }))
 }
 
 // Relative to the working folder, POSIX-separated.
@@ -78,7 +241,9 @@ function relativeToWorkingFolder(uri) {
 // nothing downstream will ever know it as well — a reader choosing what to
 // undo needs "changed the hero text on the devices page", not a file count.
 // First one wins: later writes in the same set are the same request.
-export function recordChangeSetWrite({ changeSet, summary, principal, uri, operation = 'write', undoOf } = {}) {
+export function recordChangeSetWrite({
+    changeSet, summary, principal, uri, operation = 'write', undoOf, entityId,
+} = {}) {
     // An explicit id always wins; otherwise take whatever set is in effect.
     // A write with neither stays unclaimed, which is the correct outcome for
     // an API or human write that no request owns.
@@ -94,8 +259,7 @@ export function recordChangeSetWrite({ changeSet, summary, principal, uri, opera
     // produce a selector that quietly matches nothing.
     if (!rel) return null
 
-    const sets = store()
-    let set = sets.get(changeSet)
+    let set = memory.get(changeSet)
     if (!set) {
         set = {
             id: changeSet,
@@ -106,45 +270,102 @@ export function recordChangeSetWrite({ changeSet, summary, principal, uri, opera
             // privileged operation that rewrites the record.
             undoOf: undoOf ?? null,
             startedAt: Date.now(),
+            updatedAt: Date.now(),
             paths: new Map(),
         }
-        sets.set(changeSet, set)
+        memory.set(changeSet, set)
     }
     if (!set.summary && summary) set.summary = summary
     if (!set.principal && principal) set.principal = principal
     if (!set.undoOf && undoOf) set.undoOf = undoOf
+    set.updatedAt = Date.now()
     set.paths.set(rel, operation)
+
+    const handle = db()
+    if (handle) {
+        try { persist(handle, set, rel, operation, entityId) } catch { /* memory still holds it */ }
+    }
     return set.id
 }
 
-// Every set with writes not yet consumed, oldest first — the order the work
-// actually happened in, which is the order a consumer should record it in.
+// Sets a consumer has not yet durably recorded, oldest first — the order the
+// work actually happened in, which is the order it should be recorded in.
 export function pendingChangeSets() {
-    return [...store().values()]
-        .filter(set => set.paths.size)
-        .sort((a, b) => a.startedAt - b.startedAt)
-        .map(set => ({
-            id: set.id,
-            summary: set.summary,
-            principal: set.principal,
-            undoOf: set.undoOf,
-            startedAt: set.startedAt,
-            paths: [...set.paths.keys()],
-            deletions: [...set.paths.entries()].filter(([, op]) => op === 'delete').map(([p]) => p),
-        }))
-}
-
-// Drop sets a consumer has dealt with.
-//
-// Called after a consumer has durably recorded the paths, not after they are
-// written: a crash in between loses the attribution but not the work, which
-// then reaches the consumer as an unclaimed write. That is the right way
-// round — attribution is a convenience, the bytes are not.
-export function clearChangeSets(ids = []) {
-    const sets = store()
-    for (const id of ids) sets.delete(id)
+    const handle = db()
+    if (handle) {
+        try {
+            const rows = handle.prepare(`
+                SELECT * FROM mikser_change_sets WHERE recorded_at IS NULL ORDER BY created_at ASC
+            `).all()
+            return rowsToSets(handle, rows).filter(set => set.paths.length)
+        } catch { /* fall through to memory */ }
+    }
+    return memorySets(set => !set.recordedAt).sort((a, b) => a.startedAt - b.startedAt)
+}
+
+// The log an agent reads: every set, newest first, whether or not a consumer
+// has recorded it anywhere.
+export function listChangeSets({ limit = 20 } = {}) {
+    const handle = db()
+    if (handle) {
+        try {
+            const rows = handle.prepare(`
+                SELECT * FROM mikser_change_sets ORDER BY created_at DESC LIMIT ?
+            `).all(Math.max(1, Math.min(limit, 200)))
+            return rowsToSets(handle, rows)
+        } catch { /* fall through to memory */ }
+    }
+    return memorySets().sort((a, b) => b.startedAt - a.startedAt).slice(0, limit)
+}
+
+export function findChangeSet(id) {
+    if (!id) return null
+    const handle = db()
+    if (handle) {
+        try {
+            const row = handle.prepare('SELECT * FROM mikser_change_sets WHERE id = ?').get(id)
+            return row ? rowsToSets(handle, [row])[0] : null
+        } catch { /* fall through to memory */ }
+    }
+    return memorySets(set => set.id === id)[0] ?? null
+}
+
+// Mark sets a consumer has durably recorded, and say what it recorded them AS
+// — a commit sha, a snapshot id. That reference is what an undo reverts from,
+// and its absence is why "recorded but not yet committed" is a different
+// answer from "no such change set".
+export function markChangeSetsRecorded(ids = [], recordedAs = null) {
+    const at = Date.now()
+    for (const id of ids) {
+        const set = memory.get(id)
+        if (set) { set.recordedAt = at; set.recordedAs = recordedAs }
+    }
+    const handle = db()
+    if (!handle) return
+    try {
+        const stmt = handle.prepare(
+            'UPDATE mikser_change_sets SET recorded_at = ?, recorded_as = ? WHERE id = ?')
+        for (const id of ids) stmt.run(at, recordedAs, id)
+    } catch { /* memory still holds it */ }
+}
+
+// Kept as the name consumers already call. Marking recorded is what "done
+// with it" means now — the set stays in the log so it can still be undone.
+export function clearChangeSets(ids = [], recordedAs = null) {
+    markChangeSetsRecorded(ids, recordedAs)
 }
 
 export function forgetAllChangeSets() {
-    store().clear()
+    memory.clear()
+    const handle = db()
+    if (!handle) return
+    try {
+        handle.exec('DELETE FROM mikser_change_set_paths; DELETE FROM mikser_change_sets;')
+    } catch { /* nothing to clear */ }
 }
+
+// Published on the runtime so the write primitives in utils.js can record
+// without importing this module. utils.js loads early — before the database
+// module can be imported here without closing a cycle — and an import purely
+// to reach one function is what would close it.
+runtime.recordChangeSetWrite = recordChangeSetWrite

package/src/utils.js

@@ -11,7 +11,6 @@ import yaml from 'yaml'
 import { contentType } from 'mime-types'
 import runtime from './runtime.js'
 import { trackedInfo, untrack, recordReads } from './track.js'
-import { recordChangeSetWrite } from './changeset.js'
 
 // Stable content fingerprint for entities — used by manifest snapshots,
 // engine mutation tracking, and the layouts dispatcher's hash-aware
@@ -794,7 +793,7 @@ export async function writeEntity(entity, patch = {}) {
     // The other file-writing primitive. A rename cascade rewrites every
     // referring file through here, which is the largest fan-out any single
     // request has and therefore the one most worth being able to take back.
-    recordChangeSetWrite({ uri: entity.uri })
+    runtime.recordChangeSetWrite?.({ uri: entity.uri })
 
     return entity.uri
 }
@@ -1114,14 +1113,14 @@ export function useCollection(runtime, name) {
             // of change sets still produces undoable work — the alternative is
             // every writer remembering, and the one that forgets is the one
             // whose edit cannot be taken back.
-            recordChangeSetWrite({ uri })
+            runtime.recordChangeSetWrite?.({ uri })
             return uri
         },
 
         async remove(relativePath) {
             const uri = resolveWithin(relativePath)
             await unlink(uri)
-            recordChangeSetWrite({ uri, operation: 'delete' })
+            runtime.recordChangeSetWrite?.({ uri, operation: 'delete' })
         },
     }
 }