mikser-io 11.10.0 → 11.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "11.10.0",
+  "version": "11.10.2",
   "files": [
     "app.js",
     "index.js",

package/src/journal.js

@@ -235,6 +235,25 @@ export async function* useJournal(name, operations, signal) {
 
             // Yield returned — caller's for-body completed for this
             // iteration. Diff and write back if mutated.
+            //
+            // WHICH MEANS: a consumer that mutates `entry.entity` MUST finish
+            // that mutation before its loop body completes. `for await` does
+            // this by construction. Mapping over this generator concurrently
+            // does NOT — p-map and friends pull the next item as soon as a
+            // worker slot frees, which resumes the generator here, before any
+            // body has finished. The diff then sees an untouched entity and
+            // writes nothing.
+            //
+            // Not a race that usually works: measured at concurrency 2 and 4,
+            // zero of six mutations survived. Every one, silently, with
+            // whatever the work cost already spent.
+            //
+            // Concurrent mapping over the journal is still fine for a plugin
+            // that writes somewhere else — mikser-io-vector embeds into an
+            // external store and never touches `entity`. A plugin that
+            // mutates entities and wants concurrency has to gather first, do
+            // the work off the journal, then apply inside a second walk;
+            // mikser-io-ocr does exactly that and says why.
             if (entry.entity != null) {
                 const currentEntity = JSON.stringify(entry.entity)
                 if (currentEntity !== originalEntity) {
@@ -317,5 +336,31 @@ onFinalized(async () => {
 })
 
 onCancelled(async () => {
-    clearJournal()
+    // NOT cleared. A cancelled cycle's entries are not superseded work —
+    // "this entity was created and nothing has processed it" is still true
+    // after the restart, and the restarted cycle will not re-journal it: the
+    // source gate compares checksums, finds the file unchanged, and emits
+    // nothing. So deleting these rows orphaned the entity permanently. It sat
+    // in the catalog with empty meta, no output, and no journal entry any
+    // future cycle would look at, under a green "Mikser completed" — and
+    // touching the file was the only way to get it back.
+    //
+    // Reported against a 4 MB PDF uploaded over WebDAV: the upload landed
+    // mid-cycle, the restart deleted the CREATE entry, and the page was never
+    // produced. Nothing about it was specific to the plugin that noticed —
+    // any consumer doing real work between a journal read and its write-back
+    // had the same hole.
+    //
+    // The asymmetry was the tell: a CRASH leaves these rows and `--resume`
+    // continues from them (see the leftover bootstrap above), while a restart
+    // deliberately deleted them. Keeping them makes a restart behave like the
+    // case the engine already handles.
+    //
+    // They are cleared by onFinalized when a cycle actually completes, so a
+    // run of cancellations carries its backlog forward and the first cycle to
+    // finish clears the lot.
+    const carried = stmtCount.get().n
+    if (carried > 0) {
+        useLogger()?.debug('Restart: carrying %d unprocessed journal entries into the next cycle', carried)
+    }
 })