@twinsearth/w2m-dsh-plugin 0.30.0 → 0.31.0

package/CHANGELOG.md

@@ -4,6 +4,50 @@ 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.31.0] — 2026-10-15
+
+**The approval gate got a caller, and a draft acceptance definition for 1.0.0.**
+
+### The defect this round started by finding, in the release that had just criticised it
+
+`approval-gate.mjs` shipped in 0.30.0 with a full suite and **no caller** — which is exactly the shape of the
+two defects 0.30.0 had just finished writing into `ROADMAP.md`. **Building a mechanism and wiring it are
+separate acts**, and a mechanism with no caller cannot be told from a finished feature by reading either the
+tests or the source.
+
+It is now on the raise path, and the wiring is asserted rather than described: a real dispatch raises once,
+the queue holds one request, a second raise is **refused by the front door before a request exists**, and the
+queue still holds exactly one. Two more tests pin the asymmetry — reading the queue five times past any raise
+budget, and settling the request — because a gate that also metered *those* would pass a flooding test and
+quietly break the queue.
+
+`approvalRaiseLimitPerMinute` is configurable so a host can set it and so a test can reach the refusal without
+raising thirty requests first. Unset, the gate's own default governs.
+
+### `docs/1.0.0-ACCEPTANCE.md` — a draft for objection
+
+The goal names **分模块 / 分层级 / 分权限**, and a version number means nothing without a definition that can
+fail. The draft lists 21 criteria across the three, each with **where it is checked and whether that check is
+actually running**, under one rule: **a criterion nothing measures is not a criterion.**
+
+Its two honest admissions are the point of writing it:
+
+* **§1.5 — reachability is NOT checked.** Three mechanisms shipped fully tested and completely uncalled in
+  this span. The `claims` suite catches *documentation* drift and **cannot** catch this, because the document
+  and the code can agree while neither is reachable.
+* **§3.11 — the permission gate is OFF by default.** An unset `actorAuthorityLevel` means `enforced: false`
+  and no change, so **a default install dispatches exactly as it did before the permission model existed.**
+  Treating unset as `0` would break every machine that never opted in, so the current behaviour is defensible
+  — but **"off unless configured" cannot be part of a 1.0.0 that claims 分权限.** The draft puts the choice to
+  a reader rather than resolving it: **require a level and refuse to start without one, or ship with the gate
+  off and say so in the README.** Silence is the one option that is not defensible.
+
+It also records what is **not** claimed: no scale statement (3 usable machines of 5), no restart durability for
+the queue, no MacMini verification beyond the four suites measured in 0.28.0, and `P2P_PUNCH_FAILED` still
+UNVERIFIED.
+
+**2 new tests, 0 failures.**
+
 ## [0.30.0] — 2026-10-15
 
 **The same ruler on the other two entries: v4.9.0 had the same defect, v4.10.0 did not.**

package/docs/1.0.0-ACCEPTANCE.md

