mikser-io 9.72.0 → 9.73.0

package/docs/configuration.md

@@ -70,24 +70,39 @@ Which subtrees of the output folder are deployed as their own domain root.
 
 ```js
 export default {
-    // out/bg becomes lmed.bg, out/en becomes lmed.info, out/mk becomes lmed.mk
+    // out/bg, out/en and out/mk each deploy to their own domain
     siteRoots: ['bg', 'en', 'mk'],
 }
 ```
 
-Read only by the broken-reference check. It resolves urls the way a browser
-does, and a browser cannot climb above the origin root — it discards the
-extra `..` and loads the file. Where the site root actually is therefore
-decides whether `../../x.svg` on a given page is correct, merely over-deep,
-or broken.
+Read by the url helpers and by the broken-reference check.
 
-Default is the output folder itself, which is right for the ordinary case of
-one site per build. Declare this only when a build emits several sites, as a
-per-language deploy does — resolving those against the output root instead
-misses the over-escape entirely and reports the working urls as broken.
+**It changes the output.** `asset`, `href` and `resource` build a path from the
+page to the target, and without this they measure from the output folder. When
+`out/bg` is what gets deployed, that is one directory too far — every url
+carries an extra `..` for the site segment. A browser floors a climb above the
+origin root rather than failing, so those urls load and nothing reports them.
+Declaring the roots makes the helpers measure from the site instead, and the
+urls become what they should have been.
+
+The check reads it for the same reason, and resolves urls the way a browser
+does. Where the site root is decides whether `../../x.svg` on a given page is
+correct, merely over-deep, or broken.
 
-Nothing can infer it: it is a fact about where the bytes get deployed, not
-about the bytes.
+Default is the output folder itself, which is right for the ordinary case of
+one site per build — and with nothing declared every url is byte-identical to
+what it was. Only a build that emits several sites moves, and it moves from
+working-by-flooring to correct.
+
+Declaring it also asserts something: **a site root is a deployable unit.** It
+is served alone, so anything its pages reference has to exist beneath it —
+share a common assets folder into each root rather than beside them. A url to
+a target in a *different* root is left as it was, because on a per-domain
+deploy no relative path reaches another origin; the check will report it, which
+is the honest answer.
+
+Nothing can infer any of this: it is a fact about where the bytes get deployed,
+not about the bytes.
 
 ## Engine Substrate
 

package/docs/diagnostics.md

@@ -231,7 +231,7 @@ the whole question:
 ```json
 { "destination": "/index.html", "reason": "query-matched",
   "matched": { "filter": { "id": { "$regex": "^/documents/devices/" } },
-               "by": "/documents/devices/hera.md" } }
+               "by": "/documents/devices/model-a.md" } }
 ```
 
 A `matched.filter` of `null` is a different statement: the page's predicate
@@ -887,12 +887,16 @@ surfaces that turn silence into a statement:
     same file, the output scan reports it and this one stays quiet.
 - **A link that works only by accident** — a url with one `..` too many
   still loads, because a browser discards a climb above the origin root
