mikser-io 9.18.0 → 9.19.0

package/CLAUDE.md

@@ -94,16 +94,39 @@ brevity.
   corpus-scale and the caller doesn't need an array), `queryEntities`,
   `readEntity`, `subscribe`, `assertExpand`. Expand internals
   (`expandLimits`, `expandAndProject`, `findRef`) are PRIVATE.
+  All three readers accept either a sift object or a **function**
+  predicate; a function cannot be pushed into SQL, so it forces a full
+  scan and a JSON.parse per row — prefer an object, and `refFilter(ref)`
+  for the "resolve a ref string" case. `refFilter` / `matchesRef` /
+  `lookupKeys` are one relation in three directions (query, predicate,
+  reverse) and must be changed together: `meta.url` once lived in only
+  the first, which made every `$`-ref to a served path silently
+  non-invalidating. `test/unit/utils.test.js` property-tests the
+  symmetry.
 - `subscriptions.js` — `subscribe()` primitive. Two modes: journal-
   walk dispatch (default) and graph dispatch via
   `runtime.refs.subscribeGraph` (when `expand` is set).
 - `refs.js` — inverse-reference graph (`$`-keyed refs per ADR-0007).
-  Persisted as `mikser_refs` rows with FK to `mikser_entities`
-  (`ON DELETE CASCADE`). Indexed on `target` and `source`. Exposed
-  at `runtime.refs.*`: `inboundFor`, `outboundFor`, `allRefs`,
-  `size`, `rename`, `subscribeGraph`, `inverseClosureOf`. Plus
-  `refExists` module-level. Prepared statements through the shared
-  sqlite handle.
+  Persisted as `mikser_refs` rows with FK on `source_id` to
+  `mikser_entities` (`ON DELETE CASCADE`); indexed on `target_ref`
+  and `target_id`. Each row carries BOTH the string asked for
+  (`target_ref` — an id, `meta.href`, `meta.url`, or id-minus-
+  extension) and the entity it resolved to (`target_id`, `''` when
+  nothing did). Both are load-bearing: a name alone cannot survive the
+  target renaming itself, and an id alone cannot express a forward or
+  dangling reference. `inverseClosureOf` takes the union of a name
+  query and an identity query, so it is a superset of name-only
+  matching. Kinds: `ref` (static `$`-ref, owned by `indexEntity`),
+  and `layout` / `partial` / `query` / `lookup` (render-time, owned by
+  `replaceDynamic`) — the clears divide on `kind = 'ref'` vs
+  `kind != 'ref'`, so a render-time edge must never use `ref`.
+  Exposed at `runtime.refs.*`: `inboundFor`, `outboundFor`,
+  `dynamicInboundFor`, `dynamicOutboundFor`, `allRefs`, `size`,
+  `rename`, `inverseClosureOf`, `resolveRefIds`, `replaceDynamic`,
+  `clearDynamic`, `subscribeGraph`, `subscribeQuery`. Plus `refExists`
+  module-level. `REFS_SCHEMA` is exported so tests build against the
+  real schema instead of a copy. Prepared statements through the
+  shared sqlite handle.
 - `engine.js` — `setup()`, lifecycle wiring, render + postprocess
   dispatchers, manifest tracking. Owns the Piscina worker pools
   (`renderWorkers`, `postprocessWorkers`); both are lazy
@@ -191,6 +214,12 @@ brevity.
 - `constants.js` — `OPERATION` (CREATE/UPDATE/DELETE/RENDER/
   POSTPROCESS), `ACTION` (sync action types), `TASKS` (`INLINE`/
   `SERIAL`/`WORKER` — dispatch modes).
+- `../testing/harness.js` — the in-memory plugin harness, OUTSIDE
+  `src/` because it ships in the package (`.npmignore` excludes
+  `test/`). Sibling plugins import it as
+  `mikser-io/testing/harness.js` rather than copying it; the copies
+  drifted before it moved here. `test/unit/plugin-harness.js` is a
+  re-export for this repo's own tests.
 
 ## Canonical sibling plugins
 
@@ -516,11 +545,15 @@ There is **no `--mcp` CLI flag**. Activation is plugin-presence only.
 
 ## Test suites
 
-- `npm run test:unit` — 363 unit tests across plugins + utilities
-- `npm run test:scenarios` — 18 subprocess-spawned end-to-end runs
-  (manifest skip, refs replay, watch-mode change/delete). Spawns
-  mikser fresh per scenario so module-level catalog/refs/manifest
-  state can't leak between tests.
+- `npm run test:unit` — 540 unit tests across plugins + utilities
+- `npm run test:scenarios` — 96 assertions over 20 subprocess-spawned
+  end-to-end runs (manifest skip, refs replay, watch-mode
+  change/delete, lookup + asset invalidation, unchanged output,
+  `--force`, `--explain`, `--json`). Spawns mikser fresh per scenario
+  so module-level catalog/refs/manifest state can't leak between
+  tests. Scenarios use `freshWorkdir()` in os.tmpdir — never
+  `test/fixture`, which is tracked and must stay byte-identical
+  (`git status --short test/fixture` after any run that builds).
 - `npm run test:smoke` — full lifecycle build of `test/fixture/`
   (with vector + decap + post-mjml + post-pdf if env supports).
   Exercises both INLINE postprocess (PDF) and WORKER postprocess
@@ -531,8 +564,8 @@ There is **no `--mcp` CLI flag**. Activation is plugin-presence only.
 
 ## Dev workspace
 
