mikser-io 9.15.1 → 9.18.0

package/package.json

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

package/src/catalog.js

@@ -207,16 +207,19 @@ async function applyJournalMutations() {
     }
     if (!mutations.length) return
     db.transaction(() => {
+        // Two passes, deliberately. indexEntity resolves each $-ref
+        // against mikser_entities to record what it bound to, so it has
+        // to run after every row this cycle is in place — otherwise a
+        // ref to an entity that happens to be upserted later in the same
+        // batch binds to nothing, purely because of journal order.
+        const toIndex = []
         for (const { operation, entity } of mutations) {
             switch (operation) {
                 case OPERATION.CREATE:
                 case OPERATION.UPDATE:
                     logger.trace('Database %s %s: %s', entity.collection, operation, entity.id)
                     stmtUpsert.run(entityToRow(entity))
-                    // Static $-ref edges from entity.meta. Refs index
-                    // does delete-then-insert internally so this is
-                    // idempotent across UPDATE.
-                    refsIndex?.indexEntity(entity)
+                    toIndex.push(entity)
                     cacheEvict(entity.id)   // next read returns fresh data
                     break
                 case OPERATION.DELETE:
@@ -227,6 +230,10 @@ async function applyJournalMutations() {
                     break
             }
         }
+        // Static $-ref edges from entity.meta. Refs index does
+        // delete-then-insert per source internally, so this stays
+        // idempotent across UPDATE.
+        for (const entity of toIndex) refsIndex?.indexEntity(entity)
     })
 }
 

package/src/config.js

@@ -3,6 +3,7 @@ import { useLogger } from './engine.js'
 import { onLoad } from './lifecycle.js'
 import { checksum } from './utils.js'
 import path from 'node:path'
+import { existsSync } from 'node:fs'
 
 onLoad(async () => {
     const logger = useLogger()
@@ -29,15 +30,31 @@ onLoad(async () => {
         runtime.options.configChecksum = null
     }
 
-    try {
+    // Absence is decided by looking for the file, NOT by catching
+    // ERR_MODULE_NOT_FOUND from the import.
+    //
+    // Node raises that same code for "the config file is missing" and for
+    // "the config file exists and something IT imports is missing" — a
+    // mistyped package name, a renamed local module, a dependency that
+    // was never installed. Catching the code swallowed both, so a config
+    // with one bad import loaded as `{}` and the build reported "No
+    // plugins loaded" and exited 0: a green build with an empty output
+    // folder, one line away from having printed the config's path.
+    //
+    // Every other config failure was already loud — a syntax error or a
+    // throw during evaluation both exit 1. Module resolution was the one
+    // silent case, so this brings it in line rather than inventing a new
+    // policy.
+    if (!existsSync(configFile)) {
+        logger.debug('No config file at %s — using defaults', configFile)
+    } else {
+        // No catch: any failure loading a config that EXISTS is fatal.
         const config = await import(configFile)
         if (typeof config.default == 'function') {
             runtime.config = await config.default(runtime)
         } else if (typeof config.default == 'object') {
             runtime.config = config.default
         }
-    } catch (err) {
-        if (err.code != 'ERR_MODULE_NOT_FOUND') throw err
     }
 
     // v8 used to walk `runtime.config.plugins` looking for matching

package/src/explain.js

@@ -114,7 +114,18 @@ export async function explain(reference) {
             refClosure: (snap.refClosure ?? []).map(entry =>
                 entry.kind === 'query'
                     ? { kind: 'query', filter: entry.filter }
-                    : { kind: entry.kind, target: entry.target, hash: shortHash(entry.hash) }),
+                    : {
+                        kind: entry.kind,
+                        target: entry.target,
+                        // What the name actually resolved to. A binding
+                        // that is absent means the edge is dangling —
+                        // the single most useful thing to know when a
+                        // page will not re-render and nobody can say why.
+                        bound: entry.targetIds?.length ? entry.targetIds
+                            : entry.targetId ? [entry.targetId]
+                            : [],
+                        hash: shortHash(entry.hash),
+                    }),
         })),
         // What a plain build would do next, stated plainly.
         verdict: source?.error === 'file is gone'
@@ -182,9 +193,17 @@ export function formatExplain(report) {
         const closure = r.refClosure
         row('refClosure', `${closure.length} edge${closure.length === 1 ? '' : 's'}`)
         for (const e of closure) {
-            out.push(e.kind === 'query'
-                ? `  query      ${JSON.stringify(e.filter)}`
-                : `  ${e.kind.padEnd(10)} ${e.target}${e.hash ? `  ${e.hash}` : ''}`)
+            if (e.kind === 'query') {
+                out.push(`  query      ${JSON.stringify(e.filter)}`)
+                continue
+            }
+            // Show the name asked for and the entity it bound to, since
+            // the two can differ (an href or a served path resolves to
+            // an id) and a missing binding is itself the diagnosis.
+            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}` : ''}`)
         }
     }
 

package/src/manifest.js