-  rather than failing. It is one level of nesting away from a 404, and
-  it means the emitted depth does not match the page. Reported under
-  `reference-over-deep`, separately from the outright failures. Which
-  root to floor at is deployment intent and cannot be derived, so
-  declare it — see `siteRoots` in
-  [configuration](./configuration.md#siteroots).
+  rather than failing. Reported under `reference-over-deep`, separately
+  from the outright failures, and grouped by how far each climbed:
+  - **One url, or several climbing different distances** — each is a
+    latent 404, working today and broken as soon as the same markup
+    renders one level deeper.
+  - **Every url climbing the same distance** — not N problems but one
+    base that is off by a constant, reported once and flagged
+    `structural` in `--json`. The urls work at every depth. Usually it
+    means `siteRoots` is undeclared for a build that emits several
+    sites; see [configuration](./configuration.md#siteroots).
 
 ## See also
 

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "mikser-io",
-  "version": "9.72.0",
+  "version": "9.73.0",
+  "files": [
+    "app.js",
+    "index.js",
+    "src/",
+    "testing/",
+    "docs/",
+    "favicon.ico",
+    "favicon.svg",
+    "mikser-mark.svg",
+    "mikser-lockup-stacked.svg"
+  ],
   "description": "A mixer for content: entities in, configurable render pipelines, outputs of any kind. Static sites are the canonical recipe, not the definition — the same engine renders PDFs, emails and whatever a renderer plugin produces. Files are the source of truth, every lifecycle phase is observable, and the build graph is queryable by an agent.",
   "main": "index.js",
   "exports": {

package/src/engine.js

@@ -127,19 +127,45 @@ async function reportBrokenReferences(logger) {
             broken.length, checked, broken.length > SHOWN ? `, ${SHOWN} shown` : '')
     }
 
-    for (const { url, target, files } of overDeep.slice(0, SHOWN)) {
-        logger.warn({ code: 'reference-over-deep', url, target, files },
-            'Over-deep, loads only because the browser floors it: %s (from %s) — %s',
-            url, named(files), target)
+    // Grouped by how FAR each climbed, because a site whose every over-deep url
+    // climbs the same distance does not have N problems — it has one base that
+    // is off by a constant. Printing it N times is precisely how a real signal
+    // gets filtered out, which is the failure this check exists to prevent.
+    const byClimb = new Map()
+    for (const entry of overDeep) {
+        if (!byClimb.has(entry.floored)) byClimb.set(entry.floored, [])
+        byClimb.get(entry.floored).push(entry)
     }
+    // One distance, many urls: structural. The helper's base is wrong, the urls
+    // are not — they load at every depth, because the climb is always floored.
+    // That wants a different reaction than a hand-written `../..` that happens
+    // to be right on one page and is a 404 waiting on the next.
+    const structural = byClimb.size === 1 && overDeep.length > 1
+
+    for (const [climb, entries] of [...byClimb].sort(([a], [b]) => a - b)) {
+        const examples = entries.slice(0, 3).map(e => e.url)
+        logger.warn(
+            {
+                code: 'reference-over-deep', climbs: climb, count: entries.length,
+                structural, urls: examples,
+                files: [...new Set(entries.flatMap(e => e.files))].slice(0, 3),
+            },
+            structural
+                ? '%d references climb %d level(s) above the site root — every one of them, by the '
+                  + 'same amount. They load: a browser discards the extra `..`. What is wrong is the '
+                  + 'base they were built from, not the links. Examples: %s'
+                : '%d reference(s) climb %d level(s) above the site root and load only because a '
+                  + 'browser discards the extra `..`. Each breaks if the same markup renders one '
+                  + 'level deeper. Examples: %s',
+            entries.length, climb, examples.join(', '))
+    }
+
     if (overDeep.length) {
-        logger.warn({ code: 'reference-over-deep-summary', overDeep: overDeep.length, checked },
-            '%d of %d reference(s) climb above the site root and load only because a browser '
-            + 'discards the extra `..`%s. They break as soon as the same markup renders one '
-            + 'level deeper.%s',
-            overDeep.length, checked, overDeep.length > SHOWN ? `, ${SHOWN} shown` : '',
-            siteRoots.length ? '' : ' No siteRoots are declared, so this resolved against the '
-                + 'output root — declare runtime.config.siteRoots if a subtree is deployed as its own domain.')
+        logger.warn({ code: 'reference-over-deep-summary', overDeep: overDeep.length, checked, structural },
+            '%d of %d reference(s) resolve above the site root.%s',
+            overDeep.length, checked,
+            siteRoots.length ? '' : ' No siteRoots are declared, so this resolved against the output '
+                + 'root — declare siteRoots if a subtree is deployed as its own domain.')
     }
 
     return new Set(broken.map(b => b.target))
@@ -472,6 +498,15 @@ export async function setup(options) {
     // runtime.config) and before any plugin's onLoaded.
     onLoad(async () => {
         const logger = useLogger()
+
+        // Onto OPTIONS, not left on config: the url helpers read it, and they
+        // run in render workers, which receive the worker-safe options and
+        // never see runtime.config.
+        runtime.options.siteRoots = runtime.config?.siteRoots ?? []
+        if (runtime.options.siteRoots.length) {
+            logger.info('Site roots: %s', runtime.options.siteRoots.join(', '))
+        }
+
         const cli = runtime.options.url
         const cfg = runtime.config?.url
         const raw = cli ?? cfg

package/src/plugins/render/asset.js

@@ -1,6 +1,6 @@
 import path from 'node:path'
 
-import { changeExtension } from '../../utils.js'
+import { changeExtension, siteRelativeUrl } from '../../utils.js'
 
 // `{{asset 'web' '/media/hero.jpg'}}` — the deployed URL of a preset
 // derivative, relative to the page asking for it.
@@ -71,8 +71,10 @@ export function load({ runtime, entity, state, options, logger, track }) {
         // itself — it takes a path, not an entity, so there is nothing to look
         // up and the URL is well-formed whether or not anything produced it.
         track?.asset?.(destination)
-        const from = path.dirname(entity.destination || '/')
-        return { url: path.relative(from, destination) }
+        // Resolved within the site this page belongs to, not against the
+        // output root — see siteRelativeUrl. With no siteRoots declared the two
+        // are the same folder and the url is byte-identical.
+        return { url: siteRelativeUrl(entity.destination, destination, options?.siteRoots) }
     }
 }
 

package/src/plugins/render/file.js

@@ -72,7 +72,7 @@ function warnIfUntrackable(options, resolved, logger) {
     //
     // The first version of this hardcoded five content folders, and a project
     // registering its own collections through sources() has more than five. On
-    // lmed that meant 63 warnings per build, one for every stylesheet and
+    // one real site that meant 63 warnings per build, one for every stylesheet and
     // script, all of them tracked correctly and every one of them saying the
     // opposite. Which is worse than not warning: 63 spurious lines a build
     // teaches you to filter the channel, and the filtered-out line is the real

package/src/plugins/render/href.js

@@ -1,4 +1,5 @@
 import path from 'node:path'
+import { siteRelativeUrl } from '../../utils.js'
 
 export function load({ entity, runtime, options }) {
     const { clear } = options
@@ -19,16 +20,14 @@ export function load({ entity, runtime, options }) {
 
         let found = runtime.hrefLang(href)
         if (!found) {
-            const from = path.dirname(entity.destination || '/')
-            return { url: path.relative(from, href) }
+            return { url: siteRelativeUrl(entity.destination, href, options?.siteRoots) }
         } else {
             if (!found.id) {
                 found = found[lang]
             }
             if (found?.destination) {
                 const destination = clear ? found.destination.replace('index.html', '') : found.destination
-                const from = path.dirname(entity.destination || '/')
-                found.url = path.relative(from, destination)
+                found.url = siteRelativeUrl(entity.destination, destination, options?.siteRoots)
             }
             return found
         }

package/src/plugins/render/resource.js

@@ -1,5 +1,5 @@
 import path from 'node:path'
-import { matchesLibrary } from '../../utils.js'
+import { matchesLibrary, siteRelativeUrl } from '../../utils.js'
 
 export function load({ runtime, entity, state, options, track }) {
     runtime.resource = (url) => {
@@ -17,8 +17,7 @@ export function load({ runtime, entity, state, options, track }) {
                 // than resolving one, so a library that was never copied
                 // yields a link to nothing on a green build.
                 track?.asset?.(destination)
-                const from = path.dirname(entity.destination || '/')
-                return { url: path.relative(from, destination), name }
+                return { url: siteRelativeUrl(entity.destination, destination, options?.siteRoots), name }
             }
         }
     }

package/src/references.js

@@ -25,6 +25,7 @@ import path from 'node:path'
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { globby } from 'globby'
+import { siteRootFor } from './utils.js'
 
 // Documents that can carry a reference. Anything else in the output is either
 // an asset itself or something whose internal structure this has no business
@@ -82,6 +83,8 @@ function decodeEntities(source) {
 }
 
 // Everything a page points at, as raw url strings.
+export { siteRootFor }
+
 export function extractReferences(rawSource) {
     const source = decodeEntities(rawSource)
     const found = new Set()
@@ -111,30 +114,17 @@ export function resolveUrl(pageDir, url, { root = '' } = {}) {
     const segments = clean.split('/').filter(s => s !== '' && s !== '.')
 
     const parts = absolute ? [] : pageDir.split('/').filter(Boolean)
-    let overDeep = false
+    // How FAR above the root it climbed, not merely that it did. When every
+    // over-deep url on a site climbs the same distance, that is one base
+    // mismatch reported once — not N findings, which is how a real signal gets
+    // filtered.
+    let floored = 0
     for (const segment of segments) {
         if (segment !== '..') { parts.push(segment); continue }
         if (parts.length) parts.pop()
-        else overDeep = true      // a climb above the root, floored
-    }
-    return { target: path.join(root, ...parts), overDeep }
-}
-
-// Which declared site root a file belongs to.
-//
-// lmed emits one subtree per language and deploys each as its own domain root
-// (out/bg becomes lmed.bg), so the site root is out/<lang>/ and every url
-// carries one extra `..` for the language segment that the browser then floors.
-// Resolving against the output root instead would miss the over-escape entirely
-// and report working urls as broken. Nothing can derive this — it is deployment
-// intent — so it is declared, and the default is the output root itself.
-export function siteRootFor(relativeFile, roots) {
-    let best = ''
-    for (const root of roots) {
-        if (!root) continue
-        if (relativeFile.startsWith(`${root}/`) && root.length > best.length) best = root
+        else floored++            // a climb above the root, discarded
     }
-    return best
+    return { target: path.join(root, ...parts), overDeep: floored > 0, floored }
 }
 
 // Everything the output points at that is not there.
@@ -150,7 +140,7 @@ export async function checkReferences(outputFolder, { siteRoots = [] } = {}) {
     })
 
     const broken = new Map()
-    const overDeep = new Map()
+    const overDeepRefs = new Map()
     let checked = 0
     // Existence is the expensive part and the same target repeats across a
     // site — one lookup each.
@@ -166,7 +156,7 @@ export async function checkReferences(outputFolder, { siteRoots = [] } = {}) {
         const pageDir = path.dirname(file).slice(root.length).replace(/^\/+/, '')
 
         for (const url of extractReferences(source)) {
-            const { target, overDeep: floored } = resolveUrl(pageDir, url, { root })
+            const { target, overDeep, floored } = resolveUrl(pageDir, url, { root })
             checked++
 
             if (!exists.has(target)) {
@@ -174,14 +164,14 @@ export async function checkReferences(outputFolder, { siteRoots = [] } = {}) {
             }
             // Broken outranks over-deep: a url that resolves nowhere is the
             // failure, and adding that it is also one level too deep is noise.
-            const bucket = !exists.get(target) ? broken : (floored ? overDeep : null)
+            const bucket = !exists.get(target) ? broken : (overDeep ? overDeepRefs : null)
             if (!bucket) continue
 
             const key = `${target} ${url}`
-            if (!bucket.has(key)) bucket.set(key, { url, target, files: [] })
+            if (!bucket.has(key)) bucket.set(key, { url, target, floored, files: [] })
             bucket.get(key).files.push(file)
         }
     }
 
-    return { broken: [...broken.values()], overDeep: [...overDeep.values()], checked }
+    return { broken: [...broken.values()], overDeep: [...overDeepRefs.values()], checked }
 }

package/src/utils.js

@@ -1343,3 +1343,50 @@ export function matchesLibrary(value, pattern) {
     }
     return libraryPatterns.get(pattern).test(value)
 }
+
+// Which declared site root a path belongs to.
+//
+// A build can emit one subtree per language and deploy each as its own domain
+// root, which puts the site root at out/<lang>/ rather than at out/. Nothing
+// can derive that — it is a fact about where the bytes get deployed, not about
+// the bytes — so it is declared as `siteRoots` and the default is the output
+// root itself. Accepts a path with or without a leading slash, because an
+// entity destination has one and an output-relative file path does not.
+export function siteRootFor(file, roots = []) {
+    const relative = String(file ?? '').replace(/^\/+/, '')
+    let best = ''
+    for (const root of roots) {
+        if (!root) continue
+        if (relative.startsWith(`${root}/`) && root.length > best.length) best = root
+    }
+    return best
+}
+
+// A page-relative url from one output destination to another, addressed within
+// the site the page belongs to.
+//
+// Both are output-root absolute (`/bg/aparati/index.html`, `/derived/x.webp`),
+// which is the only shape the engine has. With one site per build that is also
+// the deployed root and this is a plain path.relative. With several, it is not:
+// out/bg IS the domain root, so a url computed against out/ carries one extra
+// `..` for the language segment. The browser floors that rather than failing,
+// which is why it worked and why nothing said so.
+//
+// Three cases, and the middle one is the reason this is not a one-liner:
+//
+//   target outside every root   a shared asset. It has to be reachable from
+//                               inside this page's site, so it is addressed
+//                               there — this is the case that was wrong.
+//   target in the same root     already correct; a plain relative path.
+//   target in a DIFFERENT root  a cross-site link. On a per-domain deploy the
+//                               other site is another origin and no relative
+//                               path reaches it. Left as it was, so the
+//                               reference check reports it broken instead of
+//                               this silently inventing a path that is not.
+export function siteRelativeUrl(pageDestination, target, siteRoots = []) {
+    const from = path.dirname(pageDestination || '/')
+    const pageRoot = siteRootFor(pageDestination, siteRoots)
+    if (!pageRoot) return path.relative(from, target)
+    if (siteRootFor(target, siteRoots)) return path.relative(from, target)
+    return path.relative(from, path.join('/', pageRoot, target))
+}

package/10.0-PLAN.md

@@ -1,182 +0,0 @@
-# Mikser 10.0 — Planning (stub)
-
-**The shift in one line:** scale moves from "make one mikser hold more" to "compose more miksers." A new coordination layer ships as `party-mikser-io` — separate package, separate ADR series, separate release cadence. `mikser-io` itself stays single-instance-pure.
-
-This is a v10 placeholder — direction-setting, not a finished design. The hard pieces (cross-mikser refs, discovery, partition behavior) get worked out as `party-mikser-io` takes shape. This file gets dropped at release; the surviving decisions become ADRs.
-
-## The gate: v9 has to pay out first
-
-**No v10 work begins until v9 is incorporated into our own daily work and the workflow pays out.** Not "v9 has shipped." Not "v9 has been tested." **Used, daily, for our own real work, until the format-liberation pitch is something we'd defend with our own time.**
-
-This is the strongest gate in the roadmap. It exists because the v10 architecture is more interesting to build than the v9 documentation is to write, and that asymmetry kills projects with strong substrates. The discipline is to refuse v10 design work — even thinking about it as an escape — until v9 has earned the next layer through real use.
-
-What "pays out" means operationally — concrete signals to watch:
-
-| signal | reading |
-|---|---|
-| New work naturally flows into mikser, not into "I should mikser-ize this later" | ✅ working |
-| You stop wanting to switch back to your previous setup | ✅ working |
-| The format-liberation flows (PDF in → CSV out, CSV in → HTML out) are things you actually run, not just demos | ✅ working |
-| The MCP agent integration makes daily work faster, not just possible | ✅ working |
-| Watch-mode + incremental rebuild holds up under your real editing patterns | ✅ working |
-| You stop writing helper scripts that work around mikser instead of through it | ✅ working |
-| Friends/colleagues see what you have running and ask how to use it themselves | ✅ working — the strongest signal |
-
-Failure signals — any of these means v9 hasn't paid out yet, fix before v10:
-
-| signal | reading |
-|---|---|
-| You manually run `mikser --clear` more than weekly | ❌ incremental rebuild has rough edges |
-| You keep editing files outside the mikser folder because watch-mode is slow / breaks | ❌ watch-mode regression somewhere |
-| Specific plugins break in ways that make you avoid them | ❌ plugin needs work, not v10 work |
-| You stop using MCP integration because grep is faster | ❌ MCP surface isn't carrying its weight |
-| You compose pipelines outside mikser (one-off scripts) because composing in mikser is awkward | ❌ recipe documentation or substrate ergonomics gap |
-| You don't find yourself reaching for it for new tasks | ❌ the substrate isn't actually changing how you work |
-
-When the working signals dominate over a sustained period of real use, v10 design starts. Not before.
-
-## Why v10 (not 9.x)
-
-The 9.0 design deliberately deferred mikser-to-mikser composition to v10. The reasoning:
-
-> Cross-instance concerns (discovery, peer identity, routing, cross-mikser refs, watch propagation, liveness, partition behavior, peer auth) belong to a distributed-systems substrate that iterates at "we hit a production partition bug" speed, not at engine-substrate speed. Folding any of it into `mikser-io` would re-fail ADR-0006 test #5 (release cadence) the moment it ships.
-
-v10 is the version where that substrate ships, alongside the small `mikser-io` additions that make it possible.
-
-Until then: one folder, one mikser, domain-sized catalog. That's the v9 design center, and it earns the v10 work by staying small.
-
-## The split
-
-```
-mikser-io           → single-instance substrate (unchanged from 9.0)
-party-mikser-io     → coordination layer between mikser instances
-```
-
-The repo-split check is one line: **does this code reference anything outside this mikser's `runtime`? If yes → wrong repo.** That makes ADR-0006 test #1 (substrate?) concrete for distributed code, which is otherwise ambiguous.
-
-| concern | lives in | why |
-|---|---|---|
-| Catalog / refs / manifest / journal | `mikser-io` | every mikser needs this |
-| Source plugins, render dispatch, lifecycle | `mikser-io` | same |
-| Discovery (how A finds B) | `party-mikser-io` | mikser-io never needs to know peers exist |
-| Identity (`mikser.name` as a stable handle) | `party-mikser-io` | mikser-io has no notion of "self" beyond `runtime` |
-| Routing (which mikser owns entity X) | `party-mikser-io` | local catalog queries don't ask this |
-| Cross-mikser refs (`$author` in A → entity in B) | `party-mikser-io` | refs.js stays local-graph-pure |
-| Watch propagation across instances | `party-mikser-io` | chokidar covers one folder; cross-mikser is a different transport |
-| Liveness / health / partition behavior | `party-mikser-io` | distributed-systems posture, not file-engine posture |
-| Auth / trust between peers | `party-mikser-io` | engine auth is per-endpoint; peer auth is its own model |
-
-## The metaphor
-
-A "party" — voluntary attendance, each guest brings what they own, the host knows who's there but nobody's centrally in charge.
-
-More accurate than:
-
-- **Cluster** — implies homogeneity (every node same code, same role). A photos mikser and an invoices mikser are different roles.
-- **Mesh** — implies n-to-n by default. Real parties talk to small explicit peer sets.
-- **Federation** — implies central authority or shared schema. Each mikser owns its catalog and exposes whatever shape it wants.
-
-Reads correctly at the call site:
-
-```js
-import { join } from 'party-mikser-io'
-
-await join({
-    as: 'invoices',
-    peers: [
-        { name: 'documents', url: 'http://localhost:8081' },
-        { name: 'photos',    url: 'http://localhost:8082' },
-    ],
-})
-```
-
-## What lands in `mikser-io` to support this
-
-These are the only `mikser-io` 10.0 changes — small, surgical, and they don't introduce peer-awareness into the engine. They expose information party-mikser-io needs in order to coordinate.
-
-### `mikser-io-api` surface additions
-
-Three new endpoints. None of them know about peers; they just expose what a peer would need to read.
-
-| endpoint | purpose | rough LOC |
-|---|---|---|
-| `GET /api/identity` | mikser name (from config) + version + capabilities (plugin list + their versions) | ~20 |
-| `GET /api/checkpoint` | current catalog snapshot id (for partition-recovery sync) | ~30 |
-| `GET /api/refs/:id?direction=in|out` | inbound or outbound refs for an entity | ~40 |
-
-The `subscribe` endpoint also gains a `?since=<checkpoint>` query param for replay-on-reconnect. ~20 LOC.
-
-Total: ~110 LOC of additive endpoints. Nothing existing changes. Each one is independently testable.
-
-### `mikser.config.js` gets a `name` field
-
-```js
-export default {
-    name: 'invoices',   // stable identifier; used by /api/identity and party.join({as})
-    plugins: [...],
-}
-```
-
-Engine reads it, exposes via `runtime.name`. Default falls back to the working folder's basename. That's it — `mikser-io` doesn't act on it; party-mikser-io does.
-
-## What `party-mikser-io` ships in 10.0
-
-Not designing this in detail yet — the design happens as the package gets built. The shape at this stage is:
-
-1. **`join(config)`** — handshake with each declared peer via `/api/identity`. Verifies peer is reachable and reports name/capabilities.
-2. **`runtime.options.party.peers`** — map of peer name → metadata. Available to plugins after join completes.
-3. **`mikser-io-source-party`** — source plugin: mounts a peer's `/api` SSE feed as a local collection. Live-reload via the existing subscribe semantics.
-4. **Cross-mikser ref resolution** — `$author@documents` syntax (entity id + peer name). Resolution proxies through the source-party plugin's mirrored cache. **Design call deferred** to first implementation pass.
-5. **Liveness checks** — periodic `/api/checkpoint` poll per peer. Stale peers logged but don't break the build (their entities go cold; resync on reconnect).
-
-## Open questions (working proposals at v10 design time)
-
-1. **Cross-mikser ref shape — mirror or proxy?**
-   - (a) Mirror: source-party plugin pulls all peer entities into local catalog. Refs resolve locally. Cost: memory grows with peer corpus size.
-   - (b) Proxy: refs resolve via HTTP at lookup time. Cost: latency on every render that touches a cross-mikser ref.
-   - Working proposal: **mirror with TTL** — pull peer entities lazily on first ref, cache with checkpoint-based invalidation. Worst-case memory is bounded by what's actually referenced.
-
-2. **Discovery mechanism.**
-   - Config-pinned peer URLs (the snippet above) for v10. Anything more (mDNS, registry, DNS-SD) lives in 10.x or 11.0 after we see what real deployments need. Working proposal: **explicit URLs only for v10.**
-
-3. **Authentication between peers.**
-   - The api plugin already supports per-endpoint tokens. Reuse that: each peer in `join()` config carries a token. Working proposal: **bearer token per peer, configured in `join()`.**
-
-4. **What if two peers claim entities with the same id?**
-   - The fully-qualified form is `id@peer-name`. Local entities have no `@`. Working proposal: **namespacing by peer name avoids collision entirely** — cross-mikser refs always carry the peer name.
-
-5. **What about cycles?**
-   - A subscribes to B, B subscribes to A. Working proposal: **explicitly allowed**. Each side mirrors the other; the checkpoint mechanism prevents replay loops.
-
-## Out of scope for 10.0
-
-- **Write-across-peers** — `party.create(entity, { in: 'invoices' })` from peer A creating an entity in peer B's catalog. Probably 10.x or 11.0. Single-direction read is enough to validate the architecture.
-- **Distributed consensus / conflict resolution** — each peer owns its catalog, period. Nobody writes to anyone else's.
-- **Replication / HA** — that's a different problem. A party isn't a cluster; if a peer goes down, its entities go cold, not get failed-over.
-- **Plugin marketplace / discovery service** — same answer as 9.0. Not building this.
-
-## ADR series
-
-`party-mikser-io` gets its own decision log under `party-mikser-io/documentation/decisions/`, starting from 0001. Not extending the `mikser-io` ADR series — keeps the substrate test (#1) clean. `mikser-io` ADRs cover the single-instance engine; `party-mikser-io` ADRs cover the coordination plane.
-
-Cross-references between the two ADR series are fine; the boundary stays at "does this code reference anything outside this mikser's `runtime`?"
-
-## Concretely, what work this is (rough order)
-
-1. **`mikser-io` engine** — add `runtime.name` (read from `mikser.config.js`). One file change.
-2. **`mikser-io-api`** — add `/api/identity`, `/api/checkpoint`, `/api/refs/:id`, and `?since=` on subscribe. ~110 LOC.
-3. **`party-mikser-io`** — new repo. `join()`, peer registry, liveness loop. The boring substrate of the coordination layer. ~400 LOC.
-4. **`mikser-io-source-party`** — new repo (or sub-package). Source plugin that mounts a peer's catalog. The mirror cache + checkpoint invalidation logic. ~300 LOC.
-5. **Cross-mikser ref resolution** — extends `mikser-io-source-party`. Parses `id@peer` syntax in `$`-refs and resolves through the mirror. ~150 LOC.
-6. **Recipe documentation** — README composition examples: PDF mikser + CSV mikser + HTML mikser, piped together. The example that proves the v10 pitch works end-to-end.
-7. **`mikser-io-example-party`** — new example repo. Three miksers in one repo (subfolders), each with its own config, demonstrating the full composition.
-
-Items 1-2 ship in `mikser-io` 10.0 itself. Items 3-7 are the v10 ecosystem release.
-
-## What this earns us, when it lands
-
-The 9.0 pitch was "file-based knowledge substrate with AI superpowers." v10 extends that with one word: **composable**.
-
-> A file-based knowledge substrate with AI superpowers, composable across instances.
-
-The PDF-in-CSV-out-HTML-elsewhere story works as separate miksers connected through a party — not as one process trying to be everything. That's the architecture the substrate was designed for; v10 just makes it real.