-The siblings live side-by-side under `/Users/dick/Projects/mikser/`
-and share an npm workspace declared at the parent's `package.json`:
+The siblings live side-by-side in one parent folder and share an npm
+workspace declared at that parent's `package.json`:
 
 ```json
 {
@@ -573,6 +606,10 @@ the consumer's own project tree — no duplication, no bug.
 
 ## Reference
 
+- `docs/diagnostics.md` — "why did it do that?" — `--explain`,
+  `--json`, `--verify`, the sqlite tables, and every introspection
+  surface, indexed by the question it answers. Start here when
+  debugging rather than reading engine source.
 - `docs/architecture.md` — module map (audit before relying
   on specifics; may have drift)
 - `docs/decisions/` — ADRs

package/README.md

@@ -286,6 +286,7 @@ Mikser itself has a previous chapter: the [legacy 7.x line](https://github.com/a
 | [Entities](./docs/entities.md)               | Users & Developers | Entity model, operations, journal, catalog         |
 | [Rendering](./docs/rendering.md)             | Users & Developers | Render pipeline, render plugins, render modes      |
 | [Watch Mode](./docs/watch-mode.md)           | Users              | File watching, scheduled tasks, incremental builds |
+| [Diagnostics](./docs/diagnostics.md)         | Users & Developers | **"Why did it do that?"** — `--explain`, `--json`, `--verify`, the sqlite tables, and every introspection surface, indexed by the question it answers |
 | [MCP](https://github.com/almero-digital-marketing/mikser-io-mcp#readme) | Users              | The `mikser-io-mcp` plugin — tool surface, `mikser://` resources, twelve worked AI-driven scenarios |
 | [Caching](./docs/caching.md)                 | Users (production) | The `cache: true` disk cache + working nginx config for reverse-proxy failover |
 | [Architecture](./docs/architecture.md)       | Developers         | Module-level reference — what's in each file       |

package/docs/diagnostics.md

