mikser-io 9.29.0 → 9.30.0

package/docs/diagnostics.md

@@ -20,6 +20,8 @@ engine source, the entry point is missing and belongs on this page.
 | Which layout claimed this document, and why that one? | [`layouts.inspect()`](#layoutsinspect) |
 | Why does this page's output look stale? | [`runtime.manifest`](#runtimemanifest) |
 | Two files seem to fight over one output | [`--explain`](#--explain-entity), [`--verify`](#--verify) |
+| Which source file produced this built output? | [`runtime.manifest`](#runtimemanifest), `mikser_which` |
+| What would break if I changed this file? | [`runtime.manifest`](#runtimemanifest) `affectedBy` |
 | Did my schema validate anything at all? | [`schemas.names()`](#schemasnames--schemaslookup) |
 
 ## Command line
@@ -297,11 +299,16 @@ an SDK, or an agent speaking MCP actually has.
 
 **MCP** — `mikser_explain`, `mikser_build_report`, `mikser_verify`,
 alongside the existing `mikser_refs_*`, `mikser_layouts_inspect` and the
-`mikser://logs/recent` resource. Two more answer the questions a shell
+`mikser://logs/recent` resource. Four more answer the questions a shell
 would otherwise be needed for: `mikser_search` finds a string across
-entity meta and source files in one call, and `mikser_read_output` reads
-the bytes currently on disk for a destination — which is a different
-question from what the catalog or the manifest says should be there.
+entity meta, source files and — with `in: ["output"]` — the built files,
+reporting occurrences per destination; `mikser_read_output` reads the
+bytes currently on disk for a destination, which is a different question
+from what the catalog or the manifest says should be there;
+`mikser_which` goes the other way, from a built destination back to the
+source that produced it and the line that defines a given selector; and
+`mikser_update_entity({ dryRun: true })` reports the blast radius of an
+edit before making it.
 
 **REST** — on the `api` plugin, gated on their own `diagnostics`
 operation:
@@ -430,6 +437,8 @@ What was rendered and whether it needs redoing.
 | `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 |
+| `snapshotsAt(destination)` | every snapshot claiming a destination — the reverse of `snapshotsFor`, and the way back from a built file to what produced it |
+| `affectedBy(entity)` | which destinations would re-render if this entity changed, each with the same `reason` the build report uses |
 | `verify({outputFolder})` | `{ verdict, missing, mismatched, unverifiable, orphaned, collisions }` — what `--verify` reports; pure, no mutations |
 | `collisions()` | destinations claimed by more than one entity, with the ids claiming each |
 | `writerOf(destination, outputHash)` | which of several claimants wrote the bytes now on disk, when the hashes can tell them apart |
@@ -440,6 +449,14 @@ 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.
 
+`affectedBy(entity)` answers the same question one step earlier: *before*
+editing a shared file, which outputs does this reach? It runs the real
+`skipDecision` against each candidate rather than reimplementing the
+rule, so the preview and the cycle it previews cannot disagree. What it
+cannot model is how the entity's own frontmatter would change — that is
+parsed during import, so an edit that moves `meta.layout` moves the
+destination too, and this does not see it.
+
 ### `layouts.inspect()`
 
 Exposed by `mikser-io-layouts` at `runtime.options.layouts.inspect(id)`.

package/package.json

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

package/src/auth.js

@@ -112,6 +112,11 @@ export function reachabilityOf({ auth, token, allowRemote } = {}) {
 //     loopback, or allowRemote      → allow
 //     otherwise                     → 403
 //
+// A verifier may refine the "presented, invalid" case through an optional
+// `rejectionFor(req)` returning `{ status, code, description }` — see the
+// call site. It can only narrow a denial that already happened; there is no
+// return value from it that turns a rejection into an acceptance.
+//
 // `trustLoopback: true` restores the older mikser behaviour where a
 // token-gated endpoint stayed open to localhost. It exists so the api and
 // mcp plugins can keep their documented semantics for a plain `token:`
@@ -123,10 +128,30 @@ export async function authorize(req, verifier, { allowRemote = false, trustLoopb
         const result = await verifier.verify(req)
         if (result) return { ok: true, principal: result }
         if (result === false) {
-            return { ok: false, status: 401, reason: 'invalid',
-                     error: 'Invalid credential' }
+            // A rejected credential is not one thing. An EXPIRED token means
+            // "exchange your refresh token and retry" — a client does that
+            // silently. A token whose subject lacks the capability means
+            // "refreshing will not help", and a client that refreshes on it
+            // loops. Told apart only by the verifier, which is the only thing
+            // that looked at the credential, so it gets to refine the answer.
+            //
+            // Absent (every verifier before this existed), the answer is
+            // today's: 401 invalid_token, which is right for the common case
+            // and is what a client needs in order to refresh at all.
+            const refined = verifier.rejectionFor?.(req)
+            return {
+                ok: false,
+                status: refined?.status ?? 401,
+                reason: 'invalid',
+                code: refined?.code ?? 'invalid_token',
+                description: refined?.description,
+                error: refined?.description ?? 'Invalid credential',
+            }
         }
-        // Nothing presented.
+        // Nothing presented. No `code`: RFC 6750 §3.1 says a challenge to a
+        // request that carried no credential omits `error` entirely, and the
+        // omission is the signal — it is how a client tells "you have never
+        // authenticated here" from "the token you hold went stale".
         if (trustLoopback && local) return { ok: true, principal: { subject: 'loopback' } }
         return { ok: false, status: 401, reason: 'missing',
                  error: 'Authentication required' }
@@ -153,7 +178,12 @@ export function requireAuth(verifier, options = {}) {
             req.principal = outcome.principal
             return next()
         }
-        if (outcome.status === 401) verifier?.challenge?.(req, res)
+        // 403 carries a challenge too: RFC 6750 §3.1 puts insufficient_scope
+        // there, and a client that only reads the header on a 401 is exactly
+        // the client that cannot tell the two apart.
+        if (outcome.status === 401 || outcome.status === 403) {
+            verifier?.challenge?.(req, res, outcome)
+        }
         res.status(outcome.status).json({ error: outcome.error })
     }
 }
@@ -202,12 +232,24 @@ export function anyOf(...verifiers) {
             return rejected ? false : null
         },
 
+        // Whichever member actually judged the credential gets to say why it
+        // failed. Without forwarding this, composing a static token with an
+        // OAuth verifier silently downgrades every expiry to a bare 401 and
+        // the refresh signal is lost precisely on the surfaces that have one.
+        rejectionFor(req) {
+            for (const verifier of list) {
+                const refined = verifier.rejectionFor?.(req)
+                if (refined) return refined
+            }
+            return undefined
+        },
+
         // Challenge with the verifier that can actually be satisfied
         // interactively — pointing a browser at "Bearer" when the real
         // option is OAuth discovery helps nobody.
-        challenge(req, res) {
+        challenge(req, res, outcome) {
             const chooser = discovering ?? list.find(v => v.challenge)
-            chooser?.challenge?.(req, res)
+            chooser?.challenge?.(req, res, outcome)
         },
     }
 }

package/src/manifest.js

@@ -56,7 +56,7 @@ import { useLogger } from './engine.js'
 import { onLoaded, onFinalize } from './lifecycle.js'
 import { useJournal } from './journal.js'
 import { OPERATION } from './constants.js'
-import { extractRefs, inputHashOf, inputPartsOf, diffInputParts } from './utils.js'
+import { extractRefs, inputHashOf, inputPartsOf, diffInputParts, lookupKeys } from './utils.js'
 import { filterKey } from './track.js'
 import { findById } from './catalog.js'
 import { useDatabase, registerSchema } from './database/index.js'
@@ -295,6 +295,10 @@ export function createManifest(db) {
     const stmtSelectByDestination = db.prepare(`
         SELECT id FROM mikser_snapshots WHERE destination = ?
     `)
+    const stmtLookupByDestination = db.prepare(`
+        SELECT id, destination, inputHash, inputParts, outputHash, refClosure, renderedAt, parent
+        FROM mikser_snapshots WHERE destination = ?
+    `)
     const stmtDeleteByDestination = db.prepare(`
         DELETE FROM mikser_snapshots WHERE destination = ?
     `)
@@ -392,6 +396,28 @@ export function createManifest(db) {
         WHERE refClosure LIKE '%"kind":"query"%'
     `)
 
+    // Snapshots holding a non-query edge that names any of the given keys,
+    // by the name asked for OR by the entity it bound to. Both, for the same
+    // reason skipDecision reads both — a name survives a rename only through
+    // the binding, and a forward edge to a page that does not exist yet has
+    // only the name.
+    //
+    // A prefilter, not the answer: it narrows a corpus-wide walk to the
+    // handful of snapshots that could possibly care, and the real
+    // skipDecision then judges each one.
+    const edgeCandidates = (keys) => {
+        if (!keys.length) return []
+        const holes = keys.map(() => '?').join(',')
+        return db.prepare(`
+            SELECT DISTINCT s.id AS id, s.destination AS destination
+            FROM mikser_snapshots s, json_each(s.refClosure) j
+            WHERE s.refClosure IS NOT NULL
+              AND json_extract(j.value, '$.kind') != 'query'
+              AND (json_extract(j.value, '$.target')   IN (${holes})
+                OR json_extract(j.value, '$.targetId') IN (${holes}))
+        `).all(...keys, ...keys)
+    }
+
     const manifest = {
         // Look up a previously-recorded entry by entity (or by an
         // object with `{id, destination}`). Returns the snapshot, or
@@ -414,6 +440,78 @@ export function createManifest(db) {
             return stmtLookupById.all(id).map(rowToSnap)
         },
 
+        // Every snapshot that claims a destination — the reverse of
+        // snapshotsFor, and the entry point for "what produced this file?".
+        // More than one means a collision; see collisions().
+        snapshotsAt(destination) {
+            if (!destination) return []
+            return stmtLookupByDestination.all(destination).map(rowToSnap)
+        },
+
+        // Which destinations would re-render if this entity changed.
+        //
+        // Answered by running the REAL skipDecision against each candidate,
+        // with the mutation maps the render loop would build for exactly this
+        // one entity. A second implementation of the invalidation rule would
+        // be a preview that disagrees with the cycle it is previewing, which
+        // is worse than no preview: it would be trusted.
+        //
+        // What it cannot model, and says so at its caller: how the entity's
+        // OWN meta would change. Frontmatter is parsed during import, not
+        // here, so a change that alters meta.layout (and therefore the
+        // destination itself) is outside what this can see. Its own snapshots
+        // are reported as affected regardless, which is the safe direction.
+        affectedBy(entity) {
+            if (!entity?.id) return []
+            const lang = entity?.meta?.lang ?? null
+            const hash = inputHashOf(entity)
+            const keys = lookupKeys(entity)
+            const mutatedRefs = new Map(keys.map(key => [key, new Set([lang])]))
+            const currentHashes = new Map(keys.map(key => [key, hash]))
+            const mutatedEntities = new Map([[entity.id, entity]])
+
+            // Three ways a snapshot can care, unioned before judging so a
+            // snapshot reachable by two of them is judged once.
+            const candidates = new Map()
+            const consider = (id, destination) => {
+                if (!id || !destination) return
+                candidates.set(`${id}\u0000${destination}`, { id, destination })
+            }
+            for (const snap of this.snapshotsFor(entity.id)) consider(snap.id, snap.destination)
+            for (const row of edgeCandidates(keys)) consider(row.id, row.destination)
+            for (const id of this.queryAffected(mutatedEntities)) {
+                for (const snap of this.snapshotsFor(id)) consider(snap.id, snap.destination)
+            }
+
+            const affected = []
+            for (const { id, destination } of candidates.values()) {
+                // Its own renders: the premise of the question is that this
+                // entity changed, so asking skipDecision — which compares the
+                // hash of the entity as it stands NOW — would answer
+                // "unchanged" and hide the one destination the caller is
+                // certainly touching.
+                if (id === entity.id) {
+                    affected.push({ id, destination, reason: 'inputs-changed', why: 'this entity\'s own render' })
+                    continue
+                }
+                const dependent = findById(id)
+                if (!dependent) continue
+                const decision = this.skipDecision(
+                    { ...dependent, destination }, mutatedRefs, currentHashes, mutatedEntities)
+                if (decision.skip) continue
+                // The same provenance the build report carries. A bare list of
+                // destinations answers "how many" and not "why this one",
+                // which is the half that makes it checkable.
+                affected.push({
+                    id, destination, reason: decision.reason,
+                    ...(decision.changed?.length ? { changed: decision.changed } : {}),
+                    ...(decision.matched ? { matched: decision.matched } : {}),
+                    ...(decision.dependency ? { dependency: decision.dependency } : {}),
+                })
+            }
+            return affected
+        },
+
         // Should this render be skipped? See the original docstring in
         // the prior NDJSON-backed implementation — logic is unchanged,
         // backing storage is the only thing that changed.