@passioncode-ai/passioncode 0.1.42 → 0.1.44

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.44 - 2026-10-12
+
+### Changed
+
+- **Fabric Agent Adapter is pinned at `v0.20.0`** (it was `v0.19.0`). Fabric Agent Adapter 0.20.0 (FAA-11): runner routes in both service kits — the doctor reports each runner's state with the contract's closed probe results (not-installed, not-responding, not-connected), and a service checks a runner route, the bundle a host pins and every route event against FAC-SEM-028…034, answering the contract's own rules.
+
+## 0.1.43 - 2026-10-12
+
+### Changed
+
+- **Fabric Agent Adapter is pinned at `v0.19.0`** (it was `v0.18.0`). Fabric Agent Adapter 0.19.0 (FAA-13): both service kits keep settings backups of what the operator decided — outside the data directory, byte-identical between the kits, restored only into a fresh database and never over a row — list every spending limit a service applies in its usage report, and send the service token in the header the descriptor declares.
+
 ## 0.1.42 - 2026-10-12
 
 ### Changed

package/family.json

@@ -8,7 +8,7 @@
       "name": "fabric-agent-adapter",
       "displayName": "Fabric Agent Adapter",
       "repo": "passioncode-ai/fabric-agent-adapter",
-      "ref": "v0.18.0",
+      "ref": "v0.20.0",
       "kind": "plugin",
       "path": "plugins/fabric-agent-adapter",
       "legacyPluginIds": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/passioncode",