@@ -0,0 +1,289 @@
+# Diagnostics
+
+The other documents here are organised by subsystem — the lifecycle, the
+catalog, the render pipeline. That is the shape for learning how mikser
+works. This one is organised by the question you arrive with, which is
+almost always a form of *"why did it do that?"*
+
+Every surface below already exists. If answering a question means reading
+engine source, the entry point is missing and belongs on this page.
+
+## Start here
+
+| Your question | Reach for |
+| --- | --- |
+| Why didn't this page rebuild? | [`--explain`](#--explain-entity) |
+| What did this build actually change? | [`--json`](#--json) |
+| Does the output folder match what mikser thinks it wrote? | [`--verify`](#--verify) |
+| What happened during the last cycle, in order? | [`mikser_journal`](#mikser_journal) |
+| What depends on this entity? | [`runtime.refs`](#runtimerefs) |
+| Which layout claimed this document, and why that one? | [`layouts.inspect()`](#layoutsinspect) |
+| Why does this page's output look stale? | [`runtime.manifest`](#runtimemanifest) |
+| Did my schema validate anything at all? | [`schemas.names()`](#schemasnames--schemaslookup) |
+
+## Command line
+
+### `--explain <entity>`
+
+The single most direct answer to "why didn't this rebuild". Reports
+instead of building. Accepts an id, a `meta.href`, or an id without its
+extension — the same three forms a `$`-ref accepts, so you can paste
+whatever you have.
+
+```bash
+npx mikser --explain /documents/en/posts/hello.md
+```
+
+It prints the entity's layout and **why that layout matched**, its
+destination, its `inputHash`, whether the file on disk still agrees with
+the catalog, every recorded render with its `refClosure`, and a verdict
+in plain words — `would be SKIPPED — input hash unchanged`, or `would
+re-render`, or `source file is gone`.
+
+Each `refClosure` edge shows the name that was asked for and the entity
+it bound to, and flags the ones that bound to nothing:
+
+```
+refClosure  4 edges
+  ref        /hero.txt → /files/hero.txt  24dc5b87
+  ref        /does-not-exist  [UNRESOLVED — nothing answers to this name]
+  layout     /layouts/page.hbs  f274678c
+  lookup     /contacts  [UNRESOLVED — nothing answers to this name]
+```
+
+An `[UNRESOLVED]` edge is usually the answer on its own. Add `--json` for
+the same report as a machine-readable object. Exits `3` when the entity
+cannot be found.
+
+### `--json`
+
+A build report on stdout, as JSON. Logs and the banner move to stderr
+under this flag, so stdout parses whole.
+
+```bash
+npx mikser --json | jq '.summary'
+```
+
+Four buckets, and the distinction between them is the point:
+
+| Bucket | Meaning |
+| --- | --- |
+| `rendered` | the render ran, with a `reason` per entity |
+| `skipped` | the manifest decided not to render, with a `reason` |
+| `unchanged` | the render ran and produced bytes identical to what was already on disk |
+| `gated` | a count — the source was unchanged, so no render was ever scheduled |
+
+`reason` is a stable vocabulary you can assert on: `unchanged`,
+`never-rendered`, `inputs-changed`, `ref-changed`, `query-matched`,
+`cache-disabled`, `postprocessor`, `force`, `no-manifest`.
+
+`unchanged` is the interesting one. It means invalidation was coarser
+than it needed to be — the render was scheduled, ran, and produced
+nothing new. A high count is not a bug, but it tells you where the
+dependency graph is conservative.
+
+Warnings carry a stable `code` alongside their prose, so a test can
+assert "this build produced no preset-no-match" without grepping a
+sentence someone may later reword.
+
+### `--verify`
+
+Walks the output folder against the recorded snapshots and reports drift
+instead of building. Four categories, and the split matters:
+
+| Category | Meaning | Severity |
+| --- | --- | --- |
+| `Missing` | a snapshot records a destination that is not on disk | error |
+| `Mismatched` | the file's bytes differ from the recorded `outputHash` | error |
+| `No hash` | a snapshot with no recorded hash — nothing to compare | warning |
+| `Orphan` | a file on disk that no snapshot claims | warning |
+
+Exit codes make it usable as a CI gate directly: `2` if anything is
+missing or mismatched, `1` if only warnings, `0` when clean, and `2` when
+there is no manifest to check against.
+
+```bash
+npx mikser --verify || echo "output folder has drifted"
+```
+
+`Orphan` is the one to read carefully — it is normal for files that
+another plugin writes (assets, files, data), and a real signal for a page
+whose layout stopped producing it.
+
+### The rest, briefly
+
+| Flag | Use |
+| --- | --- |
+| `-f, --force` | ignore all three gates (import checksum, dispatch, manifest) and re-render everything |
+| `-R, --resume` | continue from a previous interrupted run's journal; skips the filesystem scan |
+| `-r, --clear` | clear state before running |
+| `-d, --debug` / `-t, --trace` | raise log level; `trace` includes per-entity catalog writes |
+
+`--force` composes with the unchanged-output check: it redoes the work
+without touching files whose bytes did not move, so it is cheap to reach
+for and its `unchanged` count tells you how much of the catalog was stale
+by suspicion rather than in fact.
+
+## The database
+
+Everything mikser knows lives in one SQLite file at
+`<workingFolder>/runtime/mikser.sqlite`. It is readable while a build
+runs (WAL mode) and it is often faster to ask it directly than to add
+logging.
+
+```bash
+sqlite3 runtime/mikser.sqlite
+```
+
+Five tables:
+
+| Table | Holds |
+| --- | --- |
+| `mikser_entities` | the catalog — one row per entity, `data` is the JSON body |
+| `mikser_journal` | the current cycle's operations, in order — cleared per cycle, which is what makes `--resume` possible |
+| `mikser_refs` | the dependency graph, both directions |
+| `mikser_snapshots` | what was rendered, where, and from which inputs |
+| `mikser_meta` | schema version and config checksum, for cache invalidation |
+
+### `mikser_journal`
+
+The ordered record of what the engine did this cycle — one row per
+operation, per consumer. When a build "did nothing" and you cannot see
+why, this is where the absence becomes visible: an entity that was never
+imported has no CREATE, and an entity gated at import has no RENDER.
+
+```sql
+SELECT operation, count(*) FROM mikser_journal GROUP BY operation;
+```
+
+### `mikser_refs`
+
+One row per dependency edge, carrying both the question and the answer:
+
+| Column | Meaning |
+| --- | --- |
+| `source_id` | the entity that depends |
+| `target_ref` | the string it asked for — an id, a `meta.href`, a `meta.url`, or an id minus its extension |
+| `target_id` | the entity that string resolved to, `''` if nothing did |
+| `kind` | `ref` (static `$`-ref), `layout`, `partial`, `query`, `lookup` |
+| `field` | for `ref`, the dotted path in `meta` |
+
+"What breaks if I rename this?" is one query:
+
+```sql
+SELECT source_id, kind, target_ref FROM mikser_refs
+ WHERE target_id = '/documents/en/authors/dick.yml';
+```
+
+A row with `target_id = ''` is a dangling reference — the dependent asked
+for a name nothing currently answers to.
+
+### `mikser_snapshots`
+
+One row per rendered destination: `inputHash` (what it was rendered
+from), `outputHash` (the bytes it produced), `refClosure` (the
+dependencies it recorded), `renderedAt`. An entity can have several — one
+per matched layout, one per paginated page.
+
+## From inside a plugin or a REPL
+
+### `runtime.refs`
+
+The dependency graph, queryable both ways.
+
+| Method | Answers |
+| --- | --- |
+| `inboundFor(ref)` | which entities `$`-ref this, and through which field |
+| `outboundFor(id)` | which refs this entity emits |
+| `dynamicInboundFor(target)` | which entities depend on this via layout / partial / query / lookup |
+| `dynamicOutboundFor(id)` | the render-time edges this entity recorded |
+| `inverseClosureOf(seeds)` | everything that transitively depends on these — the set a change dispatches |
+| `resolveRefIds(ref)` | which entity ids a ref string resolves to, by all four forms |
+| `allRefs()` / `size()` | every static ref target; edge and source counts |
+| `subscribeGraph(opts)` | react to changes within N hops of entities matching a filter |
+| `subscribeQuery(opts)` | react to changes matching a query |
+
+`inverseClosureOf` is the one to reach for when a change re-rendered more
+than you expected — it returns exactly the set the scheduler will act on.
+
+### `runtime.manifest`
+
+What was rendered and whether it needs redoing.
+
+| Method | Answers |
+| --- | --- |
+| `snapshotsFor(id)` | every snapshot for an entity, without knowing its destinations |
+| `lookup({id, destination})` | one snapshot |
+| `skipDecision(entity, …)` | `{ skip, reason }` — the same reason `--json` reports |
+| `recordedHashes()` | the dep-hashes dependents last saw |
+| `queryAffected(mutated)` | which query-dependent snapshots this mutation hits |
+| `verify({outputFolder})` | `{ missing, mismatched, unverifiable, orphaned }` — what `--verify` reports; pure, no mutations |
+| `size()` | snapshot count |
+
+`snapshotsFor(id)` exists because an entity can render to several
+destinations and a caller asking "what happened to this?" does not know
+them in advance — which is exactly the position you are in when a page
+did not change and you want to know why.
+
+### `layouts.inspect()`
+
+Exposed by `mikser-io-layouts` at `runtime.options.layouts.inspect(id)`.
+Answers "what does this layout actually do?" — its template source, the
+partials and references the renderer parses out of it, and the recorded
+`refClosure` of up to `samples` entities that used it, so you can see
+what it depended on in practice rather than in theory.
+
+```js
+const report = await runtime.options.layouts.inspect('/layouts/post.hbs', { samples: 3 })
+```
+
+Throws with `code: 'LAYOUT_NOT_FOUND'` for an id that is not a layout.
+
+### `schemas.names()` / `schemas.lookup()`
+
+Exposed by `mikser-io-schemas` at `runtime.options.schemas`. `names()`
+lists every loaded schema; `lookup(name)` returns the zod object.
+
+The failure worth knowing about: a schema that loaded but matched no
+entity is reported at finalize, because validation that silently never
+runs looks exactly like validation that passed. If you configured
+schemas and see no errors, check that warning before believing the
+content is clean.
+
+### `preview`
+
+`mikser-io`'s preview plugin exposes `runtime.options.preview = { store,
+get, stats, config }` — the on-demand render cache, useful for asking
+what has been rendered outside a build.
+
+## When mikser is silent
+
+Silence is this engine's characteristic failure mode: a declaration that
+selected nothing, or an input nothing tracked, and a green build. The
+surfaces that turn silence into a statement:
+
+- **A build that rendered nothing** — `--json` distinguishes `gated`
+  (source unchanged, never scheduled) from `skipped` (scheduled, manifest
+  declined). Those have different causes.
+- **A page pinned to stale bytes** — `--explain` on it, then read the
+  `refClosure` for an `[UNRESOLVED]` edge or a dependency you expected to
+  be listed and is not. An input nothing recorded is an input nothing
+  invalidates.
+- **A pattern or query that matched nothing** — several plugins warn on
+  this now (layout patterns, preset matching, null filters). The warnings
+  carry stable `code`s in `--json`.
+- **Output that does not match the config** — the config's bytes take
+  part in cache invalidation, so a config change forces a rebuild; but a
+  module the config *imports* does not. If you changed a helper the config
+  pulls in, use `--force`.
+- **A plugin that appears to do nothing** — `No plugins loaded` with a
+  config present is a warning naming the file. A config that fails to
+  load now exits non-zero rather than loading as empty.
+
+## See also
+
+- [Entities](./entities.md) — the entity model, operations, journal, catalog
+- [Lifecycle](./lifecycle.md) — which phase a hook can see what in
+- [API Reference](./api-reference.md) — full signatures
+- [Decisions](./decisions/) — why the graph is shaped this way, especially
+  ADR-0002 (files are the source of truth) and ADR-0009 (SQLite substrate)

package/package.json

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

package/src/catalog.js

@@ -414,7 +414,10 @@ export function findById(id) {
 // (hit the LRU and validate remaining clauses inline). For other
 // filters, translate to SQL + JS fallback.
 export async function findEntity(query) {
-    if (!query || typeof query !== 'object') return
+    // A function is a valid filter, so the guard has to admit one:
+    // `typeof fn !== 'object'`, and rejecting it here returns undefined
+    // for every function filter without a word.
+    if (!query || (typeof query !== 'object' && typeof query !== 'function')) return
     recordQuery(query)
 
     if (db?.isOpen) {
@@ -429,13 +432,12 @@ export async function findEntity(query) {
         }
 
         const t = siftToSql(query)
-        const sql = `SELECT data FROM mikser_entities ${t.sql} LIMIT ${t.jsFilter ? '' : '1'}`
-        // With a jsFilter we may need to scan multiple rows before
-        // finding a match; without one, LIMIT 1 short-circuits.
-        const stmt = db.prepare(t.jsFilter
+        // With a residual predicate we may need to scan multiple rows
+        // before finding a match; without one, LIMIT 1 short-circuits.
+        const matcher = residualMatcher(query, t.jsFilter)
+        const stmt = db.prepare(matcher
             ? `SELECT data FROM mikser_entities ${t.sql}`
             : `SELECT data FROM mikser_entities ${t.sql} LIMIT 1`)
-        const matcher = t.jsFilter ? sift(t.jsFilter) : null
         for (const row of stmt.iterate(...t.params)) {
             const entity = JSON.parse(row.data)
             if (!matcher || matcher(entity)) return entity
@@ -454,7 +456,7 @@ export async function findEntity(query) {
         if (Object.keys(rest).length === 0) return entity
         return sift(rest)(entity) ? entity : undefined
     }
-    const m = sift(query)
+    const m = typeof query === 'function' ? query : sift(query)
     for (const entity of shim.all()) {
         if (m(entity)) return entity
     }
@@ -463,6 +465,46 @@ export async function findEntity(query) {
 // All entities (no arg) or those matching `query`. Indexed clauses
 // push down to SQL; un-indexed clauses run as a sift filter over the
 // pushdown result set.
+// The residual predicate a SQL translation could not absorb.
+//
+// `translate()` reports `jsFilter: null` for two different situations:
+// nothing is left to check in JS, and the filter could not be read at
+// all. A function filter is the second. Reading that null as the first
+// discards the predicate — `findEntities(fn)` then answers with the
+// entire catalog and `findEntity(fn)` with whichever row LIMIT 1
+// returns, both silently. So the function case is decided HERE, from
+// `query` itself, rather than inferred from what translate returned.
+//
+// The plugin harness applies function filters, so a plugin that relies
+// on this passes its own tests either way; only production diverges.
+//
+// A function cannot be indexed — it forces a full scan and a JSON.parse
+// per row — so prefer an object filter, and `refFilter()` for the common
+// "resolve a ref string" case.
+function residualMatcher(query, jsFilter) {
+    if (jsFilter) return sift(jsFilter)
+    if (typeof query === 'function') {
+        warnFullScan()
+        return query
+    }
+    return null
+}
+
+// Once per process: a function filter is a performance cliff, not an
+// error, and a message per call on a hot path costs more than the cliff.
+let warnedFullScan = false
+function warnFullScan() {
+    if (warnedFullScan) return
+    warnedFullScan = true
+    try {
+        useLogger().debug(
+            'Catalog query used a function filter: this cannot be indexed and '
+            + 'scans the whole catalog. Prefer an object filter, or refFilter(ref) '
+            + 'to resolve a ref string.',
+        )
+    } catch { /* logger may not exist yet */ }
+}
+
 export async function findEntities(query) {
     recordQuery(query)
 
@@ -474,17 +516,14 @@ export async function findEntities(query) {
         const stmt = db.prepare(`SELECT data FROM mikser_entities ${t.sql}`)
         const rows = stmt.all(...t.params)
         const entities = rows.map(r => JSON.parse(r.data))
-        if (t.jsFilter) {
-            const matcher = sift(t.jsFilter)
-            return entities.filter(matcher)
-        }
-        return entities
+        const matcher = residualMatcher(query, t.jsFilter)
+        return matcher ? entities.filter(matcher) : entities
     }
 
     const shim = mapStub()
     if (!shim) return []
     if (!query) return shim.all()
-    const m = sift(query)
+    const m = typeof query === 'function' ? query : sift(query)
     return shim.all().filter(m)
 }
 
@@ -522,7 +561,7 @@ export async function* iterateEntities(query) {
         const stmt = db.prepare(
             `SELECT id, data FROM mikser_entities ${where} ORDER BY id LIMIT ?`,
         )
-        const matcher = t.jsFilter ? sift(t.jsFilter) : null
+        const matcher = residualMatcher(query, t.jsFilter)
 
         let lastId = ''
         while (true) {
@@ -540,7 +579,7 @@ export async function* iterateEntities(query) {
     // Stub path — for tests that don't bring up the database.
     const shim = mapStub()
     if (!shim) return
-    const m = query ? sift(query) : null
+    const m = query ? (typeof query === 'function' ? query : sift(query)) : null
     for (const entity of shim.all()) {
         if (!m || m(entity)) yield entity
     }

package/src/config.js

@@ -35,16 +35,15 @@ onLoad(async () => {
     //
     // 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.
+    // mistyped package name, a renamed local module, a dependency that was
+    // never installed. Catching the code cannot tell them apart, and a
+    // config with one bad import then loads as `{}`: the build reports "No
+    // plugins loaded" and exits 0, a green build with an empty output
+    // folder, one line below 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.
+    // Every other config failure is loud — a syntax error and a throw
+    // during evaluation both exit 1. Module resolution is the only one that
+    // needs this to stay in line with them.
     if (!existsSync(configFile)) {
         logger.debug('No config file at %s — using defaults', configFile)
     } else {

package/src/explain.js

@@ -117,10 +117,10 @@ export async function explain(reference) {
                     : {
                         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.
+                        // What the name resolved to. An absent binding
+                        // means a dangling edge — the most useful single
+                        // fact when a page will not re-render and nothing
+                        // says why.
                         bound: entry.targetIds?.length ? entry.targetIds
                             : entry.targetId ? [entry.targetId]
                             : [],

package/src/manifest.js

@@ -97,11 +97,11 @@ function buildRefClosure(entity, deps) {
     const closure = []
     const seen = new Set()
     // `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.
+    // ref resolved to — and they have to survive into the snapshot. A
+    // projection that keeps only {kind, target, hash} leaves the binding
+    // in mikser_refs and out of the snapshot, so skipDecision has nothing
+    // but the name to compare: the scheduler finds the dependent and the
+    // manifest then skips it.
     function pushTarget(kind, target, hash, targetId, targetIds) {
         if (!target) return
         const key = `${kind}:${target}`
@@ -122,11 +122,11 @@ function buildRefClosure(entity, deps) {
     if (entity.meta) {
         for (const { ref } of extractRefs(entity.meta)) {
             // 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.
+            // four forms. findById alone is an exact primary-key read, so
+            // a $-ref written as a meta.href or a served meta.url path
+            // (ADR-0011) resolves to nothing and the edge lands with no
+            // hash and no binding — leaving the manifest unable to see
+            // that the target changed.
             const ids = runtime.refs?.resolveRefIds?.(ref) ?? (findById(ref) ? [ref] : [])
             const bound = ids.length === 1 ? findById(ids[0]) : null
             pushTarget(
@@ -308,17 +308,17 @@ export function createManifest(db) {
         //   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.
+            // --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 has to
+            // reach all three. This one runs last, so if it alone ignores
+            // force, a forced build re-imports everything, re-dispatches
+            // everything, and drops all of it here as `unchanged`:
+            // rendered=0, and a summary that reads like a success.
             //
-            // 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.
+            // That is the situation --force exists for — the invalidation
+            // graph being under suspicion — including where the preset
+            // 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' }
             const snapshot = this.lookup(entity)
@@ -344,10 +344,10 @@ export function createManifest(db) {
                 // 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
+                // the bound entity may be re-persisted unchanged in the
+                // same cycle that a DIFFERENT entity starts answering to
+                // the same name. Stopping at the binding compares an
+                // unchanged hash and skips, 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.
@@ -499,20 +499,19 @@ export function createManifest(db) {
             }
             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".
+                    // The lookup helper has already resolved this and
+                    // handed over the ids, so the hash comes from the
+                    // BOUND entity. It must not come from
+                    // findById(target): that is an exact primary-key read
+                    // and resolves neither meta.href nor meta.url nor a
+                    // stripped extension, so any href- or url-form target
+                    // yields no hash and the manifest cannot 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.
+                    // No hash 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({

package/src/plugins/files.js

@@ -89,24 +89,24 @@ export function files(options = {}) {
                 case ACTION.UPDATE: {
                     const current = await findEntity({ id })
                     // `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.
+                    // plugin context, not a value — it has to be called.
+                    // Comparing the stored string against the function
+                    // itself is never equal, which makes the guard always
+                    // pass and `synced = false` unreachable.
                     const currentChecksum = await checksum(source)
                     if (current?.checksum != currentChecksum) {
                         await updateEntity({
                             id,
                             uri,
-                            // `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` — the prefixed form, the same one
+                            // CREATE uses. `relativePath` here drops the
+                            // outputFolder prefix that meta.url two lines
+                            // down keeps. The assets plugin builds preset
+                            // destinations from `name`, so the two
+                            // disagreeing sends a watched replacement's
+                            // derivatives somewhere else than a fresh
+                            // import's, and records the wrong path in
+                            // meta.presets.
                             name,
                             collection,
                             type,
@@ -159,12 +159,12 @@ 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.
+            // --force (and a wiped catalog) must defeat this gate, the
+            // same way source.js's gateChecksum lets them defeat its own.
+            // This is a second, independent gate: if it ignores them, no
+            // amount of forcing re-derives a file's name / meta.url /
+            // meta.presets, and a catalog holding bad `files` rows has no
+            // repair path short of deleting them.
             const forced = runtime.options.force || runtime.catalog?.cacheInvalidated
             const priorChecksums = checksumsByCollection(collection)
             await pMap(paths, async relativePath => {

package/src/plugins.js

@@ -89,9 +89,8 @@ onLoad(() => {
     if (!factoryEntries.length && !registeredRenderers && !registeredPostprocessors) {
         // "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.
+        // config. One line for both makes a config that produced no
+        // plugins read as a deliberate choice, so say which case it is.
         if (runtime.options.configChecksum) {
             logger.warn(
                 'No plugins loaded, but a config was read from %s — ' +

package/src/refs.js

@@ -26,11 +26,11 @@
 //                 (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.
+// alone means guessing which strings X could have answered to, and that
+// guess 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):
@@ -67,10 +67,9 @@ import { registerSchema, useDatabase } from './database/index.js'
 // already covers forward (everything X references) without a
 // separate index.
 //
-// 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.
+// Exported so tests build their index over the real schema rather than a
+// copy. A copy drifts the moment a column is added, and the failure is a
+// bare SQLITE_ERROR that names nothing.
 export const REFS_SCHEMA = `
     CREATE TABLE IF NOT EXISTS mikser_refs (
         source_id   TEXT NOT NULL,
@@ -270,11 +269,11 @@ export function createIndex(db) {
             // 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.
+            // Union rather than either alone: a superset of what each
+            // direction finds on its own, so no dependency is missed
+            // because it was recorded under the other one. Over-
+            // approximating here is cheap — manifest.skipDecision still
+            // compares hashes and drops anything that did not change.
             for (const key of lookupKeys(entity ?? { id })) {
                 for (const row of stmtInboundAny.all(key)) referrers.add(row.source_id)
             }

package/src/render.js

@@ -77,12 +77,11 @@ function lookupHrefViaDb(href) {
 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.
+    // Record the dependency here, where the row is already read: doing it
+    // in the wrapper costs a second lookup 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 || {}

package/src/report.js

@@ -34,11 +34,11 @@ export function reportRendered(entity, 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
+// 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.
+// declined to look, and this means invalidation was coarser than it needed
+// to be. Nothing downstream is disturbed, and the count measures what
+// conservative invalidation costs.
 export function reportUnchanged(entity) {
     if (!runtime.options?.json) return
     store().unchanged.push({ id: entity?.id, destination: entity?.destination ?? null })

package/src/track.js

@@ -45,20 +45,18 @@ export function createTrack({ partial = true, query = true, lookup = true } = {}
     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.
+        // directly, so without recording them nothing knows that a page
+        // depends on the page it links to — rename the target and only the
+        // target re-renders, leaving every link to it pointing at a file
+        // that no longer exists, on a green build.
         //
-        // 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.
+        // 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, replaceDynamic owns
+        // everything else. A render-time edge written as 'ref' is inserted
+        // by replaceDynamic and then wiped by the next indexEntity, so it
+        // lands in the manifest, never in the refs index, and schedules
+        // nothing.
         //
         // Records BOTH the string asked for and what it resolved to.
         // The string alone cannot survive the target renaming itself;

package/src/utils.js

@@ -21,21 +21,18 @@ export function inputHashOf(entity) {
         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".
+        // hand. Files are the reason it cannot be conditioned on `meta`
+        // being absent: `files()` stamps meta.url on every file entity,
+        // so a file always has meta, and a hash over {meta, content}
+        // alone does not move when the bytes on disk change. The file is
+        // copied rather than rendered, so that shows up nowhere in the
+        // file itself — it freezes the refClosure dep-hash of every
+        // dependent, whose skipDecision then always answers "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.
+        // on how that 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
@@ -59,13 +56,12 @@ export function inputHashOf(entity) {
 // 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.
+// direction of the same relation. A form present there and missing here
+// makes every ref written in that form silently non-invalidating: the
+// edge is recorded against the string the author wrote, and nothing the
+// target expands to ever matches it. `meta.url` is the one to watch —
+// a `$hero: /hero.txt` ref to a served path (ADR-0011) resolves through
+// it, while the file entity's id is `/files/hero.txt`.
 export function lookupKeys(entity) {
     const id = entity?.id
     if (!id) return []
@@ -935,22 +931,22 @@ 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:
+// Invalidation is deliberately conservative: an entity that merely READS
+// another 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. Three things
+// downstream key off the file rather than its contents, so writing it
+// anyway is not free:
 //
-//   - live reload watches the output folder, so editing one photograph
-//     reloaded the browser on pages that had not changed
+//   - live reload watches the output folder, so one edited photograph
+//     reloads the browser on every page that merely mentions it
 //   - 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.
+// The check belongs here rather than in the dependency edges: it covers
+// 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)

package/testing/harness.js

@@ -0,0 +1,246 @@
+// A minimal in-memory harness for testing core plugins.
+//
+// Real plugins call lifecycle registrations (onLoaded, onProcess, onSync, ...)
+// during their factory invocation; the engine later drives those callbacks. In
+// tests we substitute every API surface with a recorder, then drive the
+// callbacks manually with controlled inputs.
+
+import _ from 'lodash'
+import realRuntime from '../src/runtime.js'
+import { matchEntity, normalize, changeExtension, getFormatInfo, checksum, AbortError } from '../src/utils.js'
+
+const OPERATION = {
+    CREATE: 'create',
+    UPDATE: 'update',
+    DELETE: 'delete',
+    RENDER: 'render',
+    POSTPROCESS: 'postprocess',
+}
+const ACTION = {
+    CREATE: 'create',
+    UPDATE: 'update',
+    DELETE: 'delete',
+    TRIGGER: 'trigger',
+}
+const TASKS = { INLINE: 'inline', SERIAL: 'serial', WORKER: 'worker' }
+
+export function createHarness({
+    config = {},
+    options = {},
+    state = {},
+    entities = [],
+    journal = [],
+} = {}) {
+    const hookNames = [
+        'load', 'loaded', 'import', 'imported',
+        'process', 'processed', 'persist', 'persisted',
+        'beforeRender', 'render', 'afterRender',
+        'beforePostprocess', 'postprocess', 'afterPostprocess',
+        'finalize', 'finalized', 'cancel', 'cancelled',
+        'complete', 'validate',
+    ]
+    const hooks = Object.fromEntries(hookNames.map(n => [n, []]))
+    const sync = new Map()
+    const watchers = []
+    const renderTasks = []
+    const postprocessTasks = []
+    const progress = []
+    const logs = []
+    const mklog = (level) => (...args) => logs.push({ level, args })
+    const logger = {
+        info: mklog('info'),
+        warn: mklog('warn'),
+        error: mklog('error'),
+        debug: mklog('debug'),
+        trace: mklog('trace'),
+        notice: mklog('notice'),
+    }
+
+    let nextId = 1
+    const journalEntries = journal.map(e => ({ id: nextId++, output: null, context: {}, options: {}, ...e }))
+
+    function addEntry({ entity, operation, context = {}, options = {} }) {
+        journalEntries.push({ id: nextId++, entity, operation, context, options, output: null })
+    }
+
+    // Stub `runtime.catalog` so catalog.js's module-level findEntity /
+    // findEntities / findById / queryEntities / readEntity / expand
+    // walker read from the harness's in-memory entity set. Real
+    // catalog.js's onInitialized sets up an identical shape — a
+    // Map<id, entity> with a no-op save() — but persists to disk; the
+    // stub skips persistence. Pushes/mutations to the input `entities`
+    // array land in the same Map via the constructor below.
+    //
+    // Set on the runtime SINGLETON imported from src/runtime.js — that's
+    // what catalog.js sees. Setting it on the harness-local `runtime`
+    // object below wouldn't help because plugin code imports the
+    // singleton directly. Each createHarness() call overwrites the
+    // singleton's `.catalog`, which is fine because tests don't run in
+    // parallel within a file.
+    const catalogStub = {
+        byId: new Map(entities.filter(e => e?.id).map(e => [e.id, e])),
+        version: 'test',
+        cacheInvalidated: false,
+        // No-op save — the harness never wants disk side-effects.
+        // catalog.js's onFinalized hook calls runtime.catalog.save(),
+        // so any test that drives the full lifecycle would blow up
+        // without this.
+        save: async () => {},
+    }
+    realRuntime.catalog = catalogStub
+
+    const runtime = {
+        options: { workingFolder: '/tmp/test-mikser', plugins: [], ...options },
+        config,
+        state,
+        hooks,
+        engine: { logger },
+        catalog: catalogStub,
+        // A harness stands in for an engine that has finished its first build —
+        // the entities a test declares are already in the catalog stub. Tests
+        // that want the pre-build window (the api plugin's 503 gate) set this
+        // to false themselves.
+        ready: true,
+        // Real lifecycle.js attaches these to the runtime via side-effect
+        // on import. The harness doesn't load that module, so reproduce
+        // them here against the in-memory journal.
+        create: async (entity) => addEntry({ operation: OPERATION.CREATE, entity }),
+        update: async (entity) => addEntry({ operation: OPERATION.UPDATE, entity }),
+        delete: async ({ id, collection, type }) =>
+            addEntry({ operation: OPERATION.DELETE, entity: { id, collection, type } }),
+    }
+    function updateEntry({ id, entity, output }) {
+        const entry = journalEntries.find(e => e.id === id)
+        if (!entry) return
+        if (entity !== undefined) entry.entity = entity
+        if (output !== undefined) entry.output = output
+    }
+    async function* useJournal(name, operations, signal) {
+        progress.push({ name, total: journalEntries.length })
+        for (const entry of journalEntries) {
+            if (operations?.length && !operations.includes(entry.operation)) continue
+            if (signal?.aborted) return
+            yield entry
+        }
+    }
+
+    const core = {
+        runtime,
+        useLogger: () => logger,
+
+        // Lifecycle registrations
+        onLoad: (cb) => hooks.load.push(cb),
+        onLoaded: (cb) => hooks.loaded.push(cb),
+        onImport: (cb) => hooks.import.push(cb),
+        onImported: (cb) => hooks.imported.push(cb),
+        onProcess: (cb) => hooks.process.push(cb),
+        onProcessed: (cb) => hooks.processed.push(cb),
+        onPersist: (cb) => hooks.persist.push(cb),
+        onPersisted: (cb) => hooks.persisted.push(cb),
+        onBeforeRender: (cb) => hooks.beforeRender.push(cb),
+        onRender: (cb) => hooks.render.push(cb),
+        onAfterRender: (cb) => hooks.afterRender.push(cb),
+        onBeforePostprocess: (cb) => hooks.beforePostprocess.push(cb),
+        onPostprocess: (cb) => hooks.postprocess.push(cb),
+        onAfterPostprocess: (cb) => hooks.afterPostprocess.push(cb),
+        onFinalize: (cb) => hooks.finalize.push(cb),
+        onFinalized: (cb) => hooks.finalized.push(cb),
+        onCancel: (cb) => hooks.cancel.push(cb),
+        onCancelled: (cb) => hooks.cancelled.push(cb),
+        onComplete: (cb) => hooks.complete.push(cb),
+        onSync: (name, cb) => sync.set(name, cb),
+        onValidate: (operations, cb) => hooks.validate.push({ operations, cb }),
+
+        // Entity helpers — write directly to the journal
+        createEntity: async (entity) => addEntry({ operation: OPERATION.CREATE, entity }),
+        updateEntity: async (entity) => addEntry({ operation: OPERATION.UPDATE, entity }),
+        deleteEntity: async ({ id, collection, type }) =>
+            addEntry({ operation: OPERATION.DELETE, entity: { id, collection, type } }),
+        addEntry,
+        addEntries: async (entries) => entries.forEach(addEntry),
+        updateEntry,
+        useJournal,
+        findEntity: async (query) => {
+            if (!query) return entities[0]
+            if (typeof query === 'function') return entities.find(query)
+            return entities.find(e => Object.entries(query).every(([k, v]) => e[k] === v))
+        },
+        // Synchronous PK lookup mirroring catalog.js's findById. Layouts'
+        // onBeforeRender hydrates dispatch ids through this — the harness
+        // serves from the same in-memory entities array.
+        findById: (id) => entities.find(e => e?.id === id) ?? catalogStub.byId.get(id),
+        findEntities: async (query) => {
+            if (!query) return [...entities]
+            if (typeof query === 'function') return entities.filter(query)
+            return entities.filter(e => Object.entries(query).every(([k, v]) => e[k] === v))
+        },
+        iterateEntities: async function* (query) {
+            // Stub — yields the same set findEntities would return,
+            // one entity at a time. Real impl in catalog.js chunks via
+            // sqlite; the harness doesn't need that fidelity because
+            // unit-test corpora are tiny.
+            const filtered = !query
+                ? [...entities]
+                : (typeof query === 'function'
+                    ? entities.filter(query)
+                    : entities.filter(e => Object.entries(query).every(([k, v]) => e[k] === v)))
+            for (const e of filtered) yield e
+        },
+
+        // Rendering & postprocessing — capture for assertions
+        renderEntities: async (tasks) => renderTasks.push(...tasks),
+        postprocessEntities: async (tasks) => postprocessTasks.push(...tasks),
+        renderEntity: async () => { },
+        postprocessEntity: async () => { },
+
+        // Misc
+        watch: (name, folder) => watchers.push({ name, folder }),
+        schedule: () => { },
+        trackProgress: () => { },
+        updateProgress: () => { },
+        stopProgress: () => { },
+
+        // Utilities (real implementations)
+        matchEntity,
+        normalize,
+        changeExtension,
+        getFormatInfo,
+        checksum,
+        AbortError,
+
+        constants: { OPERATION, ACTION, TASKS },
+    }
+
+    async function runHook(name, ...args) {
+        const callbacks = hooks[name] || []
+        const results = []
+        for (const cb of callbacks) {
+            results.push(await cb(...args))
+        }
+        return results
+    }
+
+    async function runSync(name, payload) {
+        const handler = sync.get(name)
+        if (!handler) return undefined
+        return handler(payload)
+    }
+
+    return {
+        core,
+        runtime,
+        logger,
+        logs,
+        sync,
+        watchers,
+        renderTasks,
+        postprocessTasks,
+        progress,
+        journal: journalEntries,
+        hooks,
+        runHook,
+        runSync,
+        addJournalEntry: addEntry,
+        constants: { OPERATION, ACTION, TASKS },
+    }
+}