@twinsearth/w2m-dsh-plugin 1.0.9 → 1.0.10

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 All notable changes to this project are documented here.
 
+## [1.0.10] — 2026-10-17
+
+**`w2m_memory {"action":"diff"}`: compare this machine's collective memory against the fleet's current blob,
+and write nothing.**
+
+### Merge is still not implemented, deliberately
+
+The question merge depends on has not been answered:
+
+> **When two machines in one fleet assert different things about the same fact, who wins?**
+
+That is a product decision about what the fleet's memory *is*, not an implementation detail, and shipping a merge
+before its rule is how a fleet silently loses one machine's memory. So this release ships **the half that needs no
+decision** -- and names the other half as open rather than leaving it implied.
+
+### What `diff` answers
+
+* **Is my document the newest one?** `same: true/false`, decided by **whole-document hash equality**.
+* **What would I be overwriting?** `preview.local_only` and `preview.fleet_only`.
+* **Is the fleet's document even there?** Three distinct absence states, each named: the fleet never published; the
+  pointer names a blob that eviction removed; the blob exists and verified.
+
+### Four decisions worth recording
+
+**It writes nothing.** No `.orig`, no `.rej`, no silent merge. Comparing is not a licence to edit a document this
+machine owns.
+
+**`same` is hash equality, not "no line differences".** Two documents with identical line sets in a different order
+are **not** the same, and callling them the same would hide an order change -- which in a markdown document is a
+structural change.
+
+**A set comparison, not a diff.** A line-oriented diff would report "moved" versus "changed" and then want a merge
+policy. **A set comparison cannot resolve anything, which is exactly the property this step requires.**
+
+**The fleet copy is re-hashed before it is compared.** Comparing unverified content would launder it: the report
+would give a hash-verified-looking answer about bytes nobody checked. A blob that fails its own name raises
+`W2M_BAD_BLOB` and is never compared.
+
+Trailing whitespace is normalised (it is noise); leading whitespace is preserved (it is markdown structure).
+
+### Verified
+
+The comparison rule is pinned directly: `local_only` / `fleet_only` separate correctly, trailing whitespace creates
+no difference, and leading whitespace does. Full suite **2360 tests, 2346 pass, 0 fail, 14 skip**; pre-flight
+**GREEN, 15 of 15 checks**.
+
+### NOT verified
+
+The `diff` action **end to end** -- the same gap as `publish`/`pull`/`latest`: type-correct and lint-clean, but
+no test executes it, because that needs a profile with a `fleet-memory.md` and a live relay.
+
+### Open: #2b
+
+**Append-merge with conflict markers, and the marker's existence is the refusal** -- a document containing markers is
+one a human must not trust until resolved. Last-writer-wins is rejected: it loses data silently, and the project's
+own eviction rule already refuses "delete the only copy of a fact" in spirit. **That recommendation is in
+`FLEET-SYNC-2-DESIGN.md` and is not implemented, because it encodes a rule that is the operator's to choose.**
+
 ## [1.0.9] — 2026-10-17
 
 **Discovery: a machine can now ask the relay which blob its fleet published last, instead of a human relaying a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 11 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "type": "module",
   "main": "lib/index.js",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 11 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "license": "MIT",
   "keywords": [

package/src/plugin/tools.mjs

@@ -208,7 +208,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 = '1.0.9';
+const PLUGIN_VERSION = '1.0.10';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -5141,13 +5141,14 @@ export async function apply(ctx, config = {}) {
        */
       action: {
         type: 'string',
-        enum: ['read', 'publish', 'pull', 'latest'],
+        enum: ['read', 'publish', 'pull', 'latest', 'diff'],
         description:
           'read (default) = answer from memory. publish = upload the curated collective memory '
           + '(`fleet-memory.md`) to the relay as a content-addressed blob and return its SHA-256. latest = ask the '
-          + 'relay which blob this fleet published last (the discovery half of the channel). pull = fetch one blob '
-          + 'by SHA-256 -- or by "latest" -- and return its text, re-hashing what came back against the name it was '
-          + 'asked for. None of these modifies the local file.',
+          + 'relay which blob this fleet published last. pull = fetch one blob by SHA-256 -- or by "latest" -- and '
+          + 'return its text, re-hashing it. diff = compare the local document against the fleet current blob and '
+          + 'report what differs, **writing nothing**: merge has no conflict rule yet, so this action deliberately '
+          + 'resolves nothing. None of these modifies the local file.',
         default: 'read',
       },
       hash: {
@@ -5464,6 +5465,150 @@ export async function apply(ctx, config = {}) {
         });
       }
 
+      /**
+       * v1.0.10 (#2a): **compare** this machine's collective memory against the fleet's current blob. Writes nothing.
+       *
+       * ## Why this exists before merge does
+       *
+       * "Merge" needs a conflict rule -- *when two machines assert different facts, who wins?* -- and that is a
+       * product decision, not an implementation detail. Shipping a merge before its rule is how a fleet silently
+       * loses one machine's memory.
+       *
+       * What needs no decision is the half that **prevents harm**: telling a caller whether their local document is
+       * the newest one, and what would be lost if they published over the fleet's copy. That is this action.
+       *
+       * ## Why a set comparison instead of a diff
+       *
+       * `same` is decided by **whole-document hash equality**, not by the absence of line differences: two documents
+       * with identical line sets in a different order are not the same, and reporting them as the same would hide an
+       * order change. The line sets are then reported as `local_only` / `fleet_only` -- deliberately *not* a diff,
+       * because a diff would report "moved" versus "changed" and then want a merge policy. **A set comparison cannot
+       * resolve anything, which is the property this step needs.**
+       *
+       * ## Why it re-hashes the fleet copy
+       *
+       * Comparing unverified content would launder it: the report would give a hash-verified-looking answer about
+       * bytes nobody checked. A blob that fails its own name is reported as unverified, never compared.
+       */
+      if (typeof args?.action === 'string' && args.action === 'diff') {
+        const file = collectivePath();
+        if (file === null) {
+          throw new W2MError('W2M_CONFIG', 'W2M_CONFIG: there is no profile to compare collective memory from', {
+            hint: 'the collective layer lives beside the profile that mounted this plugin',
+          });
+        }
+        let localBytes;
+        try {
+          localBytes = await fs.readFile(file);
+        } catch {
+          throw new W2MError('W2M_NOT_FOUND', `W2M_NOT_FOUND: no collective memory to compare at ${file}`, {
+            hint: 'write measured facts to it first; this action compares, it does not create',
+          });
+        }
+        const localHash = createHash('sha256').update(localBytes).digest('hex');
+        const base = requireRabbit(cfg);
+        const token = await resolveToken(cfg);
+
+        const pointer = await request({
+          rabbitUrl: base,
+          token,
+          pathname: '/v1/fleet/blobs/latest',
+          signal: exec?.signal,
+        });
+        if (pointer.status === 404) {
+          // No fleet document yet: nothing to differ from. Reported as a state, not as an error.
+          return JSON.stringify({
+            ok: true,
+            same: false,
+            local: { hash: localHash, bytes: localBytes.length, file },
+            fleet: { present: false, reason: 'this fleet has published no blob yet' },
+            merged: false,
+            wrote_anything: false,
+          });
+        }
+        if (pointer.status !== 200) {
+          throw new W2MError(
+            'W2M_RABBIT_REFUSED',
+            `W2M_RABBIT_REFUSED: GET /v1/fleet/blobs/latest answered HTTP ${pointer.status}`,
+            { http_status: pointer.status, detail: pointer.error ?? null },
+          );
+        }
+        const fleetHash = String(pointer.json?.hash ?? '');
+        const fleetRes = await request({
+          rabbitUrl: base,
+          token,
+          pathname: `/v1/fleet/blobs/${fleetHash}`,
+          accept: 'application/octet-stream',
+          signal: exec?.signal,
+        });
+        if (fleetRes.status === 404) {
+          // The pointer is a hint (see #3): eviction can take the document it names.
+          return JSON.stringify({
+            ok: true,
+            same: false,
+            local: { hash: localHash, bytes: localBytes.length, file },
+            fleet: {
+              present: false,
+              pointed_at: fleetHash,
+              reason: 'the pointer names a blob that no longer exists (oldest-first eviction)',
+            },
+            merged: false,
+            wrote_anything: false,
+          });
+        }
+        if (fleetRes.status !== 200) {
+          throw new W2MError(
+            'W2M_RABBIT_REFUSED',
+            `W2M_RABBIT_REFUSED: GET /v1/fleet/blobs/${fleetHash} answered HTTP ${fleetRes.status}`,
+            { http_status: fleetRes.status, detail: fleetRes.error ?? null },
+          );
+        }
+        const fleetText = fleetRes.text ?? '';
+        const fleetActual = createHash('sha256').update(fleetText, 'utf8').digest('hex');
+        if (fleetActual !== fleetHash) {
+          throw new W2MError(
+            'W2M_BAD_BLOB',
+            `W2M_BAD_BLOB: the fleet blob ${fleetHash} hashes to ${fleetActual} instead`,
+            {
+              hint: 'refusing to compare unverified content -- a comparison over bytes nobody checked would '
+                + 'launder them',
+              expected: fleetHash,
+              actual: fleetActual,
+            },
+          );
+        }
+
+        const localText = localBytes.toString('utf8');
+        // Trailing whitespace only: leading whitespace is markdown structure, not noise.
+        const norm = (text) => new Set(text.split('\n').map((line) => line.replace(/\s+$/, '')));
+        const localLines = norm(localText);
+        const fleetLines = norm(fleetText);
+        const localOnly = [...localLines].filter((line) => !fleetLines.has(line));
+        const fleetOnly = [...fleetLines].filter((line) => !localLines.has(line));
+        return JSON.stringify({
+          ok: true,
+          same: localHash === fleetHash,
+          local: { hash: localHash, bytes: localBytes.length, lines: localLines.size, file },
+          fleet: {
+            present: true,
+            hash: fleetHash,
+            bytes: Buffer.byteLength(fleetText, 'utf8'),
+            lines: fleetLines.size,
+            published_at: pointer.json?.published_at ?? null,
+            published_by: pointer.json?.published_by ?? null,
+          },
+          differing_lines: localOnly.length + fleetOnly.length,
+          preview: {
+            local_only: localOnly.slice(0, 20),
+            fleet_only: fleetOnly.slice(0, 20),
+            truncated: localOnly.length > 20 || fleetOnly.length > 20,
+          },
+          merged: false,
+          wrote_anything: false,
+          note: 'a comparison only. Merge has no conflict rule yet, so nothing is resolved and nothing is written.',
+        });
+      }
+
       const limitRaw = Number(args?.limit);
       const limit = Number.isFinite(limitRaw) && limitRaw > 0 ? Math.min(Math.floor(limitRaw), 500) : 20;