-  "version": "0.1.42",
+  "version": "0.1.44",
   "description": "The PassionCode.ai agent skill set \u2014 Fabric Agent Adapter, Observatory Log and the organisation's working rules \u2014 for Claude Code and every other agent on the machine, updated as one set.",
   "bin": {
     "passioncode": "bin/passioncode.js"

package/payload/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "fabric-agent-adapter",
       "displayName": "Fabric Agent Adapter",
       "source": "./plugins/fabric-agent-adapter",
-      "version": "0.18.0",
+      "version": "0.20.0",
       "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles.",
       "author": {
         "name": "PassionCode.ai",
@@ -35,7 +35,7 @@
       "name": "passioncode",
       "displayName": "PassionCode.ai",
       "source": "./plugins/passioncode",
-      "version": "0.1.42",
+      "version": "0.1.44",
       "description": "The organisation's working rules for every contributor's agent (working-in-passioncode), and a once-a-day check that keeps the PassionCode.ai set current.",
       "author": {
         "name": "PassionCode.ai",

package/payload/manifest.json

@@ -1,15 +1,15 @@
 {
   "family": "passioncode",
-  "version": "0.1.42",
+  "version": "0.1.44",
   "release": true,
   "members": [
     {
       "name": "fabric-agent-adapter",
       "displayName": "Fabric Agent Adapter",
       "repo": "passioncode-ai/fabric-agent-adapter",
-      "ref": "v0.18.0",
-      "commit": "10a8d65bb28c3eb6d0bf2d839b53efb340e42f9d",
-      "version": "0.18.0",
+      "ref": "v0.20.0",
+      "commit": "925d052d682572dc4ba60a7e1dea3da5a77a4de7",
+      "version": "0.20.0",
       "via": "clone of https://***@github.com/passioncode-ai/fabric-agent-adapter.git",
       "skills": [
         "adapting-projects-to-fabric",
@@ -22,7 +22,7 @@
       "legacyMarketplaces": [
         "fabric-agent-adapter"
       ],
-      "contentHash": "sha256:bf6c40c50d4c5c4ca165191ae0ce0c5edfcb7744729b8384fd75c5b921331b05",
+      "contentHash": "sha256:9ae4b03e68e22f96174fff64430c47a7d575471efc5d0303560c4eed9adec038",
       "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles.",
       "author": {
         "name": "PassionCode.ai",
@@ -61,16 +61,16 @@
       "name": "passioncode",
       "displayName": "PassionCode.ai",
       "repo": "passioncode-ai/passioncode",
-      "ref": "v0.1.42",
+      "ref": "v0.1.44",
       "commit": null,
-      "version": "0.1.42",
+      "version": "0.1.44",
       "via": "this repository",
       "skills": [
         "working-in-passioncode"
       ],
       "legacyPluginIds": [],
       "legacyMarketplaces": [],
-      "contentHash": "sha256:44d408186f1bbeec38fd7d033b0141ee9b581cdc4dc9dc64a96938df288c15e9",
+      "contentHash": "sha256:209f32cdc3656684b3622173cfc630add724f38d50bb9d9c3d80d57f926f6981",
       "description": "The organisation's working rules for every contributor's agent (working-in-passioncode), and a once-a-day check that keeps the PassionCode.ai set current.",
       "author": {
         "name": "PassionCode.ai",

package/payload/plugins/fabric-agent-adapter/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "fabric-agent-adapter",
   "displayName": "Fabric Agent Adapter",
   "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles.",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

package/payload/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/SKILL.md

@@ -5,7 +5,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode.
 metadata:
   author: PassionCode.ai
-  version: "0.18.0"
+  version: "0.20.0"
   contract-version: "0.1.0"
   contract-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"
 ---

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/SKILL.md

@@ -16,7 +16,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Python 3.9+ or Node.js 20+ for the kits; the probe needs Python 3.9+. launchd steps are macOS-only; Linux services install a systemd user unit and Windows ones a per-user Scheduled Task with the kits' writers. Dashboard handoff optionally uses Fabric Dashboards MCP link/host_status/open; without it, report unresolved host capability. The contract checkout is optional.
 metadata:
   author: PassionCode.ai
-  version: "0.18.0"
+  version: "0.20.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"
@@ -84,7 +84,8 @@ are in [`scripts/fabric_interop.py`](scripts/fabric_interop.py) and
 service checks each call's delegation token (DEC-0039): read [the delegation reference](references/delegation.md);
 the verifier is [`scripts/fabric_delegation.py`](scripts/fabric_delegation.py) /
 [`scripts/fabric-delegation.mjs`](scripts/fabric-delegation.mjs). When Fabric chooses the service's runner and models
-(DEC-0046), read [the profiles reference](references/profiles.md).
+(DEC-0046), or a project routes its work through an ordered list of runners (DEC-0026: the doctor's closed probe
+results, the route checks FAC-SEM-028…034), read [the profiles reference](references/profiles.md).
 
 ## Step 2 — the non-negotiables
 
@@ -228,8 +229,12 @@ log, retention and notification policy.
 
 An agent that calls paid models reports **what it spent**: one receipt per call from the
 provider's own usage numbers, served behind the token at `surfaces.usage` as the DEC-0021 usage
-report. An unknown cost is null, never 0. Read [the usage reference](references/usage.md)
-before wiring it.
+report. An unknown cost is null, never 0. It lists **every** spending limit the service applies
+in `budgets`, enforced or not. Read [the usage reference](references/usage.md) before wiring it.
+
+A service whose store holds what the operator decided keeps **settings backups** outside its data
+directory, restores only on a fresh database and never overwrites. Read
+[the settings backups reference](references/settings-backups.md).
 
 ## Step 6 — verify
 

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/references/events-and-notifications.md

@@ -11,6 +11,15 @@
 
 The feed is a view: never copy rows into a second store that can drift from the first.
 
+## Reading a feed (FAC-SEM-036)
+
+A client of `GET /fabric/v1/events` — or of any token-protected route — sends the token in the
+header the descriptor's `auth.header` names, in the form `auth.scheme` names: the raw token for
+`none`, `Bearer <token>` for `Bearer`. Never assume `Authorization: Bearer`: a client that did
+was refused on every poll and silently dropped every notify event. `token_header(auth, token)` /
+`tokenHeader(auth, token)` gives the one header; the token never travels in another header or
+in the URL.
+
 ## Writing an event
 
 - `kind`: dotted, stable, past tense or state (`job.failed`, `job.awaiting_choice`,

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/references/lifecycle.md

@@ -88,6 +88,7 @@ remove; the back-off only stops the loop from costing the machine.
 | logs | `~/Library/Logs/<id>/` | `${XDG_STATE_HOME:-~/.local/state}/<id>/logs/` | `%LOCALAPPDATA%\<id>\Logs\` |
 | cache (deletable any time) | `~/Library/Caches/<id>/` | `${XDG_CACHE_HOME:-~/.cache}/<id>/` | `%LOCALAPPDATA%\<id>\Cache\` |
 | code | `~/.local/share/<id>/releases/…` | same | under `%LOCALAPPDATA%` too, never a network share |
+| settings backups ([DEC-0025](settings-backups.md)) | `~/Library/Application Support/PassionCode/settings-backups/<id>/<instance>/` | `${XDG_CONFIG_HOME:-~/.config}/PassionCode/settings-backups/…` | `%APPDATA%\PassionCode\settings-backups\…` |
 
 A repository that versions the data itself (a registry, a plan) may hold the data; the
 service's own code checkout and its releases may not. Directories 0700, secret files 0600. A store carries a schema version and the service

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/references/profiles.md

@@ -13,6 +13,7 @@ Python: [`scripts/fabric_profiles.py`](../scripts/fabric_profiles.py); Node:
 - Checking the documents
 - Declaring and showing what applies
 - The doctor
+- Runner routes
 - Usage by route
 
 ## Resolving the model profile
@@ -58,6 +59,28 @@ catalogued binary found on `PATH`, only with the catalogued version argv (and `a
 the entry's timeout (at most 5 s); an entry outside these rules is refused and nothing runs. `model_usable(model,
 catalogue, policy)` names why a model cannot be used here: not catalogued, or a class the project does not allow.
 
+`probe` is the contract's closed probe result for that runner, the one Fabric's walk records (DEC-0026):
+`not-installed` (no catalogued binary on `PATH`), `not-responding` (the version probe did not answer in its bound,
+failed or did not match the catalogue's pattern, or the `auth` probe did not answer), `not-connected` (it answers but
+the `auth` probe says signed out), or `None`/`null` when the runner can serve. The order is the walk's: installed,
+then responding, then connected. `problems` still names every problem the doctor found.
+
+## Runner routes
+
+A project may pin a **runner route** (DEC-0026, DEC-0029, `runners.md` §"Runner routes"): the ordered terminal agents
+that serve one capability, each with a session policy (`attach`, `spawn`), what happens when all are unavailable
+(`exhausted`) and whether a conversation returns to a preferred runner (`recovery`). Fabric walks it; a service that
+pins, records or shows routes checks them with `route_problems(kind, value)` / `routeProblems(kind, value)`, the
+contract's `routeRules` finding for finding:
+
+| `kind` | value | rules |
+|---|---|---|
+| `runner-route` | the route | one candidate per runner kind (FAC-SEM-028); a candidate can attach or spawn (029) |
+| `route-bundle` | `{route, admissions, binding?, catalogue?}` | every candidate's provider revision admitted for the capability by id, revision and hash (030); the binding agrees — project, capability, local-runner, a candidate as provider, this route as `runnerRoute` (032); every kind and named drive is in the runner catalogue (033) |
+| `route-event` | `{route, event}` | the event names this route, project and capability; candidates by position; the probes cover every candidate above the selection in order (all for an exhausted walk, none for a sticky relaunch); attach, spawn, `no-held-session` and `spawn-failed` obey the session policy; `held` only under `exhausted: hold`; `preferred-available` only under `recovery: reprobe`, moving up (034) |
+
+A probe result in an event is one of `PROBE_RESULTS`; a host never appends a runner the route does not name.
+
 ## Usage by route
 
 `make_usage_receipt(..., route="subscription"|"key")` records how the call was paid — the operator's own login in its

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/references/settings-backups.md

@@ -0,0 +1,67 @@
+# Settings backups — what the operator decided survives the data directory (DEC-0025)
+
+Fabric Agent Contract DEC-0025, `docs/specification/service.md` → *Settings backup*, schema
+`schemas/settings-backup.schema.json`, rule `FAC-SEM-035`. A service whose store holds what the operator
+decided — which projects it serves, how each is bound, which secret slot each binding uses, their overrides —
+SHOULD keep settings backups, so a lost, purged or wrongly migrated data directory costs the operator nothing.
+
+## Where
+
+`<root>/settings-backups/<id>/<instance>/settings-<UTC %Y%m%dT%H%M%S%fZ>.json`, outside the data directory:
+
+| System | `<root>` (`settings_backup_root` / `settingsBackupRoot`) |
+|---|---|
+| macOS | `~/Library/Application Support/PassionCode` |
+| Windows | `%APPDATA%\PassionCode` |
+| Linux | `$XDG_CONFIG_HOME/PassionCode`, default `~/.config/PassionCode` |
+
+`settings_backup_dir(id, instance)` / `settingsBackupDir(id, instance)` names the folder. Directories are 0700
+(on Windows a protected ACL), files 0600, writes atomic.
+
+## Take a snapshot
+
+```python
+dirs = fs.settings_backup_dir(ID, INSTANCE)
+if fs.backup_due(dirs):                                   # none yet, or the newest is older than 24 hours
+    doc = fs.make_settings_backup(service_id=ID, instance=INSTANCE, version=VERSION, schema=SCHEMA_VERSION,
+                                  tables=allow_listed_tables(db), reason="start")      # or daily, uninstall, manual
+    fs.write_settings_backup(doc, dirs)                   # None when unchanged; keeps the 14 newest
+```
+
+```js
+const dir = k.settingsBackupDir(ID, INSTANCE);
+if (k.backupDue(dir)) k.writeSettingsBackup(k.makeSettingsBackup({ id: ID, instance: INSTANCE, version, schema, tables, reason: 'daily' }), dir);
+```
+
+- **Tables on an allow-list**, each `{"columns": [...], "rows": [[...], ...]}` of JSON scalars. A fraction is its
+  decimal string (`"0.25"`), binary data is never stored, and an integer stays within ±(2^53 − 1).
+- **Secrets by name only.** `make_settings_backup` refuses a table that can only hold connections, tokens,
+  secrets, credentials, passwords, login codes or sessions, and a column whose name says it holds a credential
+  value (`access_token`, `client_secret`); `secret_name` and `token_slot` pass. The names cannot see values, so
+  back up what is on the allow-list, never everything except a deny-list.
+- **When:** at start when `backup_due`, then daily; on uninstall a last one, read-only (open the store without
+  migrating or writing). An unchanged snapshot is not rewritten; a temporary file an interrupted write left is
+  removed first. A fresh, empty database writes none: it would hide the good snapshot before it is restored.
+- Both kits write byte-identical files (`test/fabric-service-backups.test.mjs`, last case).
+
+## Read and restore
+
+`read_settings_backup` / `readSettingsBackup` refuses a file whose checksum, counts or row widths disagree with
+its tables, that carries a value with no canonical form, or whose `format` it does not know, naming why
+(`FAC-SEM-035`). The checksum is SHA-256 of the settings canonical form of `tables`
+(`settings_canonical_json` / `settingsCanonicalJson`: Python's `json.dumps(sort_keys=True,
+ensure_ascii=False)`).
+
+Restore **adds and never overwrites**:
+
+```python
+path, doc, skipped = fs.newest_intact_backup(dirs)        # the newest intact snapshot with content; damaged ones named
+plan = fs.restore_plan(doc, {"projects": {"columns": [...], "key": ["id"], "required": ["id", "name"],
+                                          "existing": existing_keys("projects")}})
+# plan["tables"]["projects"]: insert, present, droppedColumns, defaultedColumns, missingRequired, refused
+```
+
+- **Automatic restore** only on a *fresh* database — no domain records **and** the service has never started —
+  so a restart never undoes a deletion. Insert `plan[...]["insert"]` and add every row the database refuses to
+  `refused` with its key and reason.
+- **Manual restore** shows the plan first; applying it is the operator's act, never an agent's.

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/references/usage.md

@@ -50,6 +50,29 @@ left out.
 **Budget.** Pass `budget` only if the service **enforces** that limit itself. The report states
 it, and the host only shows it.
 
+**Every limit (DEC-0027).** Pass `budgets` to list every spending limit the service applies,
+enforced or not, so the spend view shows all of them — the operator asked for that on 2026-10-07:
+
+```python
+ledger.report(service_id=ID, budget={"period": "month", "limitUsd": 100}, budgets=[
+    {"id": "machine.monthly", "scope": "machine", "kind": "monthly", "period": "month", "limitUsd": 100, "enforced": True},
+    {"id": "project.demo.daily", "scope": "project", "subject": "demo", "kind": "daily", "windowSeconds": 86400,
+     "limitUsd": 5, "spentUsd": 0.31, "enforced": True},
+    {"id": "job.cap", "scope": "job", "kind": "per_job", "limitUsd": 2, "enforced": True},
+])
+```
+
+- A machine limit with a `period` and no `spentUsd` is counted by the kit from the receipts, the
+  way `budget` is, so `budget` and its twin in `budgets` never disagree. A per-order limit
+  (`per_job`, `approval`) gets `spentUsd: null`. Every other limit states its own spend.
+- `scope` is `machine`, `project`, `pool` or `job`; a `project` or `pool` limit names its
+  `subject`. A limit has at most one window — `period`, `windowSeconds` or `since` — and it agrees
+  with the kind (`daily`: the day or 86400 s; `monthly`: the month or 28–31 days; `velocity`: a
+  rolling window). `tripped: true` (work stopped by it now) needs `enforced: true`. An unknown
+  kind is shown generically, never refused.
+- The kits refuse a report that breaks these (`usage_limit_problems` / `usageLimitProblems`,
+  `FAC-SEM-031`). A breach is not refused: the report shows it, and the host shows it first.
+
 Call `ledger.prune()` at start (or daily) to keep the file at the reported window (LC-12).
 
 `JsonlUsageLedger` appends 0600 JSON lines. A line torn by a killed writer is skipped, and the

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/check_service.py

@@ -162,10 +162,9 @@ class Probe:
             conn.close()
 
     def auth_headers(self) -> Dict[str, str]:
-        auth = self.d.get("auth", {})
-        header = auth.get("header", "Authorization")
-        value = self.token or ""
-        return {header: ("Bearer " + value) if auth.get("scheme", "Bearer") == "Bearer" else value}
+        # The header and form the descriptor declares, never an assumed `Authorization: Bearer` (FAC-SEM-036).
+        name, value = fs.token_header(self.d.get("auth"), self.token or "")
+        return {name: value}
 
     # descriptor ------------------------------------------------------------
     def descriptor_rules(self) -> None:

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-profiles.mjs

@@ -126,6 +126,10 @@ function which(name, searchPath) {
  * runners.md C2: is the catalogued runner installed, which version answers, and is it signed in. Only a bare
  * catalogued binary on PATH is run, only with the catalogued version (and auth) argv, without a shell, within its
  * timeout (at most 5 s). An entry outside these rules is refused and nothing runs.
+ *
+ * `probe` is the contract's closed probe result for a walk (DEC-0026): `not-installed`, `not-responding` (the version
+ * probe did not answer, failed or did not match), `not-connected` (signed out by the `auth` probe), or null when the
+ * runner can serve. The twin of fabric_profiles.runner_check.
  */
 export function runnerCheck(entry, { searchPath = process.env.PATH, run = spawnSync } = {}) {
   const { kind, binaries } = entry ?? {};
@@ -136,10 +140,10 @@ export function runnerCheck(entry, { searchPath = process.env.PATH, run = spawnS
   const timeoutMs = version.timeoutMs ?? MAX_PROBE_MS;
   if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_PROBE_MS) throw new ProfileError(`version.timeoutMs is at most ${MAX_PROBE_MS}`);
   const authArgv = 'auth' in entry ? argvOf(entry.auth, 'auth') : null;
-  const out = { kind, installed: false, binary: null, version: null, signedIn: null, problems: [] };
+  const out = { kind, installed: false, binary: null, version: null, signedIn: null, probe: 'not-installed', problems: [] };
   const binary = binaries.map((name) => which(name, searchPath)).find(Boolean) ?? null;
   if (!binary) { out.problems.push(`${kind} is not installed: none of ${binaries.join(', ')} is on PATH`); return out; }
-  Object.assign(out, { installed: true, binary });
+  Object.assign(out, { installed: true, binary, probe: 'not-responding' });
   const probe = (argv) => {
     const result = run(binary, argv, { encoding: 'utf8', timeout: timeoutMs, shell: false });
     if (result.error?.code === 'ETIMEDOUT' || result.signal === 'SIGTERM') { out.problems.push(`${kind} ${argv.join(' ')} did not answer within ${timeoutMs} ms`); return null; }
@@ -153,10 +157,12 @@ export function runnerCheck(entry, { searchPath = process.env.PATH, run = spawnS
     if (match && match.length > 1) out.version = match[1];
     else out.problems.push(`${kind} answered, but its version did not match the catalogue's pattern`);
   }
-  if (authArgv) {
-    const signed = probe(authArgv);
-    if (signed) { out.signedIn = signed.status === 0; if (!out.signedIn) out.problems.push(`${kind} is installed but not signed in`); }
-  }
+  const signed = authArgv ? probe(authArgv) : null;
+  if (signed) { out.signedIn = signed.status === 0; if (!out.signedIn) out.problems.push(`${kind} is installed but not signed in`); }
+  // The walk's order (runners.md): installed, then responding, then connected. The doctor still reports every problem.
+  if (out.version === null || (authArgv && !signed)) out.probe = 'not-responding';
+  else if (out.signedIn === false) out.probe = 'not-connected';
+  else out.probe = null;
   return out;
 }
 
@@ -194,3 +200,131 @@ export function configurationSummary(doc) {
   if (resolved.modelProfile) tiles.push({ label: 'Model', value: [resolved.modelProfile, (resolved.models ?? [])[0]].filter(Boolean).join(' · ') });
   return tiles;
 }
+
+// ---- runner routes (DEC-0026, DEC-0029; FAC-SEM-028…034) ----
+// The contract's routeRules (src/route-rules.ts), finding for finding: code, path and message. The twin of
+// fabric_profiles.route_problems.
+
+/** The closed probe results a walk records for a candidate it passed over (runner-route-event.schema.json). */
+export const PROBE_RESULTS = Object.freeze(['not-catalogued', 'not-admitted', 'not-installed', 'not-responding', 'not-connected', 'no-held-session', 'quota-unknown', 'refused', 'spawn-failed']);
+
+const routeCandidates = (value) => (Array.isArray(value?.candidates) ? value.candidates.filter(isObject) : []);
+const objectAt = (value, key) => (isObject(value?.[key]) ? value[key] : {});
+const refKey = (ref) => (isObject(ref) ? `${String(ref.id)}@${String(ref.revision)}#${String(ref.contentHash)}` : '');
+const sameRef = (a, b) => refKey(a) !== '' && refKey(a) === refKey(b);
+
+function runnerRoute(value) {
+  const findings = [];
+  const kinds = new Set();
+  routeCandidates(value).forEach((candidate, index) => {
+    const kind = String(candidate.runnerKind);
+    if (kinds.has(kind)) findings.push(finding('FAC-SEM-028', `/candidates/${index}/runnerKind`, `runner kind ${kind} appears in the route more than once`));
+    kinds.add(kind);
+    const session = objectAt(candidate, 'session');
+    if (session.attach === 'never' && session.spawn === 'never') findings.push(finding('FAC-SEM-029', `/candidates/${index}/session`, `candidate ${kind} can never run: attach and spawn are both "never"`));
+  });
+  return findings;
+}
+
+function routeBundle(value) {
+  const route = objectAt(value, 'route');
+  const admissions = Array.isArray(value.admissions) ? value.admissions.filter(isObject) : [];
+  const admitted = new Set(admissions.filter((a) => a.state === 'admitted' && a.capability === route.capability).map((a) => refKey(a.provider)));
+  const findings = [];
+  routeCandidates(route).forEach((candidate, index) => {
+    const key = refKey(candidate.provider);
+    if (!admitted.has(key)) findings.push(finding('FAC-SEM-030', `/route/candidates/${index}/provider`, `candidate ${String(candidate.runnerKind)} names provider ${key}, which is not a revision admitted for ${String(route.capability)}`));
+  });
+  if (isObject(value.binding)) {
+    const binding = value.binding;
+    const disagree = (where, message) => findings.push(finding('FAC-SEM-032', `/binding/${where}`, message));
+    if (binding.project !== route.project) disagree('project', `the binding is for ${String(binding.project)}, the route for ${String(route.project)}`);
+    if (binding.capability !== route.capability) disagree('capability', `the binding binds ${String(binding.capability)}, the route orders ${String(route.capability)}`);
+    if (binding.profileKind !== 'local-runner') disagree('profileKind', `a runner route serves the local-runner profile, not ${String(binding.profileKind)}`);
+    if (!routeCandidates(route).some((c) => sameRef(c.provider, binding.provider))) disagree('provider', `the binding's provider ${refKey(binding.provider)} is not a candidate of the route`);
+    if (binding.runnerRoute !== undefined && !sameRef(binding.runnerRoute, route.meta)) disagree('runnerRoute', `the binding pins ${refKey(binding.runnerRoute)}, not this route ${refKey(route.meta)}`);
+  }
+  if (Array.isArray(value.catalogue)) {
+    const byKind = new Map(value.catalogue.filter(isObject).map((entry) => [String(entry.kind), entry]));
+    routeCandidates(route).forEach((candidate, index) => {
+      const kind = String(candidate.runnerKind);
+      const entry = byKind.get(kind);
+      if (!entry) { findings.push(finding('FAC-SEM-033', `/route/candidates/${index}/runnerKind`, `runner kind ${kind} has no entry in the host's catalogue`)); return; }
+      if (candidate.drive !== undefined && !Object.hasOwn(objectAt(entry, 'drives'), String(candidate.drive))) findings.push(finding('FAC-SEM-033', `/route/candidates/${index}/drive`, `the catalogue entry for ${kind} offers no drive ${String(candidate.drive)}`));
+    });
+  }
+  return findings;
+}
+
+function routeEvent(value) {
+  const route = objectAt(value, 'route');
+  const event = objectAt(value, 'event');
+  const list = routeCandidates(route);
+  const findings = [];
+  const wrong = (where, message) => findings.push(finding('FAC-SEM-034', `/event${where}`, message));
+  if (!sameRef(event.route, route.meta)) wrong('/route', `the event names route ${refKey(event.route)}, not ${refKey(route.meta)}`);
+  if (event.project !== route.project) wrong('/project', `the event is for ${String(event.project)}, the route for ${String(route.project)}`);
+  if (event.capability !== route.capability) wrong('/capability', `the event names ${String(event.capability)}, the route orders ${String(route.capability)}`);
+  const indexOf = (ref) => (typeof ref.index === 'number' && Number.isInteger(ref.index) ? ref.index : -1);
+  const candidateAt = (ref, where) => {
+    const index = indexOf(ref);
+    const candidate = index >= 0 ? list[index] : undefined;
+    if (!candidate || candidate.runnerKind !== ref.runnerKind || (ref.provider !== undefined && !sameRef(candidate.provider, ref.provider))) {
+      wrong(where, `candidate ${String(ref.index)} (${String(ref.runnerKind)}) is not that position of the route`);
+      return undefined;
+    }
+    return candidate;
+  };
+  const probes = Array.isArray(event.probes) ? event.probes.filter(isObject) : [];
+  probes.forEach((probe, position) => {
+    const candidate = candidateAt(probe, `/probes/${position}`);
+    if (candidate && probe.result === 'no-held-session' && objectAt(candidate, 'session').spawn !== 'never') wrong(`/probes/${position}/result`, `${String(probe.runnerKind)} may spawn, so finding no held session does not pass it over`);
+    if (candidate && probe.result === 'spawn-failed' && objectAt(candidate, 'session').spawn !== 'allowed') wrong(`/probes/${position}/result`, `${String(probe.runnerKind)} has spawn: never, so it cannot have failed to spawn`);
+  });
+  const expectProbes = (count) => {
+    const indexes = probes.map(indexOf);
+    const expected = Array.from({ length: Math.max(count, 0) }, (_, index) => index);
+    if (indexes.length !== expected.length || indexes.some((index, position) => index !== expected[position])) {
+      wrong('/probes', `the walk must record candidates ${expected.join(', ') || 'none'} in order; it records ${indexes.join(', ') || 'none'}`);
+    }
+  };
+  if (event.kind === 'runner-exhausted') {
+    expectProbes(list.length);
+    if (event.answer === 'held' && route.exhausted !== 'hold') wrong('/answer', 'the route does not declare exhausted: hold, so an exhausted walk answers capability-unavailable');
+    return findings;
+  }
+  const selected = objectAt(event, 'selected');
+  const chosen = candidateAt(selected, '/selected');
+  if (chosen) {
+    const session = objectAt(chosen, 'session');
+    if (selected.session === 'attached' && session.attach !== 'preferred') wrong('/selected/session', `${String(selected.runnerKind)} has attach: never, so the host cannot attach it`);
+    if (selected.session === 'spawned' && session.spawn !== 'allowed') wrong('/selected/session', `${String(selected.runnerKind)} has spawn: never, so the host cannot spawn it`);
+    if (chosen.drive !== undefined && selected.drive !== undefined && selected.drive !== chosen.drive) wrong('/selected/drive', `the route runs ${String(selected.runnerKind)} through ${String(chosen.drive)}, not ${String(selected.drive)}`);
+    if (event.sticky === true) {
+      // A sticky relaunch keeps the conversation's runner and walks nothing above it.
+      if (route.recovery === 'reprobe') wrong('/sticky', 'a route with recovery: reprobe walks from the top at every launch');
+      if (event.conversation === undefined) wrong('/sticky', 'only a conversation can keep its runner');
+      expectProbes(0);
+    } else expectProbes(indexOf(selected));
+  }
+  if (event.kind === 'runner-switched') {
+    const from = objectAt(event, 'from');
+    candidateAt(from, '/from');
+    if (indexOf(from) === indexOf(selected)) wrong('/from', 'a switch moves to another candidate');
+    if (event.reason === 'preferred-available') {
+      if (route.recovery !== 'reprobe') wrong('/reason', 'only a route with recovery: reprobe moves a conversation back to a preferred runner');
+      if (!(indexOf(selected) < indexOf(from))) wrong('/reason', 'preferred-available moves to a higher-preference candidate');
+    }
+  }
+  return findings;
+}
+
+/**
+ * The contract's routeRules: findings for a `runner-route` (FAC-SEM-028, 029), a `route-bundle` `{route, admissions,
+ * binding?, catalogue?}` (030, 032, 033) or a `route-event` `{route, event}` (034); undefined for another kind or a
+ * value that is not an object.
+ */
+export function routeProblems(kind, value) {
+  if (!isObject(value)) return undefined;
+  return { 'runner-route': runnerRoute, 'route-bundle': routeBundle, 'route-event': routeEvent }[kind]?.(value);
+}