@@ -0,0 +1,109 @@
+# What 1.0.0 would have to prove — a draft for objection
+
+**Status: DRAFT, and deliberately incomplete.** Nothing here is an announcement that 1.0.0 is close. This file
+exists because the goal names three properties — **分模块 / 分层级 / 分权限** — and a version number means
+nothing without a definition that can fail. It is written to be argued with, and every row says **where the
+claim is checked and whether that check is actually running**.
+
+The rule applied throughout: **a criterion that nothing measures is not a criterion.** Where a check exists
+but has no caller, that is stated in its own column rather than hidden behind a tick.
+
+---
+
+## 1. 分模块 — modules with a declared identity
+
+| # | Criterion | Checked by | Enforced? |
+|---|---|---|---|
+| 1.1 | Every source module belongs to exactly one declared layer | `scripts/layer-check.mjs` | **yes** — `clean: every cross-layer edge is declared` |
+| 1.2 | Every dependency edge is declared, and every declared edge is used | `scripts/layer-check.mjs` | **yes** |
+| 1.3 | Every suite on disk is named by a script | pre-flight `test wiring`, `claims` | **yes** — reported, not silently ignored |
+| 1.4 | Every document's claim about the artifact matches the artifact | `test/claims.test.mjs` | **yes** — 48 claims, and it has caught real drift |
+| 1.5 | No module is unreachable — every declared thing has a caller | *nothing* | **NO — see §4** |
+
+`1.5` is the row that matters most and is the one **not** satisfied. This span shipped three mechanisms that
+were, for a round each, fully tested and completely uncalled: `field-authority.mjs`, `approval-gate.mjs`, and
+before them `createApprovalIndex`. **A tested mechanism with no caller is indistinguishable from a finished
+feature by reading either the tests or the source.** `1.4` catches *documentation* drift and cannot catch this,
+because the document and the code can agree while neither is reachable.
+
+---
+
+## 2. 分层级 — layers, with a direction
+
+| # | Criterion | Checked by | Enforced? |
+|---|---|---|---|
+| 2.1 | Ranked layer model, declared as data | `scripts/layer-model.mjs` | **yes** |
+| 2.2 | An allow-list of edges, not a denylist | `layer-model.mjs` | **yes** — a new edge is refused and forces a decision |
+| 2.3 | No upward edge | `layer-check.mjs` | **yes** — it refused `agent → relay` in 0.30.0 |
+| 2.4 | The layer a module sits in matches what it uses | `layer-check.mjs` | **yes** — it is how `SlidingWindowRateLimiter` was found mis-layered |
+
+**`2.3` and `2.4` have each caught a real defect in this span**, which is the only evidence that a check is
+worth its place. `2.3` fired when the approval gate reached for a relay module; the fix was to move the shared
+limiter down to `util`, **not** to add the edge.
+
+---
+
+## 3. 分权限 — declared capabilities, and something that consults them
+
+| # | Criterion | Checked by | Enforced? |
+|---|---|---|---|
+| 3.1 | Capabilities declared with a cost and a destructiveness flag | `authority.mjs` (`CAPABILITIES`) | **yes** |
+| 3.2 | Every declared capability is reachable by some band | `auditCapabilities()`, asserted | **yes** |
+| 3.3 | A decision is reached from a real dispatch's own facts | `gateDispatch`, `capabilityForDispatch` | **yes** |
+| 3.4 | The dispatch path consults it | `tools.mjs`, asserted end to end | **yes** — since 0.23.0 |
+| 3.5 | An undeclared capability is refused, not granted or escalated | `permission.test.mjs` | **yes** |
+| 3.6 | Escalation is exactly one band | asserted across the whole table | **yes** |
+| 3.7 | Nothing destructive auto-settles, at any level | `mayAutoSettle`, asserted | **yes** |
+| 3.8 | An escalated dispatch reaches a queue an approver can answer | `w2m_approvals`, asserted end to end | **yes** |
+| 3.9 | The queue's front door meters **raising only** | `approval-gate.mjs`, wired in 0.31.0 | **yes** |
+| 3.10 | Field-level memory acceptance is driven by the same model | `field-authority.mjs` | **mechanism yes, caller NO — see §4** |
+| 3.11 | **The gate is ON by default** | *nothing — it is off* | **NO — see below** |
+
+### `3.11` is the load-bearing gap, and it is a decision rather than an oversight
+
+`actorAuthorityLevel` is **unset by default**, and an unset level means the gate reports `enforced: false` and
+changes nothing. So today, **a default install dispatches exactly as it did before the permission model
+existed.** The reasoning is in `permission.mjs` and it is sound as far as it goes: treating an unset level as
+`0` would refuse every writing dispatch on every machine that never opted in, breaking a working fleet to
+enforce a policy nobody asked for.
+
+**But "off unless configured" cannot be part of a 1.0.0 that claims 分权限**, because a permission system that
+is off is a permission system that is untested in production. The question this file puts to a reader is
+therefore concrete:
+
+> **Should 1.0.0 require `actorAuthorityLevel` to be set, refusing to start without one — or should it ship
+> with the gate off and say so in the README?**
+
+Both are defensible. Silence is not, and neither is claiming 分权限 while it is off.
+
+---
+
+## 4. What is explicitly NOT claimed
+
+Recorded here so that absence is a decision rather than an omission:
+
+| Not claimed | Why |
+|---|---|
+| **Reachability of every module** | nothing measures it (§1.5). Three uncalled mechanisms were shipped in this span. |
+| **The gate is active** | `actorAuthorityLevel` is unset by default (§3.11). |
+| **Field authority reaches the memory layer** | `field-authority.mjs` has no production caller; `w2m_memory` does not use it. |
+| **The queue survives a restart** | it is per-plugin-lifetime by design, and is **not** an audit log. |
+| **Any scale claim** | this fleet is 3 usable machines of 5 paired. `ROADMAP.md` refuses to plan v4.11.0+ for exactly this reason, and `fleet-scale.mjs` refuses to extrapolate from five. |
+| **MacMini verification of everything** | four suites were verified on that machine in 0.28.0; the other 69 were not. |
+| **`P2P_PUNCH_FAILED`** | cause UNVERIFIED; three hypotheses measured and excluded. |
+
+---
+
+## 5. What would make this file finished
+
+1. **A reachability check** — every exported function has a non-test caller, or is declared as
+   interface-only with a reason. Without it, §1.5 stays open and the class of defect that produced three
+   dead mechanisms stays invisible.
+2. **A decision on §3.11**, whichever way it goes, reflected in `README.md` and in the pre-flight.
+3. **Every row above promoted to a check that runs**, so this document becomes a description of the
+   pre-flight rather than a parallel list that can drift from it. **A document that restates what the
+   pre-flight does is a second source of truth, and this project has already paid for one of those.**
+
+This draft deliberately stops short of those three, because each is a decision about what 1.0.0 must be
+rather than a defect to fix, and the person who owns it has not answered the question this session asked in
+round 12: **write the acceptance definition, or keep advancing the roadmap?**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.30.0",
+  "version": "0.31.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",

