mikser-io 11.1.0 → 11.2.1

package/package.json

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

package/src/changeset.js

@@ -84,6 +84,27 @@ registerMigrations('change-sets', [
             })
         },
     },
+    {
+        // What the write actually put there.
+        //
+        // Without it, a set that produced no commit is ambiguous in a way that
+        // matters: the file on disk being identical to the last commit means
+        // EITHER the write matched what was already committed, or something
+        // replaced it before the commit pass ran. The first is a no-op; the
+        // second is lost work. From disk alone they are the same picture, and
+        // a real one was misread as the harmless case on a live site.
+        //
+        // Recorded at write time, so a consumer can ask afterwards whether
+        // what it wrote is still there. Nullable: a writer that does not know
+        // its own bytes records nothing, and a consumer must then say it
+        // cannot tell rather than assume either way.
+        name: '002-write-checksums',
+        up: async (knex) => {
+            await knex.schema.alterTable('mikser_change_set_paths', (table) => {
+                table.string('checksum')
+            })
+        },
+    },
 ])
 
 // How many sets to keep. An undo log is only useful while the change is
@@ -197,7 +218,7 @@ async function settled() {
     try { await queue } catch { /* reported at the point of failure */ }
 }
 
-async function persist(knex, set, rel, operation, entityId) {
+async function persist(knex, set, rel, operation, entityId, checksum) {
     // COALESCE rather than a plain merge: the first write's summary is the
     // request's own description of itself, and a later write in the same set
     // must not overwrite it with its own. `excluded` is the pseudo-table on
@@ -220,9 +241,17 @@ async function persist(knex, set, rel, operation, entityId) {
         })
 
     await knex('mikser_change_set_paths')
-        .insert({ change_set: set.id, path: rel, operation, entity_id: entityId ?? null })
+        .insert({ change_set: set.id, path: rel, operation, entity_id: entityId ?? null,
+                  checksum: checksum ?? null })
         .onConflict(['change_set', 'path'])
-        .merge({ operation: knex.raw('excluded.operation') })
+        // The LATEST write to a path is the one that says what should be there
+        // now, so its checksum replaces the earlier one — but only when it has
+        // one, or a writer that knows its bytes is overwritten by one that
+        // does not and the path silently becomes unverifiable.
+        .merge({
+            operation: knex.raw('excluded.operation'),
+            checksum: knex.raw('COALESCE(excluded.checksum, mikser_change_set_paths.checksum)'),
+        })
 
     await prune(knex)
 }
@@ -267,7 +296,7 @@ async function rowsToSets(knex, rows) {
     const paths = await knex('mikser_change_set_paths')
         .whereIn('change_set', rows.map(row => row.id))
         .orderBy('path')
-        .select('change_set', 'path', 'operation')
+        .select('change_set', 'path', 'operation', 'checksum')
 
     const bySet = new Map()
     for (const row of paths) {
@@ -292,6 +321,10 @@ async function rowsToSets(knex, rows) {
             outcome: row.outcome ?? null,
             paths: mine.map(p => p.path),
             deletions: mine.filter(p => p.operation === 'delete').map(p => p.path),
+            // path -> the checksum of what was written there, for the paths
+            // whose writer knew. Absent means unverifiable, not unchanged.
+            checksums: Object.fromEntries(
+                mine.filter(p => p.checksum).map(p => [p.path, p.checksum])),
         }
     })
 }
@@ -312,6 +345,9 @@ function memorySets(filter = () => true) {
         outcome: set.outcome ?? null,
         paths: [...set.paths.keys()],
         deletions: [...set.paths.entries()].filter(([, op]) => op === 'delete').map(([p]) => p),
+        // Same shape as the durable path, so a consumer reads one contract
+        // whether or not a database is configured.
+        checksums: Object.fromEntries(set.checksums ?? []),
     }))
 }
 
