mikser-io 9.24.0 → 9.25.0

package/docs/diagnostics.md

@@ -54,7 +54,23 @@ rendered    2026-08-22 21:07:52   → /page-a.html   [STALE: input hash moved si
 ```
 
 A snapshot written before per-input recording says so rather than
-guessing. Note that `--explain` compares the CATALOG's entity against the
+guessing.
+
+A destination whose **last render attempt threw** reads as such, rather
+than as current:
+
+```
+rendered    2026-08-22 21:52:24   → /page-a.html   [STALE: last render attempt failed]
+  failed     2026-08-22 21:52:25  The partial partials/btn could not be found
+             3 attempts since 2026-08-22 21:52:24
+  partial    /layouts/partials/btn.hbs  b6ab7ccc  [TARGET DELETED SINCE]
+would re-render — the last render attempt failed and nothing has changed since
+```
+
+`[TARGET DELETED SINCE]` is the same distinction one level down: an edge's
+binding is what it resolved to *when recorded*, so a target deleted
+afterwards still shows an id and a hash and reads as healthy unless the
+catalog is asked. Note that `--explain` compares the CATALOG's entity against the
 snapshot: if you have edited a file and not yet built, the verdict is
 `source differs from the catalog` — the edit has not been imported yet, so
 there is nothing to attribute. Build, then ask.
@@ -117,6 +133,17 @@ means the output moved, and a throw writes nothing. The previous good bytes
 stay on disk, which is what makes a failed render survivable — and also
 what makes it invisible without this bucket.
 
+A failed render is **retried on every subsequent build** until it
+succeeds, reported as `reason: "retry-failed"`. Nothing else would schedule
+it — the entity's own source has not changed, so it is gated at import, and
+the manifest still describes the last good render — so without the retry a
+build after a failing one reported success with the site still stale.
+
+Retries are unbounded and deliberately noisy: a page that fails every cycle
+is failing every cycle. `errors[].since` and `errors[].attempts` are what
+make that readable — "broke just now" and "broken for an hour" are
+different situations. The marker clears itself on the first success.
+
 **A one-shot build with render errors exits `1`.** That is the signal a CI
 gate needs, because `mikser && mikser --verify` would otherwise pass a
 build in which nothing rendered: `--verify` compares the output against the

package/package.json

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

package/src/engine.js

@@ -526,6 +526,9 @@ export async function setup(options) {
                         await updateEntry({ id, output: entry.output, deps: edges })
                     }
 
+                    // A success clears whatever was recorded about this
+                    // destination failing, so the retry set drains itself.
+                    runtime.manifest?.clearFailure(entity)
                     reportRendered(entity, decision.reason, decision)
                     logger.debug('Rendered: [%s] %s → %s', options.renderer, entity.name || entity.id, entity.destination)
                 } catch (err) {
@@ -537,10 +540,24 @@ export async function setup(options) {
                         // it a build that fails every page reports rendered:N,
                         // warnings:0 and exits 0 — three clean signals and only
                         // the human log knowing otherwise.
+                        // Durable, so the next cycle knows to try again and
+                        // --explain stops calling this destination current.
+                        runtime.manifest?.recordFailure(entity, {
+                            error: err.message,
+                            context: context.trim() || null,
+                            at: Date.now(),
+                        })
+                        const failure = runtime.manifest?.failureAt(entity.id, entity.destination)
                         reportError(entity, err, {
                             renderer: options.renderer ?? null,
                             layout: entity.layout?.id ?? null,
                             context: context.trim() || null,
+                            // When it STARTED failing, and how many attempts.
+                            // "broke just now" and "broken since 14:02" are
+                            // different situations and the reader needs to
+                            // tell them apart at a glance.
+                            since: failure?.firstFailedAt ?? null,
+                            attempts: failure?.attempts ?? 1,
                         })
                     }
                     logger.debug('Render canceled')

package/src/explain.js

@@ -10,7 +10,7 @@
 // Follows --verify's shape: report and exit, no build phases run.
 import { inputHashOf, inputPartsOf, diffInputParts, lookupKeys, checksum as fileChecksum } from './utils.js'
 import { filterKey } from './track.js'
-import { findEntity, findEntities } from './catalog.js'
+import { findEntity, findEntities, findById } from './catalog.js'
 import runtime from './runtime.js'
 
 const shortHash = (h) => (h ? String(h).slice(0, 8) : null)
@@ -118,6 +118,11 @@ export async function explain(reference) {
     const currentHash = inputHashOf(entity)
     const currentParts = inputPartsOf(entity)
     const queryMatches = await countQueryMatches(snapshots)
+    // Checked before the hash comparison in the verdict: a destination whose
+    // last attempt threw will re-render regardless of what the hashes say.
+    const failedSnapshots = snapshots
+        .map(snap => runtime.manifest?.failureAt?.(entity.id, snap.destination))
+        .filter(Boolean)
 
     // The catalog is as of the LAST BUILD. If the file has been edited since,
     // nothing here knows it yet — the hashes would all agree and the verdict
@@ -186,6 +191,21 @@ export async function explain(reference) {
             // The single most useful field: does this entity's current hash
             // match what it was last rendered at?
             stale: snap.inputHash !== currentHash,
+            // The last render ATTEMPT for this destination, if it threw.
+            // Without this, a destination whose render is failing reports
+            // `[current]` and `would be SKIPPED` — both true of the recorded
+            // state, and together the wrong answer to the only question
+            // --explain is ever asked.
+            failed: (() => {
+                const f = runtime.manifest?.failureAt?.(entity.id, snap.destination)
+                if (!f) return null
+                return {
+                    error: f.error,
+                    since: when(f.firstFailedAt),
+                    lastAttempt: when(f.lastFailedAt),
+                    attempts: f.attempts ?? 1,
+                }
+            })(),
             // WHICH input moved, not merely that one did. This is the whole
             // question behind "why did this re-render" — answering it from
             // the recorded parts costs nothing, and not answering it sends
@@ -220,6 +240,14 @@ export async function explain(reference) {
                         bound: entry.targetIds?.length ? entry.targetIds
                             : entry.targetId ? [entry.targetId]
                             : [],
+                        // `bound` is what the edge resolved to WHEN RECORDED.
+                        // A target deleted since then still shows an id and a
+                        // hash, which reads as healthy — so check the catalog
+                        // rather than describing the record as if it were
+                        // current.
+                        gone: (entry.targetIds?.length ? entry.targetIds
+                            : entry.targetId ? [entry.targetId]
+                            : []).filter(id => !findById(id)),
                         hash: shortHash(entry.hash),
                     }),
         })),
@@ -231,6 +259,9 @@ export async function explain(reference) {
                   + '(Some plugins compose a checksum from several files, so verify before concluding.)'
                 : snapshots.length === 0
             ? 'never rendered — no manifest snapshot. Either it has no layout, or its layout produced no destination.'
+            : failedSnapshots.length
+                ? `would re-render — the last render attempt failed and nothing has changed since `
+                  + `(${failedSnapshots[0].error})`
             : snapshots.some(s => s.inputHash !== currentHash)
                 ? renderVerdict(snapshots, currentHash, currentParts)
                 : 'would be SKIPPED — input hash unchanged. A dependency in refClosure changing is the only other thing that would re-render it.',
@@ -285,7 +316,15 @@ export function formatExplain(report) {
     }
     for (const r of report.renders) {
         row('rendered', `${r.renderedAt ?? 'unknown'}   → ${r.destination}`
-            + (r.stale ? '   [STALE: input hash moved since]' : '   [current]'))
+            + (r.failed ? '   [STALE: last render attempt failed]'
+                : r.stale ? '   [STALE: input hash moved since]'
+                : '   [current]'))
+        if (r.failed) {
+            out.push(`  failed     ${r.failed.lastAttempt}  ${r.failed.error}`)
+            if (r.failed.attempts > 1) {
+                out.push(`             ${r.failed.attempts} attempts since ${r.failed.since}`)
+            }
+        }
         const closure = r.refClosure
         row('refClosure', `${closure.length} edge${closure.length === 1 ? '' : 's'}`)
         for (const e of closure) {
@@ -308,7 +347,8 @@ export function formatExplain(report) {
             const bound = e.bound?.length
                 ? (e.bound.length === 1 && e.bound[0] === e.target ? '' : ` → ${e.bound.join(', ')}`)
                 : '  [UNRESOLVED — nothing answers to this name]'
-            out.push(`  ${e.kind.padEnd(10)} ${e.target}${bound}${e.hash ? `  ${e.hash}` : ''}`)
+            const gone = e.gone?.length ? '  [TARGET DELETED SINCE]' : ''
+            out.push(`  ${e.kind.padEnd(10)} ${e.target}${bound}${e.hash ? `  ${e.hash}` : ''}${gone}`)
         }
     }
 

package/src/manifest.js

@@ -85,6 +85,38 @@ export const SNAPSHOTS_SCHEMA = `
 `
 registerSchema('mikser_snapshots', SNAPSHOTS_SCHEMA)
 
+// Failed render attempts, durably.
+//
+// A failed render writes no snapshot — deliberately, so the last good bytes
+// survive — which leaves nothing anywhere saying the attempt happened. The
+// consequences all follow from that one absence: the entity is gated at
+// import next cycle (its own source did not change), so it is never
+// re-dispatched; the manifest still describes the last good render, so
+// --verify is clean; and --explain reports `[current]` and `would be
+// SKIPPED` for a page whose render is throwing — the one tool whose job is
+// "why is this not rebuilding", answering "because there is nothing to do".
+//
+// Keyed by (id, destination) like snapshots, but a SEPARATE table because a
+// render that has never once succeeded has no snapshot to hang a column on.
+//
+// firstFailedAt is kept distinct from lastFailedAt so a report can say
+// "since 14:02" — the difference between "this broke just now" and "this has
+// been broken for an hour" is most of what a reader wants.
+export const FAILURES_SCHEMA = `
+    CREATE TABLE IF NOT EXISTS mikser_failures (
+        id            TEXT NOT NULL,
+        destination   TEXT NOT NULL,
+        error         TEXT,
+        context       TEXT,
+        firstFailedAt INTEGER,
+        lastFailedAt  INTEGER,
+        attempts      INTEGER NOT NULL DEFAULT 1,
+        PRIMARY KEY (id, destination)
+    ) WITHOUT ROWID;
+    CREATE INDEX IF NOT EXISTS idx_mikser_failures_id ON mikser_failures(id);
+`
+registerSchema('mikser_failures', FAILURES_SCHEMA)
+
 // Module-level DB handle + prepared statements for the lifecycle
 // integration. Tests build their own via `createManifest(db)` —
 // the lifecycle hook below grabs useDatabase() and stashes the
@@ -252,6 +284,32 @@ async function hashOutputFile(destination) {
 export function createManifest(db) {
     if (!db) throw new Error('createManifest: db is required')
 
+    const stmtRecordFailure = db.prepare(`
+        INSERT INTO mikser_failures
+            (id, destination, error, context, firstFailedAt, lastFailedAt, attempts)
+        VALUES (@id, @destination, @error, @context, @at, @at, 1)
+        ON CONFLICT(id, destination) DO UPDATE SET
+            error = excluded.error,
+            context = excluded.context,
+            lastFailedAt = excluded.lastFailedAt,
+            attempts = mikser_failures.attempts + 1
+    `)
+    const stmtClearFailure = db.prepare(`
+        DELETE FROM mikser_failures WHERE id = ? AND destination = ?
+    `)
+    const stmtFailuresFor = db.prepare(`
+        SELECT id, destination, error, context, firstFailedAt, lastFailedAt, attempts
+        FROM mikser_failures WHERE id = ?
+    `)
+    const stmtFailureAt = db.prepare(`
+        SELECT id, destination, error, context, firstFailedAt, lastFailedAt, attempts
+        FROM mikser_failures WHERE id = ? AND destination = ?
+    `)
+    const stmtAllFailures = db.prepare(`
+        SELECT id, destination, error, context, firstFailedAt, lastFailedAt, attempts
+        FROM mikser_failures
+    `)
+
     const stmtLookupById = db.prepare(`
         SELECT id, destination, inputHash, inputParts, outputHash, refClosure, renderedAt, parent
         FROM mikser_snapshots WHERE id = ? ORDER BY destination
@@ -359,6 +417,8 @@ export function createManifest(db) {
         //   query-matched    an entity matching a recorded query mutated
         //   cache-disabled   meta.cache === false
         //   force            --force: skip nothing, ask nothing
+        //   retry-failed     the last render attempt for this destination
+        //                    threw; nothing else would reschedule it
         skipDecision(entity, mutatedRefs, currentHashes, mutatedEntities) {
             // --force means "ignore what you think you know". THREE gates
             // can stop a render — source.js's import checksum gate,
@@ -373,6 +433,31 @@ export function createManifest(db) {
             // no-match warning tells the operator to use it.
             if (runtime.options?.force) return { skip: false, reason: 'force' }
             if (entity?.meta?.cache === false) return { skip: false, reason: 'cache-disabled' }
+            // A render whose last attempt threw must be retried, and checked
+            // before anything else: every other branch reasons about hashes,
+            // and the hashes are consistent — the entity did not change, the
+            // snapshot still describes the last GOOD render. Consistency is
+            // exactly why the failure is invisible without this.
+            //
+            // Retried unbounded, and noisily. A page that fails every cycle IS
+            // failing every cycle, and a build that stops mentioning it after
+            // the third attempt is making the same trade as reporting
+            // `rendered: 12, exit 0`. What makes it tolerable is presentation
+            // — one line per failing entity, and `since` on the report so a
+            // reader can tell "broke just now" from "broken since 14:02" —
+            // not backoff.
+            const failure = this.failureAt(entity?.id, entity?.destination)
+            if (failure) {
+                return {
+                    skip: false,
+                    reason: 'retry-failed',
+                    failure: {
+                        error: failure.error,
+                        since: failure.firstFailedAt ?? null,
+                        attempts: failure.attempts ?? 1,
+                    },
+                }
+            }
             const snapshot = this.lookup(entity)
             if (!snapshot?.inputHash) return { skip: false, reason: 'never-rendered' }
             if (inputHashOf(entity) !== snapshot.inputHash) {
@@ -483,6 +568,51 @@ export function createManifest(db) {
             return { skip: true, reason: 'unchanged' }
         },
 
+        // Record that a render attempt threw. `at` is passed in rather than
+        // read from the clock here so the caller owns the timestamp.
+        recordFailure(entity, { error, context, at }) {
+            if (!entity?.id || !entity?.destination) return
+            stmtRecordFailure.run({
+                id: entity.id,
+                destination: entity.destination,
+                error: error ?? null,
+                context: context ?? null,
+                at: at ?? Date.now(),
+            })
+        },
+
+        // A render succeeded, so whatever was recorded about it failing is
+        // no longer true. Called on every success, not only after a failure —
+        // it is a cheap DELETE and forgetting it would strand the marker.
+        clearFailure(entity) {
+            if (!entity?.id || !entity?.destination) return
+            stmtClearFailure.run(entity.id, entity.destination)
+        },
+
+        // Every recorded failure for an entity, across destinations.
+        failuresFor(id) {
+            return id ? stmtFailuresFor.all(id) : []
+        },
+
+        // One, at a known destination.
+        failureAt(id, destination) {
+            if (!id || !destination) return null
+            return stmtFailureAt.get(id, destination) ?? null
+        },
+
+        // Every entity id with a recorded failure. The dispatch set a
+        // task-production plugin unions in so a failed render is retried:
+        // the entity's own source has not changed, so nothing else will
+        // schedule it, and going quiet about a page that will not build is
+        // the failure mode this whole area exists to avoid.
+        failedIds() {
+            return [...new Set(stmtAllFailures.all().map(row => row.id))]
+        },
+
+        allFailures() {
+            return stmtAllFailures.all()
+        },
+
         // Record a successful render. Single INSERT OR REPLACE.
         record(entity, deps) {
             stmtUpsert.run(snapToRow(buildSnapshot(entity, deps)))