@twinsearth/w2m-dsh-plugin 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -4,6 +4,97 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.21.0] — 2026-10-15
+
+**The capability table has a gate now, so it is a policy rather than a description of one.**
+
+`scripts/layer-model.mjs` has declared since 0.12.0 what each operational capability costs in authority —
+`read_fleet_state` at ordinary, `dispatch_writing` at captain, `publish_release` at org admin,
+`write_config` at system admin — and **nothing consulted it**. A table nothing reads is true on the day it is
+written and unenforced afterwards; that is the same failure this project already paid for with the layering,
+where a prose description was quietly violated while nothing failed.
+
+`src/agent/permission.mjs` compares the table against `authority.mjs`'s bands and returns one of three
+verdicts. The interesting part is not `ALLOW`:
+
+### The escalation window is exactly one band
+
+`NEEDS_APPROVAL` is granted to an actor **one band below** the requirement and to nobody further down.
+`DENY` covers everything else.
+
+**Two bands below is refused rather than escalated**, and that is a security decision rather than a
+convenience one: if any shortfall could be forwarded, an ordinary actor could request a system-admin action
+and **the request itself would be the attack** — one inattentive approver away from a write to
+`allowedCommands`. One band means an actor can ask for the next thing up and no more, which is what
+"escalate to your supervisor" actually means.
+
+### An undeclared capability is DENIED
+
+Not `ALLOW`, which would make the table grant whatever is added next; not `NEEDS_APPROVAL`, which would make
+it requestable. Either would turn an **omission** into a permission. `decide('teleport', 100)` refuses, because
+authority answers *how much may this actor do*, not *is this a thing that exists*.
+
+### A level nobody defined is refused rather than rounded
+
+`50.5`, `-1`, `101`, `NaN` and `'50'` are all denied with the requirement still reported. Treating them as `0`
+would silently downgrade an actor; treating them as high would silently promote one. Neither is a decision
+this module is entitled to make.
+
+### Nothing destructive settles itself
+
+`mayAutoSettle()` returns false for any destructive capability **even on an `ALLOW` at maximum authority** —
+the level answers "may this actor", not "should this happen now". A release published on a machine's own
+judgement is a release nobody reviewed.
+
+### The table is audited, not trusted
+
+`auditCapabilities()` reports any entry **no band can reach**, because an unreachable capability reads as
+policy while doing nothing — worse than an absent one, since it looks like a control.
+
+**18 tests, 0 failures.** One property is asserted across the whole table rather than by example: for every
+declared capability and every level from 0 to 100, a `NEEDS_APPROVAL` verdict implies the actor is exactly one
+band below.
+
+## [0.20.0] — 2026-10-15
+
+**Version skew is refuted too, and the direct-path failure is now counted instead of read one at a time.**
+
+### Third hypothesis, third refutation
+
+The previous release established that this machine runs plugin **0.9.5** while the source tree is **0.19.0**,
+and that the failing `P2P_PUNCH_FAILED` is raised by the plugin process. The natural next step was to suspect a
+digest name that 0.9.5 used and later versions removed.
+
+**Measured, and refuted:** reading `crypto.mjs`, `p2p.mjs` and `p2p-node.mjs` **at tag `v0.9.5`** through the
+API shows the same two digest names the current tree uses — `blake2s256` and `sha256`. Then a search for
+**dynamic** algorithm arguments (`createHash(variable)`) across `src/` found **none**: every `createHash` and
+`createHmac` in this codebase is called with a string literal.
+
+**So there is no call in this codebase that can produce `Digest method not supported`.** Three hypotheses have
+now been measured and excluded — BLAKE2s, the wider primitive set, and version skew — and the cause remains
+**UNVERIFIED**. What is *not* in doubt is where it is raised: the plugin process on this machine, running
+0.9.5 while the source under study is 0.20.0.
+
+### What this release delivers instead of a fourth guess
+
+`p2pReasons()` and `classifyP2PReason()` turn the P2P reason strings into a **count**, because the finding that
+matters was invisible in every individual report: **twelve of twelve tasks travelled by relay, and no aggregate
+anywhere said so.**
+
+* `relay_only_share` is the fleet's avoidable latency as one number, and it is **`null`** for an empty
+  denominator — "no lease carried a p2p block" and "every lease failed" must not look alike.
+* an unrecognised code is counted as `OTHER` **with the raw code travelling with it**, so a new refusal name
+  is reported rather than swallowed.
+* a missing reason is distinguished from a present one, because *"no reason recorded" is not "no failure"*.
+
+### The version skew is still unresolved and still blocks diagnosis
+
+The installed plugin is **0.9.5**; the source is **0.20.0**. Until they match, every source-level conclusion
+about this machine's P2P behaviour is read from code that is not running. This needs a person: updating the
+plugin installs files into the DSH profile, which is outside what this session changes on its own.
+
+**7 new tests, 0 failures.**
+
 ## [0.19.0] — 2026-10-15
 
 **The plugin this machine runs is 0.9.5. The source tree is 0.18.0. Every source-level conclusion about the P2P failure was read from code that may not have run.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "DSH: Windows2MacOS — drive the same project on online Windows and macOS machines from one DeepSeek account, across networks and regions. P2P hole punching is the default path (relay + shared server as rendezvous, ledger and fallback), with a bundled STUN responder, Tailscale/public-VPS/tunnel shapes, Rabbit relay + per-machine Localside + eight DSH tools (replicate / split), nine aggregate verdicts and signed requests.",
   "type": "module",
   "main": "lib/index.js",
