mikser-io 9.45.0 → 9.46.1

package/docs/api-reference.md

@@ -598,10 +598,39 @@ clearChangeSets(['req-42'])
 
 | Export | Does |
 | --- | --- |
+| `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 |
 
+### Ambient, not threaded
+
+Passing an id through every write is fine for one API and hopeless across a
+plugin ecosystem — `mikser-io-drive` writes with `fs.writeFile`, a rename
+cascade goes through `writeEntity`, and every new mutating tool would have to
+remember. `withChangeSet` puts one in scope instead, and the write primitives
+attribute themselves:
+
+```js
+await withChangeSet({ changeSet: 'req-42', summary: 'Rewrite the hero copy' }, async () => {
+    await useCollection(runtime, 'documents').write('hero.md', text)   // attributed
+    await writeEntity({ uri }, { title })                             // attributed
+})
+```
+
+`useCollection().write` / `.remove` and `writeEntity` record automatically, so
+code that has never heard of change sets still produces undoable work. A plugin
+writing with raw `fs` calls `recordChangeSetWrite({ uri })` with no id and
+picks up whatever is in effect. An explicit id always wins over the ambient
+one, and a write with neither stays unclaimed.
+
+In `mikser-io-mcp`, a tool registered with `mutates: true` gets `changeSet` and
+`summary` added to its schema and its handler wrapped in `withChangeSet`
+automatically — declared once per tool rather than threaded through each write,
+because a new mutating tool that forgets the plumbing is one whose edits
+silently cannot be undone.
+
 Paths come back repo-relative and POSIX-separated, ready for a git pathspec.
 
 **Not a transaction.** Nothing is held back, nothing rolls back on failure, and
@@ -617,6 +646,12 @@ happened, and losing them would be worse than not attributing them.
 rest into unattributed ones, which is what lets it offer undo for the first and
 not the second.
 
+The engine records the grouping and takes no position on what is done with it —
+it knows nothing about commits, branches or reverts. Versioning the paths
+together is one use; a snapshot, an audit trail, a draft-then-publish gate or a
+filesystem-level rollback all want the same fact. That is why change sets live
+in core and git does not.
+
 ## Search
 
 `queryEntities` sifts **meta**. `searchEntities` answers the other question —

package/package.json

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

package/src/changeset.js

@@ -8,8 +8,12 @@
 // second are indistinguishable, so removing one removes the other.
 //
 // A change set is the missing grain. The caller names it, the writes
-// accumulate under it, and a consumer — mikser-io-git today — can commit
-// exactly those paths and later remove exactly that contribution.
+// accumulate under it, and a consumer can act on exactly those paths.
+//
+// The engine records the grouping and takes no position on what is done with
+// it. Versioning the paths together is one use — mikser-io-git's — but a
+// snapshot, an audit trail, a draft-then-publish gate or a filesystem-level
+// rollback all want the same fact, and none of them is a commit.
 //
 // Deliberately NOT a transaction. Nothing is held back, nothing rolls back on
 // failure, and a half-finished set is a real set containing what actually
@@ -21,15 +25,45 @@
 // attribute them.
 
 import path from 'node:path'
+import { AsyncLocalStorage } from 'node:async_hooks'
 import runtime from './runtime.js'
 
+// The change set in effect for the current call.
+//
+// Threading an id through every write is fine for one API and hopeless across
+// a plugin ecosystem: mikser-io-drive writes with fs.writeFile, forms writes
+// its own entities, and each new mutating tool would have to remember. An
+// ambient context means a caller declares the set ONCE and everything written
+// underneath is attributed, including by code that has never heard of change
+// sets.
+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.
+export function withChangeSet(set, fn) {
+    if (!set?.changeSet) return fn()
+    return changeSetContext.run({
+        changeSet: set.changeSet,
+        summary: set.summary ?? null,
+        principal: set.principal ?? null,
+        undoOf: set.undoOf ?? null,
+    }, fn)
+}
+
+export function currentChangeSet() {
+    return changeSetContext.getStore() ?? null
+}
+
 function store() {
     runtime.changeSets ??= new Map()
     return runtime.changeSets
 }
 
-// Repo-relative, POSIX-separated: these end up in a git pathspec, and a
-// consumer should not have to redo that conversion or guess the root.
+// Relative to the working folder, POSIX-separated.
+//
+// The working folder is the root every consumer already reasons in, and
+// forward slashes are the separator entity ids use — so a path here matches
+// the vocabulary of the rest of the engine rather than the host's.
 function relativeToWorkingFolder(uri) {
     const root = runtime.options?.workingFolder
     if (!root || !uri) return null
@@ -45,11 +79,19 @@ function relativeToWorkingFolder(uri) {
 // 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 } = {}) {
+    // 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.
+    const ambient = currentChangeSet()
+    changeSet ??= ambient?.changeSet
+    summary ??= ambient?.summary
+    principal ??= ambient?.principal
+    undoOf ??= ambient?.undoOf
     if (!changeSet || !uri) return null
     const rel = relativeToWorkingFolder(uri)
-    // Outside the working folder there is nothing a repo-scoped consumer can
-    // do with the path, and silently keeping an absolute one would produce a
-    // pathspec that matches nothing.
+    // Outside the working folder there is nothing a consumer scoped to the
+    // project can do with the path, and silently keeping an absolute one would
+    // produce a selector that quietly matches nothing.
     if (!rel) return null
 
     const sets = store()
@@ -59,9 +101,9 @@ export function recordChangeSetWrite({ changeSet, summary, principal, uri, opera
             id: changeSet,
             summary: summary ?? null,
             principal: principal ?? null,
-            // Set when this change set exists to take another one back, so
-            // the undo is itself an ordinary, undoable change rather than a
-            // special history-rewriting operation.
+            // Set when this change set exists to take another one back, so an
+            // undo is itself an ordinary, undoable change rather than a
+            // privileged operation that rewrites the record.
             undoOf: undoOf ?? null,
             startedAt: Date.now(),
             paths: new Map(),
@@ -75,8 +117,8 @@ export function recordChangeSetWrite({ changeSet, summary, principal, uri, opera
     return set.id
 }
 
-// Every set with writes not yet consumed, oldest first — the order a consumer
-// should commit them in, so history reads the way the work happened.
+// 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.
 export function pendingChangeSets() {
     return [...store().values()]
         .filter(set => set.paths.size)
@@ -94,10 +136,10 @@ export function pendingChangeSets() {
 
 // Drop sets a consumer has dealt with.
 //
-// Called after the paths are committed, 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.
+// 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)

package/src/utils.js

@@ -11,6 +11,7 @@ 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
@@ -790,6 +791,10 @@ export async function writeEntity(entity, patch = {}) {
 
     await mkdir(path.dirname(entity.uri), { recursive: true })
     await writeFile(entity.uri, newContent, 'utf8')
+    // 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 })
 
     return entity.uri
 }
@@ -1104,11 +1109,19 @@ export function useCollection(runtime, name) {
             const uri = resolveWithin(relativePath)
             await mkdir(path.dirname(uri), { recursive: true })
             await writeFile(uri, content, 'utf8')
+            // Attributed to whatever change set is in effect, if any. Hooked
+            // at the lowest write primitive so a plugin that has never heard
+            // 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 })
             return uri
         },
 
         async remove(relativePath) {
-            await unlink(resolveWithin(relativePath))
+            const uri = resolveWithin(relativePath)
+            await unlink(uri)
+            recordChangeSetWrite({ uri, operation: 'delete' })
         },
     }
 }

package/src/write.js

@@ -24,7 +24,7 @@ import runtime from './runtime.js'
 import { readEntity, findEntities } from './catalog.js'
 import { useCollection, checksum, readEntityContent, lookupKeys } from './utils.js'
 import { nextCycleId, whenCycleCompletes } from './report.js'
-import { recordChangeSetWrite } from './changeset.js'
+import { recordChangeSetWrite, currentChangeSet } from './changeset.js'
 
 // How far into a file to look for a marker. A header nobody reads is not a
 // header; one buried 200 lines down is not either.
@@ -172,6 +172,14 @@ export async function writeEntitySource({
     summary,
     principal,
 } = {}) {
+    // An explicit id wins; otherwise inherit whatever set is in effect, so the
+    // response can name the set a caller would undo even when the caller never
+    // passed one.
+    const ambient = currentChangeSet()
+    changeSet ??= ambient?.changeSet
+    summary ??= ambient?.summary
+    principal ??= ambient?.principal
+
     if (id) {
         const located = await locateEntityFile(id)
         if (located.error) return { ok: false, refused: 'unresolvable-id', error: located.error }
@@ -306,6 +314,14 @@ export async function deleteEntitySource({
     summary,
     principal,
 } = {}) {
+    // An explicit id wins; otherwise inherit whatever set is in effect, so the
+    // response can name the set a caller would undo even when the caller never
+    // passed one.
+    const ambient = currentChangeSet()
+    changeSet ??= ambient?.changeSet
+    summary ??= ambient?.summary
+    principal ??= ambient?.principal
+
     if (id) {
         const located = await locateEntityFile(id)
         if (located.error) return { ok: false, refused: 'unresolvable-id', error: located.error }