mikser-io 11.10.3 → 11.10.5

package/package.json

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

package/src/invalidation.js

@@ -52,6 +52,12 @@ export const REASON = Object.freeze({
     RELOAD: 'reload',
     REBUILD_INTERRUPTED: 'rebuild-interrupted',
     OUTPUT_MISSING: 'output-missing',
+    // A catalog entity with a layout that has no snapshot at all — distinct
+    // from NEVER_RENDERED below, which is a gate reporting what it found. This
+    // one is an OVERRIDE: nothing would otherwise look at such an entity,
+    // because every other mechanism starts from a snapshot. Claimed once per
+    // entity per process; see claimUnrendered.
+    NEVER_RECORDED: 'never-recorded',
     // Evidence — each layer's business, named here so the vocabulary is
     // legible as a whole.
     UNCHANGED: 'unchanged',
@@ -117,6 +123,49 @@ export function missingOutputIds() {
 
 export function forgetMissingOutputs() {
     cachedMissingOutputs = null
+    // `unrenderedOnce` is NOT dropped here. It is per PROCESS, not per cycle:
+    // clearing it would recompute the set every cycle and hand back the same
+    // un-renderable entity every time, which is the churn the claim-once rule
+    // exists to prevent.
+}
+
+// Entities with a layout that have never recorded a snapshot.
+//
+// The gap `missingOutputIds` cannot see: it walks SNAPSHOTS, so an entity
+// that never got one is invisible to it, and nothing else looks either — the
+// source gate sees the file unchanged and never journals it again. That is
+// the state a superseded DELETE left behind, and the reason it was permanent:
+// a missing page, green builds forever, and only --audit-output to say so.
+//
+// ONE DISPATCH PER ENTITY, per process, which is the whole safety of it.
+// Membership is CLAIMED rather than read: an id comes out once and is then
+// gone from the set. An entity that legitimately cannot render — a layout
+// that produces no destination is the real case, and `mikser_explain` names
+// it — therefore costs one wasted dispatch rather than one per cycle for the
+// life of the process. Re-dispatching such an entity forever is the failure
+// this net could otherwise become, and it would be quiet: slower builds and
+// nothing to point at.
+//
+// Computed lazily and only once, then dropped alongside the missing-output
+// cache at the end of onFinalize.
+let unrenderedOnce = null
+
+export function claimUnrendered(id) {
+    if (id === undefined) return false
+    if (!unrenderedOnce) {
+        // Nothing has ever rendered, so nothing is missing: this is a cold
+        // build and every entity is about to be dispatched on its own merits.
+        // Without this the whole corpus answers `never-recorded` on a first
+        // build — true, useless, and it would take the real reason off every
+        // page in `--json`.
+        const recorded = runtime.manifest?.size?.() ?? 0
+        unrenderedOnce = recorded > 0
+            ? new Set(runtime.manifest?.unrenderedIds?.() ?? [])
+            : new Set()
+    }
+    if (!unrenderedOnce.has(id)) return false
+    unrenderedOnce.delete(id)
+    return true
 }
 
 // What overrides a gate's own evidence, or null when nothing does.
@@ -138,6 +187,10 @@ export function bypassReason({ reload = false, id } = {}) {
     // this module exists, and this is the first override added since.
     if (runtime.options?.cacheRebuildInterrupted) return REASON.REBUILD_INTERRUPTED
     if (id !== undefined && missingOutputIds().has(id)) return REASON.OUTPUT_MISSING
+    // Last, and after OUTPUT_MISSING on purpose: an entity with a snapshot
+    // whose file went missing is the better-understood case and keeps its own
+    // reason, which `--json` callers and the scenario suite already match on.
+    if (claimUnrendered(id)) return REASON.NEVER_RECORDED
     return null
 }
 

package/src/manifest/cycle.js

@@ -53,8 +53,47 @@ onFinalize(async () => {
     const newDestinationsByParent = new Map()
     const lostPagination = new Set()
 
-    for await (const { entity } of useJournal('Manifest cleanup', [OPERATION.DELETE])) {
-        deletedIds.push(entity.id)
+    // A DELETE only counts if nothing re-created the entity after it.
+    //
+    // Collected with no regard for supersession, this unlinked a page that
+    // had just been written. A file created, deleted and re-created AT THE
+    // SAME PATH while one cycle was held open leaves that cycle holding
+    // CREATE, DELETE and CREATE for one id — and since 11.10.2 a cancelled
+    // cycle's entries are carried rather than dropped, which is what lets
+    // the stale DELETE reach the cycle that finally renders the entity. That
+    // fix is right; this is the other end of it.
+    //
+    // The staging below and the `claimedByThisCycle` guard were both written
+    // for the RENAME case, where the DELETE carries the OLD id and the RENDER
+    // a NEW one. There the new destination is correctly protected. When the
+    // id is the SAME, the guard skipped the very destination just written,
+    // `stillClaimed` was empty because a first render has no snapshot row
+    // yet, and the unlink ran: an empty output directory, no snapshot, no
+    // failure, `Rendered: 1` and a green build. Nothing recovered it — the
+    // source gate saw the file unchanged, and missingOutputIds() iterates
+    // SNAPSHOTS, so an entity that never got one is invisible to it.
+    //
+    // ORDER, not catalog presence. Catalog presence gives the same answers
+    // today, but only because catalog.js's finalize drain happens to be
+    // registered before this one (index.js exports catalog.js first), so the
+    // row is already gone when cleanup reads it. That is an invisible
+    // coupling: reordering two exports would silently restore this bug. The
+    // journal knows the answer on its own, and mikser-io-layouts already
+    // reconciles the same journal by order when it seeds dispatch.
+    const lastDelete = new Map()
+    const lastWrite = new Map()
+    for await (const { id: seq, operation, entity } of useJournal(
+        'Manifest cleanup', [OPERATION.DELETE, OPERATION.CREATE, OPERATION.UPDATE])) {
+        if (!entity?.id) continue
+        const seen = operation === OPERATION.DELETE ? lastDelete : lastWrite
+        const prior = seen.get(entity.id)
+        if (prior === undefined || seq > prior) seen.set(entity.id, seq)
+    }
+    for (const [id, seq] of lastDelete) {
+        // `>` and not `>=`: a render that opts out of the catalog journals its
+        // DELETE after the entity's own CREATE, so the DELETE is genuinely
+        // later and must win — the rule 2e documents.
+        if (seq > (lastWrite.get(id) ?? -1)) deletedIds.push(id)
     }
 
     // Every destination claimed by a render task this cycle — whether it

package/src/manifest/index.js

@@ -65,6 +65,10 @@ import { sha1, describeInputChange, buildRefClosure, buildSnapshot, rowToSnap, s
 
 
 export function createManifest(db) {
+    // See unrenderedIds(): prepared on first use, because it is the one
+    // statement that reaches outside the manifest's own tables.
+    let stmtUnrendered
+
     const {
         stmtCollisions,
         stmtClaimants,
@@ -504,6 +508,49 @@ export function createManifest(db) {
             return [...new Set(stmtAllFailures.all().map(row => row.id))]
         },
 
+        // Catalog entities that should have rendered and never did.
+        //
+        // The state a superseded DELETE used to leave behind: a catalog row
+        // with a layout, an output written and then unlinked, and NO snapshot
+        // — which made it invisible to missingOutputIds(), because that walks
+        // snapshots. The source gate saw the file unchanged, so nothing
+        // journalled it again either. Permanently missing page, green builds
+        // forever, and only --audit-output to say so.
+        //
+        // Both exclusions are load-bearing:
+        //   - a snapshot means it HAS rendered, so there is nothing to
+        //     recover;
+        //   - a failure means the render was attempted and threw. A failed
+        //     render writes no snapshot ON PURPOSE, so the last good bytes
+        //     survive, and the retry path owns that case. Re-dispatching it
+        //     here would fight the mechanism that exists for it.
+        //
+        // `meta_layout` is the column the layouts plugin mirrors its match
+        // into and carries a partial index, so this is an index scan that
+        // finds nothing in a healthy build.
+        //
+        // PREPARED LAZILY, and that is not a style choice: this is the only
+        // statement here that reaches outside the manifest's own tables, and
+        // a manifest is legitimately built against a database that holds no
+        // catalog — the unit suite does exactly that. Preparing it eagerly
+        // threw SQLITE_ERROR at construction and took twenty-one unrelated
+        // tests with it.
+        unrenderedIds() {
+            if (stmtUnrendered === undefined) {
+                try {
+                    stmtUnrendered = db.prepare(`
+                        SELECT e.id FROM mikser_entities e
+                        LEFT JOIN mikser_snapshots s ON s.id = e.id
+                        LEFT JOIN mikser_failures  f ON f.id = e.id
+                        WHERE e.meta_layout IS NOT NULL AND s.id IS NULL AND f.id IS NULL
+                    `)
+                } catch {
+                    stmtUnrendered = null      // no catalog here; nothing to recover
+                }
+            }
+            return stmtUnrendered ? stmtUnrendered.all().map(row => row.id) : []
+        },
+
         allFailures() {
             return stmtAllFailures.all()
         },