@@ -336,6 +372,11 @@ function relativeToWorkingFolder(uri) {
 // First one wins: later writes in the same set are the same request.
 export function recordChangeSetWrite({
     changeSet, summary, principal, uri, operation = 'write', undoOf, entityId,
+    // The checksum of the bytes just written, when the caller knows them.
+    // Optional on purpose: a writer that does not have the content in hand
+    // records nothing rather than a wrong value, and a consumer reading the
+    // log must treat its absence as "cannot tell".
+    checksum,
 } = {}) {
     // An explicit id always wins; otherwise take whatever set is in effect.
     // A write with neither stays unclaimed, which is the correct outcome for
@@ -373,6 +414,7 @@ export function recordChangeSetWrite({
     if (!set.undoOf && undoOf) set.undoOf = undoOf
     set.updatedAt = Date.now()
     set.paths.set(rel, operation)
+    if (checksum) (set.checksums ??= new Map()).set(rel, checksum)
 
     if (db()) {
         // Snapshotted, because the queued write runs later and the set keeps
@@ -381,7 +423,7 @@ export function recordChangeSetWrite({
         const snapshot = { ...set }
         enqueue(async () => {
             const knex = db()
-            if (knex) await persist(knex, snapshot, rel, operation, entityId)
+            if (knex) await persist(knex, snapshot, rel, operation, entityId, checksum)
         })
     }
     return set.id

package/src/render.js

@@ -544,6 +544,25 @@ export function useRenderer(runtime, { defaultTimeout = 30_000 } = {}) {
      * @returns {Promise<{output, entity}>}
      */
     async function render(entity, { timeout = defaultTimeout, catalog = true, save = true } = {}) {
+        // Was this row already in the catalog BEFORE the render? `catalog:
+        // false` means "do not leave a row behind", and that is only the
+        // render's to decide for a row the render created. Asked here, before
+        // the render puts one there.
+        //
+        // Without it, `catalog: false` deleted whatever it was handed: a
+        // preview of an EXISTING entity pruned the real row, so the entity
+        // vanished from the site while its file sat on disk — no change set,
+        // no cycle, and the removal logged only at debug. It cost a day to
+        // find, in a form that rendered once and then answered "Entity not
+        // found".
+        // Imported HERE, not at the top: catalog.js reaches back into this
+        // module, and a static import makes that cycle load-bearing at
+        // module-evaluation time — it surfaced as "Cannot access 'schemas'
+        // before initialization" in three unrelated test files.
+        const preexisting = catalog === false && entity?.id
+            ? Boolean(await (await import('./catalog.js')).findById(entity.id))
+            : false
+
         const result = await new Promise((resolve, reject) => {
             const correlationId = randomUUID()
             // Engine-set fields live under entity.options. The caller's
@@ -585,7 +604,14 @@ export function useRenderer(runtime, { defaultTimeout = 30_000 } = {}) {
             // and wrong for one that did. `catalog: false, save: true`
             // therefore keeps its row, and says so rather than dropping
             // the output on the floor.
-            if (save === false) {
+            if (preexisting) {
+                // Someone else's row. It was here before this render and is
+                // not this render's to remove.
+                useLogger()?.debug(
+                    'render: catalog:false ignored for %s — the entity was already in the catalog',
+                    result.entity.id,
+                )
+            } else if (save === false) {
                 await runtime.delete(result.entity)
             } else {
                 useLogger()?.warn(

package/src/utils/entity.js

@@ -3,6 +3,7 @@ import path from 'path'
 import runtime from '../runtime.js'
 import yaml from 'yaml'
 
+import { checksumOf } from './hash.js'
 import { isRefKey } from './refs.js'
 import { contentType } from 'mime-types'
 import { minimatch } from 'minimatch'
@@ -449,7 +450,11 @@ 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.
-            runtime.recordChangeSetWrite?.({ uri })
+            // The checksum goes with it, from the bytes just written. Same
+            // reason the recording is here: a consumer asking later whether
+            // its write is still on disk needs to know what it wrote, and the
+            // only place that reliably knows is the write itself.
+            runtime.recordChangeSetWrite?.({ uri, checksum: checksumOf(content) })
             return uri
         },
 

package/src/write.js

@@ -22,7 +22,7 @@ import { readdir, readFile } from 'node:fs/promises'
 
 import runtime from './runtime.js'
 import { readEntity, findEntities } from './catalog.js'
-import { useCollection, checksum, readEntityContent, lookupKeys, validateSource } from './utils/index.js'
+import { useCollection, checksum, checksumOf, readEntityContent, lookupKeys, validateSource } from './utils/index.js'
 import { nextCycleId, whenCycleCompletes } from './report.js'
 import { recordChangeSetWrite, currentChangeSet } from './changeset.js'
 
@@ -275,7 +275,10 @@ export async function writeEntitySource({
     // AFTER the write, so a set only ever claims paths that actually moved.
     // Claiming on intent would make a failed write undoable, and undoing a
     // write that never happened is a way to delete someone else's file.
-    if (changeSet) recordChangeSetWrite({ changeSet, summary, principal, uri })
+    // The checksum of what was just written, so a consumer can tell later
+    // whether what it wrote is still there. See the change-set log's
+    // 002-write-checksums migration.
+    if (changeSet) recordChangeSetWrite({ changeSet, summary, principal, uri, checksum: checksumOf(content) })
 
     const result = {
         ok: true, collection, relativePath,