mikser-io 9.15.0 → 9.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.15.0",
+  "version": "9.16.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/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
@@ -303,26 +323,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 +469,7 @@ export function createManifest(db) {
                 edges.push({
                     kind: 'layout',
                     target: entity.layout.id,
+                    targetId: entity.layout.id,
                     hash: inputHashOf(entity.layout),
                 })
             }
@@ -436,10 +479,38 @@ export function createManifest(db) {
                     edges.push({
                         kind: 'partial',
                         target,
+                        targetId: partial ? target : undefined,
                         hash: partial ? inputHashOf(partial) : undefined,
                     })
                 }
             }
+            if (track?.lookups) {
+                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 targetIds = [...ids]
+                    const bound = targetIds.length === 1 ? findById(targetIds[0]) : null
+                    edges.push({
+                        kind: 'lookup',
+                        target,
+                        targetId: targetIds.length === 1 ? targetIds[0] : undefined,
+                        targetIds: targetIds.length > 1 ? targetIds : undefined,
+                        hash: bound ? inputHashOf(bound) : undefined,
+                    })
+                }
+            }
             if (track?.queries) {
                 for (const filter of track.queries) {
                     edges.push({ kind: 'query', filter })

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
@@ -187,10 +194,31 @@ export default async ({ entity, options, config, context, state, logger, port, t
         // state.layouts.sitemap map that was serialized per render
         // task. Goes through the same WAL-backed read-only handle
         // every worker shares with the engine writer.
-        lookupHref: lookupHrefViaDb,
+        // Both lookups RECORD what they were asked for, via track.lookup.
+        //
+        // They read the catalog directly, and until this they told nobody —
+        // so nothing knew a page depended on the page it links to. Renaming
+        // a target left every page linking to it pointing at a file that no
+        // longer existed, on a green build, because manifest.shouldSkip had
+        // no edge to check. A sidecar's findEntities() was tracked all along;
+        // these two were the asymmetry.
+        //
+        // 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) => {
+            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) => lookupUrlViaDb(ref, preset, options.url),
+        lookupUrl: (ref, preset) => lookupUrlViaDb(ref, preset, options.url, track),
         content() {
             return readFileSync(entity.source, { encoding: 'utf8' })
         },

package/src/track.js

@@ -40,8 +40,47 @@ export function filterKey(filter) {
 // The returned object exposes `partials: Set<string>` and
 // `queries: Array<filter | null>` directly. Consumers iterate either
 // shape; both are owned by the track for the lifetime of the run.
-export function createTrack({ partial = true, query = true } = {}) {
+export function createTrack({ partial = true, query = true, lookup = true } = {}) {
     const track = {}
+    if (lookup) {
+        // Lookups a TEMPLATE made by name: runtime.href('/contacts'),
+        // runtime.lookupUrl('/media/clip.mp4'). Both read the catalog
+        // directly, and until this existed neither told anyone — so nothing
+        // recorded that a page depends on the page it links to.
+        //
+        // Measured consequence: rename contacts.md to contact-us.md and only
+        // the renamed page re-renders. Every page linking to it keeps a href
+        // pointing at a file that no longer exists, on a green build.
+        //
+        // The edge kind is 'lookup', NOT 'ref': mikser_refs divides ownership
+        // by kind — indexEntity owns kind='ref' (static frontmatter $-refs)
+        // and clears it per source, while replaceDynamic owns everything
+        // else. Writing these as 'ref' got them inserted by replaceDynamic
+        // and then wiped by the next indexEntity, so the edge existed in
+        // the manifest and never in the refs index — recorded, and still
+        // never scheduling a re-render.
+        //
+        // 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, 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()
         track.partials = partials

package/src/utils.js

@@ -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
 }