@@ -113,13 +113,13 @@
     }
   },
   "scripts": {
-    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/layer-model.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/chatops-fleet-join.test.mjs",
+    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/layer-model.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/chatops-fleet-join.test.mjs",
     "test:e2e": "node --test --test-force-exit test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/p2p-agent.test.mjs",
     "test:relay": "node --test --test-force-exit test/relay.test.mjs",
     "test:agent": "node --test --test-force-exit test/agent.test.mjs test/memory.test.mjs",
     "test:tools": "node --test --test-force-exit test/tools.test.mjs",
     "test:crossnetwork": "node --test --test-force-exit test/crossnetwork.test.mjs",
-    "test:all": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/layer-model.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-agent.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/p2p-crypto.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/chatops-fleet-join.test.mjs",
+    "test:all": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/agent.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/layer-model.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-agent.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/p2p-crypto.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/chatops-fleet-join.test.mjs",
     "pack": "node scripts/pack.mjs",
     "verify:join": "node scripts/verify-join.mjs",
     "lint": "eslint .",
@@ -144,7 +144,8 @@
     "test:fleet-scale": "node --test --test-force-exit test/fleet-scale.test.mjs",
     "test:fleet-state": "node --test --test-force-exit test/fleet-state.test.mjs",
     "test:crypto-blake2s": "node --test --test-force-exit test/crypto-blake2s.test.mjs",
-    "test:installed-version": "node --test --test-force-exit test/installed-version.test.mjs"
+    "test:installed-version": "node --test --test-force-exit test/installed-version.test.mjs",
+    "test:permission": "node --test --test-force-exit test/permission.test.mjs"
   },
   "keywords": [
     "dsh-bundle",

package/src/agent/fleet-scale.mjs

@@ -111,6 +111,78 @@ export function isFleetFailure(entry) {
   return classifyLease(entry).outcome === LEASE_OUTCOME.NO_RESULT;
 }
 
+/** Refusal codes the relay writes into `p2p.reason`, grouped by what they mean for a fleet. */
+export const P2P_FAILURE_KIND = Object.freeze({
+  NO_CANDIDATES: 'no candidate address was known, so no punch was attempted',
+  PUNCH_FAILED: 'a punch was attempted and did not complete',
+  PUNCH_TIMEOUT: 'a punch was attempted and nothing answered in time',
+  LEASE_NOT_RUNNABLE: 'the lease was not in a state to be handed the command',
+  REVERSE_DIAL: 'the reverse dial did not complete',
+  BLOCKED: 'a local condition stopped the direct path',
+  OTHER: 'a reason the table does not classify',
+});
+
+/**
+ * Classify one `p2p.reason` string.
+ *
+ * Reasons are prose with a machine-readable prefix (`P2P_NO_CANDIDATES: ...`), and reading them one at a time
+ * is how a fleet's direct-path problem stays invisible: the sample that prompted this had **twelve of twelve
+ * tasks on the relay** and no aggregate anywhere that said so.
+ *
+ * Returns `OTHER` for anything unrecognised rather than throwing or guessing, and the raw reason travels with
+ * the classification so a new code is reported rather than swallowed.
+ */
+export function classifyP2PReason(reason) {
+  if (typeof reason !== 'string' || reason === '') {
+    return { kind: null, code: null, detail: 'no reason recorded, which is not the same as no failure' };
+  }
+  const code = (reason.split(':')[0] ?? '').trim();
+  if (code === 'P2P_NO_CANDIDATES') return { kind: P2P_FAILURE_KIND.NO_CANDIDATES, code, detail: reason };
+  if (code === 'P2P_PUNCH_FAILED') return { kind: P2P_FAILURE_KIND.PUNCH_FAILED, code, detail: reason };
+  if (code === 'P2P_PUNCH_TIMEOUT') return { kind: P2P_FAILURE_KIND.PUNCH_TIMEOUT, code, detail: reason };
+  if (code === 'P2P_LEASE_NOT_RUNNABLE') return { kind: P2P_FAILURE_KIND.LEASE_NOT_RUNNABLE, code, detail: reason };
+  if (code.startsWith('P2P_REVERSE_DIAL')) return { kind: P2P_FAILURE_KIND.REVERSE_DIAL, code, detail: reason };
+  if (code.startsWith('P2P_UNAVAILABLE') || code.startsWith('P2P_CRYPTO')) return { kind: P2P_FAILURE_KIND.BLOCKED, code, detail: reason };
+  return { kind: P2P_FAILURE_KIND.OTHER, code, detail: reason };
+}
+
+/**
+ * Count why the direct path was not used, across a set of reports.
+ *
+ * The number worth acting on is `relay_only_share`: the fraction of leases that travelled by relay while a
+ * direct path was nominally configured. That is the fleet's avoidable latency, and it is invisible in any
+ * single report.
+ */
+export function p2pReasons(reports) {
+  const byCode = new Map();
+  let leasesWithP2P = 0;
+  let onRelay = 0;
+  let onDirect = 0;
+  for (const report of Array.isArray(reports) ? reports : []) {
+    for (const m of Array.isArray(report?.machines) ? report.machines : []) {
+      const p = m?.p2p;
+      if (p === null || p === undefined || typeof p !== 'object') continue;
+      leasesWithP2P += 1;
+      if (p.encrypted === true || (p.peer !== null && p.peer !== undefined)) onDirect += 1;
+      else onRelay += 1;
+      const c = classifyP2PReason(p.reason ?? p.encryption_reason ?? null);
+      if (c.code !== null) byCode.set(c.code, (byCode.get(c.code) ?? 0) + 1);
+    }
+  }
+  return {
+    leases_with_p2p: leasesWithP2P,
+    on_relay: onRelay,
+    on_direct: onDirect,
+    // Null rather than 0 for an empty denominator, for the same reason every other rate here is: "no leases"
+    // and "every lease failed" must not look alike.
+    relay_only_share: leasesWithP2P === 0 ? null : Math.round((onRelay / leasesWithP2P) * 1000) / 1000,
+    by_code: Object.fromEntries([...byCode].sort((a, b) => b[1] - a[1])),
+    detail: leasesWithP2P === 0
+      ? 'no lease carried a p2p block, so nothing can be said about the direct path'
+      : `${onRelay} of ${leasesWithP2P} lease(s) used the relay; ${byCode.size} distinct reason code(s)`,
+  };
+}
+
 /**
  * Summarise a set of task reports.
  *

package/src/agent/permission.mjs

@@ -0,0 +1,198 @@
+/**
+ * The permission gate: turning a declared capability table into a decision.
+ *
+ * ## Why this exists, and what it is not
+ *
+ * `scripts/layer-model.mjs` declares what each operational capability costs in authority, and **nothing used
+ * it**. A table nothing consults is not a policy; it is a description of a policy that happens to be true on
+ * the day it is written. This module is the thing that consults it.
+ *
+ * What it is **not**: it does not know what a capability *means*. Classification — is this a write, a scope
+ * change, a registration — belongs to whatever knows the action, which is `authority.mjs`'s own stated rule
+ * and the reason that file declines to enumerate actions. So the two files are split by that line:
+ * `layer-model.mjs` says what each capability costs, `authority.mjs` owns the bands, and this module compares
+ * the two and returns a verdict.
+ *
+ * ## The three answers, and why there are exactly three
+ *
+ * `ALLOW` — the actor's level meets the capability's cost.
+ * `NEEDS_APPROVAL` — the actor is **one band below**, so somebody above them may authorise it.
+ * `DENY` — anything else, including a capability nobody declared.
+ *
+ * The `NEEDS_APPROVAL` window is deliberately **one band**, not "anything below". If any shortfall could be
+ * escalated, an ordinary actor could request a system-admin action and a single inattentive approver would
+ * grant it; the request itself would be the attack. One band means an actor can ask for the *next* thing up
+ * and no more, which is what "escalate to your supervisor" actually means.
+ *
+ * ## The refusal that matters most
+ *
+ * **An undeclared capability is DENIED.** Answering `ALLOW` for something the table has not heard of makes the
+ * table grant whatever is added next, and answering `NEEDS_APPROVAL` makes it requestable. Both are worse than
+ * a refusal, because both hide the omission.
+ */
+import { CAPABILITIES, permissionFor, isDestructive } from '../../scripts/layer-model.mjs';
+import { AUTHORITY_BANDS, AUTHORITY_MAX, AUTHORITY_VERDICT, bandOf, isAuthorityLevel } from './authority.mjs';
+
+export { AUTHORITY_VERDICT };
+
+/** Why a decision came out the way it did. Codes, so a caller branches on a value rather than on prose. */
+export const GATE_REFUSAL = Object.freeze({
+  UNKNOWN_CAPABILITY: 'GATE_UNKNOWN_CAPABILITY',
+  NOT_A_LEVEL: 'GATE_NOT_A_LEVEL',
+  BELOW_BAND: 'GATE_BELOW_BAND',
+  SUFFICIENT: 'GATE_SUFFICIENT',
+  ONE_BAND_BELOW: 'GATE_ONE_BAND_BELOW',
+});
+
+/**
+ * The band index a level falls in, or `-1` when the level is unusable.
+ *
+ * Uses `bandOf` from `authority.mjs` rather than re-deriving the bands, so a change to the band table cannot
+ * make this module disagree with the one that owns it.
+ */
+function bandIndex(level) {
+  if (!isAuthorityLevel(level)) return -1;
+  const band = bandOf(level);
+  if (band === null || band === undefined) return -1;
+  const index = AUTHORITY_BANDS.findIndex((b) => b.name === (band.name ?? band));
+  return index;
+}
+
+/**
+ * Decide whether an actor may exercise a capability.
+ *
+ * @param {string} capability as named in the capability table
+ * @param {number} level the actor's authority level
+ * @returns {{
+ *   verdict: string, capability: string|null, level: number|null,
+ *   required: number|null, shortfall: number|null, destructive: boolean|null,
+ *   reason_code: string, detail: string
+ * }}
+ */
+export function decide(capability, level) {
+  const required = permissionFor(capability);
+
+  if (required === null) {
+    // The most important branch. A capability the table has never heard of is refused, not permitted and not
+    // escalated: either answer would turn an omission into a grant.
+    return {
+      verdict: AUTHORITY_VERDICT.DENY,
+      capability: typeof capability === 'string' ? capability : null,
+      level: isAuthorityLevel(level) ? level : null,
+      required: null,
+      shortfall: null,
+      destructive: null,
+      reason_code: GATE_REFUSAL.UNKNOWN_CAPABILITY,
+      detail: `no capability named ${JSON.stringify(capability)} is declared, so nothing may exercise it; an undeclared capability is refused rather than granted`,
+    };
+  }
+
+  if (!isAuthorityLevel(level)) {
+    // A level nobody defined cannot be compared, and treating it as 0 would silently downgrade an actor while
+    // treating it as high would silently promote one. Neither is a decision this module is entitled to make.
+    return {
+      verdict: AUTHORITY_VERDICT.DENY,
+      capability,
+      level: null,
+      required,
+      shortfall: null,
+      destructive: isDestructive(capability),
+      reason_code: GATE_REFUSAL.NOT_A_LEVEL,
+      detail: `${JSON.stringify(level)} is not an authority level (an integer in 0..${AUTHORITY_MAX}), so it cannot be compared against the required ${required}`,
+    };
+  }
+
+  const destructive = isDestructive(capability);
+
+  if (level >= required) {
+    return {
+      verdict: AUTHORITY_VERDICT.ALLOW,
+      capability,
+      level,
+      required,
+      shortfall: 0,
+      destructive,
+      reason_code: GATE_REFUSAL.SUFFICIENT,
+      detail: `level ${level} meets the ${required} required for ${capability}${destructive ? ' (destructive)' : ''}`,
+    };
+  }
+
+  const actorBand = bandIndex(level);
+  const requiredBand = bandIndex(required);
+  const oneBelow = actorBand >= 0 && requiredBand >= 0 && requiredBand - actorBand === 1;
+
+  if (oneBelow) {
+    return {
+      verdict: AUTHORITY_VERDICT.NEEDS_APPROVAL,
+      capability,
+      level,
+      required,
+      shortfall: required - level,
+      destructive,
+      reason_code: GATE_REFUSAL.ONE_BAND_BELOW,
+      detail: `level ${level} is one band below the ${required} required for ${capability}, so it may be escalated to an approver${destructive ? '; the action is destructive and must not be auto-approved' : ''}`,
+    };
+  }
+
+  return {
+    verdict: AUTHORITY_VERDICT.DENY,
+    capability,
+    level,
+    required,
+    shortfall: required - level,
+    destructive,
+    reason_code: GATE_REFUSAL.BELOW_BAND,
+    detail: `level ${level} is ${required - level} below the ${required} required for ${capability}, which is more than one band; the request itself is refused rather than escalated`,
+  };
+}
+
+/**
+ * Whether a decision may be settled automatically.
+ *
+ * Only `ALLOW` and only for a non-destructive capability. A destructive action that reaches an approver's
+ * queue is a decision for a person even when the approver's level is far above the requirement — the level
+ * answers "may this actor", not "should this happen now".
+ *
+ * @returns {{auto: boolean, detail: string}}
+ */
+export function mayAutoSettle(decision) {
+  if (decision === null || typeof decision !== 'object') return { auto: false, detail: 'no decision supplied' };
+  if (decision.verdict !== AUTHORITY_VERDICT.ALLOW) {
+    return { auto: false, detail: `verdict is ${decision.verdict}, which is not an allow` };
+  }
+  if (decision.destructive === true) {
+    return { auto: false, detail: `${decision.capability} is destructive, so a person settles it however high the level` };
+  }
+  return { auto: true, detail: `${decision.capability} is allowed and not destructive` };
+}
+
+/**
+ * Check that every declared capability is reachable by somebody.
+ *
+ * **An unreachable capability is a defect in the table, not a safety feature.** If its minimum authority
+ * exceeds `AUTHORITY_MAX`, no actor can ever exercise it and the entry is dead — which reads as policy while
+ * doing nothing. Called at test time rather than at load time, because a table with a mistake in it should
+ * fail its own tests rather than make a machine refuse to start.
+ *
+ * @returns {{ok: boolean, unreachable: string[], detail: string}}
+ */
+export function auditCapabilities() {
+  const unreachable = [];
+  for (const c of CAPABILITIES) {
+    if (!Number.isInteger(c.min_authority) || c.min_authority < 0 || c.min_authority > AUTHORITY_MAX) {
+      unreachable.push(`${c.name} (min_authority ${c.min_authority} is outside 0..${AUTHORITY_MAX})`);
+      continue;
+    }
+    // Reachability by a real actor, not merely by the number: a level in a declared band must exist at or
+    // above the requirement.
+    const reachable = AUTHORITY_BANDS.some((b) => b.min >= c.min_authority || (b.max ?? AUTHORITY_MAX) >= c.min_authority);
+    if (!reachable) unreachable.push(`${c.name} (no band reaches ${c.min_authority})`);
+  }
+  return {
+    ok: unreachable.length === 0,
+    unreachable,
+    detail: unreachable.length === 0
+      ? `all ${CAPABILITIES.length} declared capability(ies) are reachable by some band`
+      : `${unreachable.length} declared capability(ies) no actor can exercise: ${unreachable.join('; ')}`,
+  };
+}

package/src/plugin/tools.mjs

@@ -185,7 +185,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '0.19.0';
+const PLUGIN_VERSION = '0.21.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;