@@ -96,12 +96,20 @@ function sha1(payload) {
 function buildRefClosure(entity, deps) {
     const closure = []
     const seen = new Set()
-    function pushTarget(kind, target, hash) {
+    // `targetId`/`targetIds` are the recorded BINDING — which entity the
+    // ref actually resolved to. They have to survive into the snapshot:
+    // this projection used to keep only {kind, target, hash}, so the
+    // binding was written to mikser_refs, dropped here, and skipDecision
+    // had nothing but the name to compare. The scheduler found the
+    // dependent and the manifest then skipped it.
+    function pushTarget(kind, target, hash, targetId, targetIds) {
         if (!target) return
         const key = `${kind}:${target}`
         if (seen.has(key)) return
         seen.add(key)
         const entry = { kind, target }
+        if (targetId) entry.targetId = targetId
+        if (targetIds?.length) entry.targetIds = targetIds
         if (hash) entry.hash = hash
         closure.push(entry)
     }
@@ -113,14 +121,26 @@ function buildRefClosure(entity, deps) {
     }
     if (entity.meta) {
         for (const { ref } of extractRefs(entity.meta)) {
-            const target = findById(ref)
-            pushTarget('ref', ref, target ? inputHashOf(target) : undefined)
+            // Resolve through the refs index, which mirrors refFilter's
+            // four forms. findById alone — as this used to do — is an
+            // exact primary-key read: a $-ref written as a meta.href or
+            // a served meta.url path (ADR-0011) resolved to nothing, so
+            // the edge was stored with no hash and no binding, and the
+            // manifest could not tell the target had changed.
+            const ids = runtime.refs?.resolveRefIds?.(ref) ?? (findById(ref) ? [ref] : [])
+            const bound = ids.length === 1 ? findById(ids[0]) : null
+            pushTarget(
+                'ref', ref,
+                bound ? inputHashOf(bound) : undefined,
+                ids.length === 1 ? ids[0] : undefined,
+                ids.length > 1 ? ids : undefined,
+            )
         }
     }
     if (Array.isArray(deps)) {
         for (const dep of deps) {
             if (dep.kind === 'query') pushQuery(dep.filter ?? null)
-            else pushTarget(dep.kind, dep.target, dep.hash)
+            else pushTarget(dep.kind, dep.target, dep.hash, dep.targetId, dep.targetIds)
         }
     }
     return closure
@@ -286,7 +306,20 @@ export function createManifest(db) {
         //   ref-changed      a $-ref or partial it depends on moved
         //   query-matched    an entity matching a recorded query mutated
         //   cache-disabled   meta.cache === false
+        //   force            --force: skip nothing, ask nothing
         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, layouts'
+            // dispatch filter, and this one — and force reached only the
+            // first two. Since this one runs last, a forced build re-imported
+            // everything (gated=0), re-dispatched everything, and then
+            // dropped all of it here with reason `unchanged`: rendered=0, and
+            // a summary that read like a successful build.
+            //
+            // That made --force useless in exactly the situation it exists
+            // for, which is when the invalidation graph is under suspicion —
+            // including the advice the preset no-match warning gives.
+            if (runtime.options?.force) return { skip: false, reason: 'force' }
             if (entity?.meta?.cache === false) return { skip: false, reason: 'cache-disabled' }
             const snapshot = this.lookup(entity)
             if (!snapshot?.inputHash) return { skip: false, reason: 'never-rendered' }
@@ -303,26 +336,48 @@ export function createManifest(db) {
                     }
                     continue
                 }
-                if (!mutatedRefs?.has(entry.target)) continue
-                // Language scope: if the source has a meta.lang AND the
-                // mutation came from a different meta.lang, the ref
-                // doesn't actually depend on what changed. A `null` lang
-                // in the mutation set means a shared (un-localized)
-                // entity touched the same key — that does invalidate
-                // language-specific sources because the shared entity
-                // is the only variant. Sources without a meta.lang are
-                // language-agnostic and accept any mutation lang.
-                if (sourceLang) {
-                    const mutatedLangs = mutatedRefs.get(entry.target)
-                    if (mutatedLangs && !mutatedLangs.has(sourceLang) && !mutatedLangs.has(null)) {
-                        continue
+                // An edge is checked against every key it could have been
+                // hit by: the entity it BOUND to, and the name it asked
+                // for. entity.id is always lookupKeys()[0], so the engine's
+                // mutation maps are already keyed by id — reading them by
+                // targetId needs no change there, and a binding survives
+                // the target renaming itself.
+                //
+                // Both, not the first match, because the two can disagree:
+                // the bound entity may have been re-persisted unchanged in
+                // the same cycle that a DIFFERENT entity started answering
+                // to the same name. Stopping at the binding would compare
+                // an unchanged hash and skip, silently ignoring the new
+                // claimant. The name key also carries unresolved/forward
+                // edges, which is how a link to a not-yet-existing page
+                // invalidates once that page appears.
+                const keys = [
+                    ...(entry.targetIds ?? []),
+                    ...(entry.targetId ? [entry.targetId] : []),
+                    entry.target,
+                ]
+                for (const key of keys) {
+                    if (!mutatedRefs?.has(key)) continue
+                    // Language scope: if the source has a meta.lang AND the
+                    // mutation came from a different meta.lang, the ref
+                    // doesn't actually depend on what changed. A `null` lang
+                    // in the mutation set means a shared (un-localized)
+                    // entity touched the same key — that does invalidate
+                    // language-specific sources because the shared entity
+                    // is the only variant. Sources without a meta.lang are
+                    // language-agnostic and accept any mutation lang.
+                    if (sourceLang) {
+                        const mutatedLangs = mutatedRefs.get(key)
+                        if (mutatedLangs && !mutatedLangs.has(sourceLang) && !mutatedLangs.has(null)) {
+                            continue
+                        }
                     }
+                    if (!entry.hash) return { skip: false, reason: 'ref-changed' }
+                    const currentHash = currentHashes?.get(key)
+                    if (currentHash === undefined) continue
+                    if (currentHash === null) return { skip: false, reason: 'ref-changed' }
+                    if (currentHash !== entry.hash) return { skip: false, reason: 'ref-changed' }
                 }
-                if (!entry.hash) return { skip: false, reason: 'ref-changed' }
-                const currentHash = currentHashes?.get(entry.target)
-                if (currentHash === undefined) continue
-                if (currentHash === null) return { skip: false, reason: 'ref-changed' }
-                if (currentHash !== entry.hash) return { skip: false, reason: 'ref-changed' }
             }
             return { skip: true, reason: 'unchanged' }
         },
@@ -427,6 +482,7 @@ export function createManifest(db) {
                 edges.push({
                     kind: 'layout',
                     target: entity.layout.id,
+                    targetId: entity.layout.id,
                     hash: inputHashOf(entity.layout),
                 })
             }
@@ -436,23 +492,35 @@ export function createManifest(db) {
                     edges.push({
                         kind: 'partial',
                         target,
+                        targetId: partial ? target : undefined,
                         hash: partial ? inputHashOf(partial) : undefined,
                     })
                 }
             }
             if (track?.lookups) {
-                for (const target of track.lookups) {
-                    // findById is extension-tolerant and also resolves a
-                    // meta.href, so the hash is the resolved entity's when
-                    // there is one. No hash means "nothing resolved" —
-                    // shouldSkip treats a hashless edge whose target mutated
-                    // as a re-render, which is what should happen when a page
+                for (const [target, ids] of track.lookups) {
+                    // The lookup helper resolved this already and handed
+                    // over the ids, so the hash comes from the BOUND
+                    // entity. Hashing findById(target) instead — as this
+                    // did — silently produced no hash at all whenever the
+                    // target was an href or url form, because findById is
+                    // an exact primary-key read: it resolves neither
+                    // meta.href nor meta.url nor a stripped extension.
+                    // Every such edge was hashless, so the manifest could
+                    // not tell "target moved" from "target changed".
+                    //
+                    // No hash still means "nothing resolved", and
+                    // skipDecision re-renders a hashless edge whose target
+                    // mutated — which is what should happen when a page
                     // that was linked-to-but-missing finally appears.
-                    const resolved = findById(target)
+                    const targetIds = [...ids]
+                    const bound = targetIds.length === 1 ? findById(targetIds[0]) : null
                     edges.push({
                         kind: 'lookup',
                         target,
-                        hash: resolved ? inputHashOf(resolved) : undefined,
+                        targetId: targetIds.length === 1 ? targetIds[0] : undefined,
+                        targetIds: targetIds.length > 1 ? targetIds : undefined,
+                        hash: bound ? inputHashOf(bound) : undefined,
                     })
                 }
             }

package/src/plugins/files.js

@@ -86,25 +86,41 @@ export function files(options = {}) {
                         link: await link(source)
                     })
                     break
-                case ACTION.UPDATE:
+                case ACTION.UPDATE: {
                     const current = await findEntity({ id })
-                    if (current?.checksum != checksum) {
+                    // `checksum` is the source-checksum FUNCTION from the
+                    // plugin context, not a value. Comparing the stored
+                    // string against it was never equal, so the guard
+                    // always passed and every sync re-wrote the entity —
+                    // `synced = false` was unreachable.
+                    const currentChecksum = await checksum(source)
+                    if (current?.checksum != currentChecksum) {
                         await updateEntity({
                             id,
                             uri,
-                            name: relativePath,
+                            // `name` — the prefixed form, as CREATE uses.
+                            // This read `relativePath`, so an update
+                            // dropped the outputFolder prefix while
+                            // meta.url two lines down kept it. The assets
+                            // plugin builds preset destinations from
+                            // `name`, so a file replaced under watch had
+                            // its derivatives written somewhere else than
+                            // the same file freshly imported, and
+                            // meta.presets recorded the wrong path.
+                            name,
                             collection,
                             type,
                             format,
                             source,
                             meta: { url: '/' + name },
-                            checksum: await checksum(source),
+                            checksum: currentChecksum,
                             link: await link(source)
                         })
                     } else {
                         synced = false
                     }
                     break
+                }
                 case ACTION.DELETE:
                     await removeLink(relativePath)
                     await deleteEntity({
@@ -143,6 +159,13 @@ export function files(options = {}) {
             // journal with phantom mutations and triggering downstream
             // re-dispatch of aggregate layouts whose recorded query deps
             // matched the collection.
+            // --force (and a wiped catalog) must defeat the gate, the same
+            // way source.js's gateChecksum lets them defeat its own. This
+            // plugin carries a second, independent gate, and it honoured
+            // neither — so no amount of forcing ever re-derived a file's
+            // name / meta.url / meta.presets, and a catalog holding bad
+            // `files` rows had no repair path short of deleting them.
+            const forced = runtime.options.force || runtime.catalog?.cacheInvalidated
             const priorChecksums = checksumsByCollection(collection)
             await pMap(paths, async relativePath => {
                 const { uri, source } = await ensureLink(relativePath)
@@ -159,7 +182,7 @@ export function files(options = {}) {
                 // the journal stays accurate (mutations = actual changes),
                 // and downstream aggregate-layout invalidation isn't fired
                 // spuriously.
-                if (priorChecksums.get(id) === newChecksum) return
+                if (!forced && priorChecksums.get(id) === newChecksum) return
                 await createEntity({
                     id,
                     uri,

package/src/plugins.js

@@ -87,7 +87,21 @@ onLoad(() => {
     }
 
     if (!factoryEntries.length && !registeredRenderers && !registeredPostprocessors) {
-        logger.info('No plugins loaded')
+        // "No plugins loaded" is a legitimate state for a project with no
+        // config at all, and a near-certain mistake for one that HAS a
+        // config — the two printed the same line, so a config that
+        // produced no plugins looked like a deliberate choice. Say which
+        // case this is.
+        if (runtime.options.configChecksum) {
+            logger.warn(
+                'No plugins loaded, but a config was read from %s — ' +
+                'it exported no `plugins` array, or the array was empty. ' +
+                'Nothing will be built.',
+                runtime.options.config,
+            )
+        } else {
+            logger.info('No plugins loaded')
+        }
         return
     }
 

package/src/refs.js

@@ -14,7 +14,26 @@
 //                               the engine after each successful render
 //                               via the track API. field = '' (empty).
 //
-// Lookups are indexed SELECTs over (target_ref, kind) and (source_id):
+// Every row carries BOTH the question and the answer:
+//
+//   target_ref  — the string the dependent asked for. May be an id, a
+//                 meta.href, a meta.url (ADR-0011 served path), or an
+//                 id with its extension stripped.
+//   target_id   — the entity it actually resolved to, '' when nothing
+//                 did. NOT NULL because WITHOUT ROWID requires it of
+//                 primary-key columns, and it is in the key so one
+//                 dependent can bind one name to several entities
+//                 (language variants).
+//
+// Both are load-bearing. Answering "who depends on X?" from target_ref
+// alone means guessing which strings X could have answered to, which
+// fails the moment X changes its name — the recorded string is then
+// derivable from no live state. target_id alone cannot express a
+// forward or dangling reference, nor re-bind when an entity later
+// claims a name nobody could resolve before.
+//
+// Lookups are indexed SELECTs over (target_ref, kind), (target_id) and
+// (source_id):
 //
 //   inbound  :: "Which entities reference this target_ref?"
 //   outbound :: "Which target_refs does this source emit?"
@@ -47,17 +66,25 @@ import { registerSchema, useDatabase } from './database/index.js'
 // who references X). The primary key's leading source_id column
 // already covers forward (everything X references) without a
 // separate index.
-registerSchema('mikser_refs', `
+//
+// Exported so tests build their index over the REAL schema instead of a
+// hand-copied one. The copy in test/unit/refs.test.js silently drifted
+// out of date the moment target_id was added — 25 tests failed with a
+// bare SQLITE_ERROR pointing at nothing in particular.
+export const REFS_SCHEMA = `
     CREATE TABLE IF NOT EXISTS mikser_refs (
         source_id   TEXT NOT NULL,
         target_ref  TEXT NOT NULL,
+        target_id   TEXT NOT NULL DEFAULT '',
         kind        TEXT NOT NULL,
         field       TEXT NOT NULL DEFAULT '',
-        PRIMARY KEY (source_id, target_ref, kind, field),
+        PRIMARY KEY (source_id, target_ref, kind, field, target_id),
         FOREIGN KEY (source_id) REFERENCES mikser_entities(id) ON DELETE CASCADE
     ) WITHOUT ROWID;
     CREATE INDEX IF NOT EXISTS idx_mikser_refs_target ON mikser_refs(target_ref);
-`)
+    CREATE INDEX IF NOT EXISTS idx_mikser_refs_target_id ON mikser_refs(target_id);
+`
+registerSchema('mikser_refs', REFS_SCHEMA)
 
 // Build the index handle over the provided sqlite database. Prepares
 // the SQL statements once at construction; subsequent reads/writes
@@ -82,6 +109,14 @@ export function createIndex(db) {
         SELECT DISTINCT source_id FROM mikser_refs
         WHERE target_ref = ?
     `)
+    // Identity-direction inbound: everything BOUND to this entity, under
+    // whatever name it was asked for. Immune to the target renaming
+    // itself, which is the whole point — the binding was recorded when
+    // it was made instead of re-derived from the target's current names.
+    const stmtInboundByTargetId = db.prepare(`
+        SELECT DISTINCT source_id FROM mikser_refs
+        WHERE target_id = ? AND target_id != ''
+    `)
     const stmtInboundDynamic = db.prepare(`
         SELECT source_id, kind FROM mikser_refs
         WHERE target_ref = ? AND kind != 'ref'
@@ -109,6 +144,45 @@ export function createIndex(db) {
         SELECT COUNT(DISTINCT source_id) AS c FROM mikser_refs WHERE kind != 'ref'
     `)
 
+    // Synchronous resolution of a ref string to entity ids. Mirrors
+    // `refFilter` in utils.js — id, meta.href, meta.url, then
+    // id-minus-extension — but as sync SQL, because indexEntity runs
+    // inside catalog.applyJournalMutations' transaction and
+    // better-sqlite3 transactions are sync-only.
+    //
+    // Returns every match, not the first: a name shared by language
+    // variants binds to all of them, and over-binding only ever means
+    // more invalidation, which the manifest's hash check then filters.
+    const stmtResolveExact = db.prepare(`
+        SELECT id FROM mikser_entities
+        WHERE id = ? OR meta_href = ? OR meta_url = ?
+    `)
+    const stmtResolveExtended = db.prepare(`
+        SELECT id FROM mikser_entities WHERE id GLOB ?
+    `)
+    function resolveRefIds(ref) {
+        if (typeof ref !== 'string' || !ref) return []
+        const ids = new Set()
+        for (const row of stmtResolveExact.all(ref, ref, ref)) ids.add(row.id)
+        // The extension-tolerant form. GLOB narrows to `<ref>.something`
+        // using the primary key's prefix; the regex then enforces
+        // EXACTLY one trailing extension and no further path segment,
+        // matching refFilter's `^ref\.[^./]+$`.
+        //
+        // SQLite's GLOB has no escape syntax, so a ref containing GLOB
+        // metacharacters cannot be used as a literal prefix. Skip the
+        // narrowing rather than run a pattern that means something else
+        // than the caller wrote; the exact forms above still apply, and
+        // the name-direction query still covers the edge.
+        if (/[*?[\]]/.test(ref)) return [...ids]
+        const escaped = ref.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        const oneExtension = new RegExp(`^${escaped}\\.[^./]+$`)
+        for (const row of stmtResolveExtended.all(`${ref}.*`)) {
+            if (oneExtension.test(row.id)) ids.add(row.id)
+        }
+        return [...ids]
+    }
+
     // Write statements
     const stmtClearStaticForSource = db.prepare(`
         DELETE FROM mikser_refs WHERE source_id = ? AND kind = 'ref'
@@ -117,8 +191,8 @@ export function createIndex(db) {
         DELETE FROM mikser_refs WHERE source_id = ? AND kind != 'ref'
     `)
     const stmtInsertEdge = db.prepare(`
-        INSERT OR IGNORE INTO mikser_refs (source_id, target_ref, kind, field)
-        VALUES (?, ?, ?, ?)
+        INSERT OR IGNORE INTO mikser_refs (source_id, target_ref, target_id, kind, field)
+        VALUES (?, ?, ?, ?, ?)
     `)
 
     // -- Read API ------------------------------------------------------
@@ -168,25 +242,45 @@ export function createIndex(db) {
     // schemas / findRef use. Cycle-safe via the result Set.
     function inverseClosureOf(seeds, getEntityById) {
         const closure = new Set()
-        const keysToWalk = []
+        const toWalk = []
+
+        const enqueue = (id, entity) => {
+            if (!id || closure.has(id)) return
+            closure.add(id)
+            toWalk.push({ id, entity })
+        }
 
         for (const seed of seeds ?? []) {
             const entity = typeof seed === 'string' ? null : seed
-            const id = entity?.id ?? (typeof seed === 'string' ? seed : null)
-            if (!id) continue
-            if (closure.has(id)) continue
-            closure.add(id)
-            keysToWalk.push(...lookupKeys(entity ?? { id }))
+            enqueue(entity?.id ?? (typeof seed === 'string' ? seed : null), entity)
         }
 
-        while (keysToWalk.length > 0) {
-            const key = keysToWalk.shift()
-            const referrers = stmtInboundAny.all(key)
-            for (const { source_id: id } of referrers) {
-                if (closure.has(id)) continue
-                closure.add(id)
-                const entity = getEntityById?.(id)
-                keysToWalk.push(...lookupKeys(entity ?? { id }))
+        while (toWalk.length > 0) {
+            const { id, entity } = toWalk.shift()
+            const referrers = new Set()
+
+            // Identity direction: edges BOUND to this entity. Survives
+            // the entity renaming itself, because the binding was
+            // recorded at resolve time rather than reconstructed from
+            // whatever names it happens to carry now.
+            for (const row of stmtInboundByTargetId.all(id)) referrers.add(row.source_id)
+
+            // Name direction: edges that ASKED for a name this entity
+            // answers to. Covers unresolved/forward references, and an
+            // entity that has just started answering to a name nobody
+            // could resolve before.
+            //
+            // Union rather than replacement: strictly a superset of the
+            // pre-binding behaviour, so nothing that invalidated before
+            // can stop invalidating now. Over-approximating here is
+            // cheap — manifest.skipDecision still compares hashes and
+            // drops anything that did not actually change.
+            for (const key of lookupKeys(entity ?? { id })) {
+                for (const row of stmtInboundAny.all(key)) referrers.add(row.source_id)
+            }
+
+            for (const sourceId of referrers) {
+                enqueue(sourceId, getEntityById?.(sourceId))
             }
         }
 
@@ -208,7 +302,18 @@ export function createIndex(db) {
         stmtClearStaticForSource.run(entity.id)
         if (!entity.meta) return
         for (const { path, ref } of extractRefs(entity.meta)) {
-            stmtInsertEdge.run(entity.id, ref, 'ref', path)
+            // Resolve now and record what it bound to. An unresolvable
+            // ref still gets its row with target_id '' — a forward
+            // reference is a real dependency, and the name-direction
+            // query is what will find it when the target appears.
+            const targetIds = resolveRefIds(ref)
+            if (!targetIds.length) {
+                stmtInsertEdge.run(entity.id, ref, '', 'ref', path)
+                continue
+            }
+            for (const targetId of targetIds) {
+                stmtInsertEdge.run(entity.id, ref, targetId, 'ref', path)
+            }
         }
     }
 
@@ -220,9 +325,16 @@ export function createIndex(db) {
         db.transaction(() => {
             stmtClearDynamicForSource.run(sourceId)
             if (!edges?.length) return
-            for (const { kind, target } of edges) {
+            for (const { kind, target, targetId, targetIds } of edges) {
                 if (!kind || !target) continue
-                stmtInsertEdge.run(sourceId, target, kind, '')
+                // Render-time edges already know what they resolved to —
+                // the lookup helper had the entity in hand — so no
+                // re-resolution here. `targetIds` carries the plural
+                // case (one name, several language variants).
+                const ids = targetIds?.length ? targetIds : targetId ? [targetId] : ['']
+                for (const id of ids) {
+                    stmtInsertEdge.run(sourceId, target, id, kind, '')
+                }
             }
         })
     }
@@ -260,6 +372,12 @@ export function createIndex(db) {
         dynamicInboundFor,
         dynamicOutboundFor,
         inverseClosureOf,
+        // Synchronous ref -> entity ids, mirroring refFilter's four
+        // forms. Exposed because the manifest needs the same binding
+        // the index records: hashing a static $-ref with catalog's
+        // findById only ever worked for id-form refs, since findById is
+        // an exact primary-key read.
+        resolveRefIds,
         // Write
         indexEntity,
         replaceDynamic,
@@ -459,6 +577,11 @@ export function createRefs(db, prebuiltIndex = null) {
 
         inverseClosureOf: (seeds) => index.inverseClosureOf(seeds, findById),
 
+        // Resolve a ref string to the entity ids it binds to — the same
+        // four forms refFilter uses, synchronously. The manifest needs
+        // it to hash a static $-ref correctly.
+        resolveRefIds: (ref) => index.resolveRefIds(ref),
+
         // Replace dynamic edges for a source — called by the engine
         // after a successful render via the track API.
         replaceDynamic: (sourceId, edges) => index.replaceDynamic(sourceId, edges),

package/src/render.js

@@ -74,9 +74,16 @@ function lookupHrefViaDb(href) {
 // `origin` (runtime.options.url) makes it absolute so static outputs —
 // emails, feeds — carry a whole URL; absent, it stays base-relative.
 // Unresolved refs return unchanged, staying visible like lookupHref.
-function lookupUrlViaDb(ref, preset, origin) {
+function lookupUrlViaDb(ref, preset, origin, track) {
     if (typeof ref !== 'string') return ref
     const row = stmtIdLookup.get(ref)
+    // Record the dependency here, where the row is already read, rather
+    // than in the wrapper — a second lookup per call would be paid on
+    // every image and media reference in a template. stmtIdLookup is an
+    // exact-id read, so a hit means the bound entity IS `ref`; a miss
+    // records the name with no binding, which is a forward reference and
+    // still a real dependency.
+    track?.lookup?.(ref, row ? ref : null)
     if (!row) return ref
     const meta = JSON.parse(row.data).meta || {}
     // A template helper called with one arg still receives the renderer's
@@ -196,19 +203,22 @@ export default async ({ entity, options, config, context, state, logger, port, t
         // no edge to check. A sidecar's findEntities() was tracked all along;
         // these two were the asymmetry.
         //
-        // The recorded target is the string the template asked for, not the
-        // resolved id — see track.lookup for why that also covers a target that
-        // does not exist yet.
+        // Both record the name asked for AND what it bound to. The
+        // entities are already in the result, so extracting the ids is
+        // free — see track.lookup for why both halves are needed.
         lookupHref: (href) => {
-            track?.lookup?.(href)
-            return lookupHrefViaDb(href)
+            const result = lookupHrefViaDb(href)
+            // Either a bare entity or a { lang: entity } map — see
+            // lookupHrefViaDb's contract above.
+            const ids = !result ? []
+                : typeof result.id === 'string' ? [result.id]
+                : Object.values(result).map(e => e?.id).filter(Boolean)
+            track?.lookup?.(href, ids)
+            return result
         },
         // Resolve a served-entity reference to its deployed URL, absolute
         // when runtime.options.url is set (ADR-0011).
-        lookupUrl: (ref, preset) => {
-            if (typeof ref === 'string') track?.lookup?.(ref)
-            return lookupUrlViaDb(ref, preset, options.url)
-        },
+        lookupUrl: (ref, preset) => lookupUrlViaDb(ref, preset, options.url, track),
         content() {
             return readFileSync(entity.source, { encoding: 'utf8' })
         },

package/src/report.js

@@ -13,7 +13,7 @@ import runtime from './runtime.js'
 
 function store() {
     runtime.state ??= {}
-    runtime.state.report ??= { rendered: [], skipped: [], warnings: [], gated: 0 }
+    runtime.state.report ??= { rendered: [], skipped: [], unchanged: [], warnings: [], gated: 0 }
     return runtime.state.report
 }
 
@@ -33,6 +33,17 @@ export function reportRendered(entity, reason) {
     store().rendered.push({ id: entity?.id, destination: entity?.destination ?? null, reason })
 }
 
+// A render that RAN and produced bytes identical to what was already on
+// disk. Distinct from both other outcomes and the interesting one of the
+// three: `rendered` means the output moved, `skipped` means the manifest
+// decided not to look, and this means invalidation was coarser than it
+// needed to be. Nothing downstream should have been disturbed, and the
+// count is the measure of how much conservative invalidation costs.
+export function reportUnchanged(entity) {
+    if (!runtime.options?.json) return
+    store().unchanged.push({ id: entity?.id, destination: entity?.destination ?? null })
+}
+
 export function reportSkipped(entity, reason) {
     if (!runtime.options?.json) return
     store().skipped.push({ id: entity?.id, destination: entity?.destination ?? null, reason })
@@ -54,9 +65,13 @@ export function buildReport() {
     return {
         rendered: report.rendered,
         skipped: report.skipped,
+        unchanged: report.unchanged,
         warnings: report.warnings,
         summary: {
             rendered: report.rendered.length,
+            // Of those renders, how many produced bytes identical to
+            // what was already on disk — see reportUnchanged.
+            unchanged: report.unchanged.length,
             // Renders that were CONSIDERED and skipped by the manifest.
             skipped: report.skipped.length,
             // Entities gated at import because their source was unchanged, so

package/src/track.js

@@ -60,15 +60,26 @@ export function createTrack({ partial = true, query = true, lookup = true } = {}
         // the manifest and never in the refs index — recorded, and still
         // never scheduling a re-render.
         //
-        // The target is the STRING the template asked for, not the resolved
-        // entity's id, and that is deliberate: lookupKeys() expands a mutated
-        // entity into its id, its meta.href AND its id-minus-extension, so an
-        // edge on '/contacts' fires whether the target was edited, renamed,
-        // deleted, or created for the first time. Recording the resolved id
-        // instead would miss the case where nothing resolved yet.
-        const lookups = new Set()
+        // Records BOTH the string asked for and what it resolved to.
+        // The string alone cannot survive the target renaming itself;
+        // the resolved id alone cannot express a link to a page that
+        // does not exist yet. mikser_refs keeps both columns for the
+        // same reason, and the two invalidation directions read one
+        // each.
+        //
+        // A name can resolve to several entities — language variants
+        // share a meta.href — so the value is a Set of ids, empty when
+        // the lookup found nothing.
+        const lookups = new Map()
         track.lookups = lookups
-        track.lookup = (target) => { if (target && typeof target === 'string') lookups.add(target) }
+        track.lookup = (target, resolvedIds) => {
+            if (!target || typeof target !== 'string') return
+            let ids = lookups.get(target)
+            if (!ids) lookups.set(target, ids = new Set())
+            for (const id of Array.isArray(resolvedIds) ? resolvedIds : resolvedIds ? [resolvedIds] : []) {
+                if (id && typeof id === 'string') ids.add(id)
+            }
+        }
     }
     if (partial) {
         const partials = new Set()

package/src/utils.js

@@ -1,7 +1,7 @@
 import crypto from 'node:crypto'
 import { createHash } from 'node:crypto'
 import { hashFile } from 'hasha'
-import { stat, readFile, writeFile, mkdir, unlink, open } from 'node:fs/promises'
+import { stat, lstat, readFile, writeFile, mkdir, unlink, open } from 'node:fs/promises'
 import { createRequire } from 'node:module'
 import _ from 'lodash'
 import { minimatch } from 'minimatch'
@@ -17,15 +17,26 @@ import runtime from './runtime.js'
 // Pure: synchronous, no I/O, no engine state.
 export function inputHashOf(entity) {
     if (!entity) return ''
-    // For file-only entities (no meta/content surface) the upstream
-    // file-content checksum from `checksum()` above is the authoritative
-    // fingerprint and is already computed.
-    if (entity.checksum && entity.meta == null && entity.content == null) {
-        return crypto.createHash('sha1').update(String(entity.checksum)).digest('hex')
-    }
     return crypto.createHash('sha1').update(JSON.stringify({
         meta: entity.meta ?? null,
         content: entity.content ?? null,
+        // The bytes' fingerprint, for entities whose content is not in
+        // hand. Files are the whole reason: `files()` sets meta.url on
+        // every file entity, so `meta` is never null, so the old
+        // "file-only entity" special case (meta == null && content ==
+        // null) never fired for a real file — and the fall-through
+        // hashed {meta, content} with content null. The result was an
+        // inputHash that did not move when an image, video or download
+        // changed on disk. The file itself is copied rather than
+        // rendered, so nothing looked wrong; what broke was every
+        // dependent, whose refClosure dep-hash for that file was frozen
+        // and whose skipDecision therefore always said "unchanged".
+        //
+        // Excluded when content IS present: content is then the
+        // authoritative copy of the same bytes, and folding in a
+        // checksum computed a different way would make the hash depend
+        // on how the checksum happens to be derived.
+        checksum: entity.content == null ? entity.checksum ?? null : null,
         // `inputs` is how a plugin declares bytes that are NOT part of the
         // entity's own content but that its output depends on. Whatever is
         // put here participates in the hash, so a change to it invalidates
@@ -41,16 +52,26 @@ export function inputHashOf(entity) {
     })).digest('hex')
 }
 
-// Canonical lookup variants for an entity — the same three forms the
+// Canonical lookup variants for an entity — the same four forms the
 // schemas plugin, refs subscribers, and the catalog's findRef all use
 // to resolve `$author: '/authors/jane'` against an entity at
 // `/documents/authors/jane.yml` with `meta.href: '/authors/jane'`.
 // Pure: synchronous, no I/O.
+//
+// MUST stay in lockstep with `refFilter` below, which is the forward
+// direction of the same relation. `meta.url` used to be missing here
+// while refFilter had it: a `$hero: /hero.txt` ref to a served path
+// (ADR-0011) recorded an edge against `/hero.txt`, but the file entity
+// at `/files/hero.txt` produced keys `['/files/hero.txt',
+// '/files/hero']` — so nothing ever matched the edge and editing the
+// asset invalidated nothing. Every $-ref to an image, video or
+// download was silently non-invalidating.
 export function lookupKeys(entity) {
     const id = entity?.id
     if (!id) return []
     const keys = [id]
     if (entity.meta?.href) keys.push(entity.meta.href)
+    if (entity.meta?.url) keys.push(entity.meta.url)
     if (typeof id === 'string') {
         const stripped = id.replace(/\.[^./]+$/, '')
         if (stripped !== id) keys.push(stripped)
@@ -59,7 +80,7 @@ export function lookupKeys(entity) {
 }
 
 // Predicate inverse of `lookupKeys`: does `entity` answer to `refValue`
-// via any of the three canonical forms? Used by anywhere a per-entity
+// via any of the four canonical forms? Used by anywhere a per-entity
 // JS test of "does this match the ref" is needed without going through
 // the catalog (e.g. testing an in-hand entity).
 //
@@ -71,6 +92,7 @@ export function matchesRef(entity, refValue) {
     if (!entity || typeof refValue !== 'string') return false
     if (entity.id === refValue) return true
     if (entity.meta?.href === refValue) return true
+    if (entity.meta?.url === refValue) return true
     if (typeof entity.id === 'string' && entity.id.replace(/\.[^./]+$/, '') === refValue) return true
     return false
 }
@@ -910,6 +932,68 @@ export function useCollection(runtime, name) {
     }
 }
 
+// Write `bytes` to `file`, unless the file already holds exactly those
+// bytes. Returns true if it wrote, false if the file was already correct.
+//
+// Invalidation is deliberately conservative: an entity that merely READ
+// another entity re-renders when that one changes, because the engine
+// cannot know which field was read. That is the right default, and it
+// means renders regularly produce byte-identical output. Writing anyway
+// moves mtime, and three things downstream key off the file rather than
+// its contents:
+//
+//   - live reload watches the output folder, so editing one photograph
+//     reloaded the browser on pages that had not changed
+//   - rsync, `aws s3 sync` and most CDN tools compare size plus mtime,
+//     so unchanged pages re-upload
+//   - `find out -newer` cannot answer "what did this build change?"
+//
+// Doing it here rather than narrowing the dependency edges fixes every
+// conservative-invalidation case at once, and stays correct as the graph
+// gets more precise instead of becoming redundant.
+//
+// Ordering matters: the size check comes first so the common
+// output-really-changed case never pays for a read, and lstat (not stat)
+// because a destination that is currently a SYMLINK has to be replaced
+// by a real file even when the bytes behind it match — the type of the
+// destination is part of the output, not just its contents.
+export async function writeOutput(file, bytes) {
+    // Size first, and WITHOUT materialising a buffer: Buffer.byteLength
+    // measures a string in place, while Buffer.from copies it (~250µs for
+    // a 1MB page, against ~25µs for the lstat). Since a size mismatch is
+    // the common outcome on a build that changed something, the cheap
+    // path must not pay for the expensive one.
+    const size = Buffer.isBuffer(bytes) ? bytes.length : Buffer.byteLength(bytes)
+    let identical = false
+    try {
+        const info = await lstat(file)
+        if (info.isFile() && info.size === size) {
+            const existing = await readFile(file)
+            identical = Buffer.isBuffer(bytes)
+                ? bytes.equals(existing)
+                : existing.equals(Buffer.from(bytes))
+        }
+    } catch (err) {
+        // Missing or unreadable — fall through and write. Anything else
+        // is a bug in this function, and swallowing it would look
+        // exactly like "the file wasn't there": a missing `lstat` import
+        // made every comparison fail open, so the skip silently never
+        // happened while the tests still passed.
+        if (err.code !== 'ENOENT' && err.code !== 'EACCES') throw err
+    }
+    if (identical) return false
+    await mkdir(path.dirname(file), { recursive: true })
+    // Unlink first so an existing hard link or symlink at this path is
+    // broken rather than written through.
+    try {
+        await unlink(file)
+    } catch { /* not there, or not removable — writeFile will say so */ }
+    // Pass the original value through — writeFile encodes a string
+    // directly, so converting first would add a copy for nothing.
+    await writeFile(file, bytes)
+    return true
+}
+
 // ── operating-system and file-manager litter ────────────────────────────
 //
 // Exposing a source folder over a network filesystem (mikser-io-webdav) or