package/src/plugin/tools.mjs

@@ -129,6 +129,8 @@ import { gateDispatch, approvalRequestFor, raiseApproval } from '../agent/permis
 // v0.24.0: the queue an escalation is raised into. Imported from `src/`, never from `scripts/` -- a
 // `src/` module reaching above itself breaks the published package (see CHANGELOG 0.23.0).
 import { createApprovalIndex } from '../agent/approval-index.mjs';
+// v0.31.0: the approval queue's front door. Written in 0.30.0 and given a caller here.
+import { createApprovalGate } from '../agent/approval-gate.mjs';
 import { AUTHORITY_MAX, isAuthorityLevel } from '../agent/authority.mjs';
 // v0.6.0: the device keypair and the offer's key distribution (`docs/P2P-CRYPTO.md` §4). Imported
 // rather than reimplemented: the dispatcher and the executor have to derive the *same* keys, and two
@@ -193,7 +195,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.30.0';
+const PLUGIN_VERSION = '0.31.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -3246,6 +3248,28 @@ export async function apply(ctx, config = {}) {
     return approvals;
   };
 
+  /**
+   * v0.31.0: the rate limiter that is the approval queue's front door.
+   *
+   * ## Why this took a round to arrive
+   *
+   * `approval-gate.mjs` was written in 0.30.0 with a full suite and **no caller** — which is precisely the
+   * defect that same release had just finished documenting in `ROADMAP.md` twice. Building the mechanism and
+   * wiring it are separate acts, and a mechanism with no caller is the thing a reader cannot tell from a
+   * finished feature.
+   *
+   * It guards **raising only**. Reading the queue and settling a request are deliberately unmetered: limiting
+   * the view would limit knowing what is waiting, and limiting the answer would punish the supervisor
+   * clearing the backlog. The threat is queue flooding by a runaway retry loop, and that is a threat against
+   * the raise path.
+   */
+  const approvalGate = createApprovalGate(
+    // Configurable so a host can tighten or loosen it, and so a test can reach the refusal without raising
+    // thirty requests first. Omitted entirely when unset, which leaves the gate's own default in charge --
+    // passing `undefined` through would be the same thing with more ways to be wrong.
+    Number.isInteger(config.approvalRaiseLimitPerMinute) ? { limit: config.approvalRaiseLimitPerMinute } : {},
+  );
+
   // v0.6.1: the two browser routes behind the composer's target control. Additive and optional: a
   // host without `connection.fetch` still gets every tool, and `w2m_status` reports the absence  -   // which is the honest place for it, since a host that has no Connection at all is simply not a web
   // composition and does not need a warning on every headless run.
@@ -3778,6 +3802,24 @@ export async function apply(ctx, config = {}) {
             machineId: null,
             requestedBy: cfg.machineName,
           });
+          // v0.31.0: the raise path passes the front door BEFORE a request exists. A flood of raises is
+          // what the limiter is for, so a refused raise must not have already created the request it was
+          // refused for.
+          const permission = approvalGate.mayRaise({ id: cfg.machineName, level: cfg.actorAuthorityLevel });
+          if (!permission.allowed) {
+            throw new W2MError(
+              'W2M_PERMISSION_APPROVAL_RATE_LIMITED',
+              'W2M_PERMISSION_APPROVAL_RATE_LIMITED: ' + permission.detail,
+              {
+                hint: 'wait for the window to pass and dispatch again; the queue was not cleared and existing requests are still answerable',
+                detail: {
+                  reason_code: permission.reason_code,
+                  retry_after_seconds: permission.retry_after_seconds,
+                  budget: approvalGate.budgetFor({ id: cfg.machineName, level: cfg.actorAuthorityLevel }),
+                },
+              },
+            );
+          }
           const approvalId = randomUUID();
           const raised = raiseApproval(approvalQueue(), request, { approvalId, toolName: 'w2m_run' });
           if (!raised.ok) {