jui-tools-mcp-server 2.10.3 → 2.11.0

package/data/screen_identity.json

@@ -297,7 +297,7 @@
   },
   "diagram": {
     "description": "The screen-transition diagram is derived from the same ids.",
-    "nodeSource": "flow test inline step 'screen' values, plus file-reference steps normalized to the same id space",
+    "nodeSource": "TWO sources, both normalized into the same id space: (1) flow test inline step 'screen' values plus file-reference steps; (2) spec 'transitions[].destination' values, through specTransitions below. Naming only one of them here is how an implementation ends up reading a source the canon does not declare.",
     "pipeline": [
       "resolve",
       "canonicalize",
@@ -309,6 +309,53 @@
       "An edge caused by a 'back' action is a return edge and is rendered distinctly from a forward transition.",
       "Node ids are sanitized for the diagram language; a screen id is never emitted raw into a diagram identifier position."
     ],
+    "specTransitions": {
+      "source": "<screen spec>.transitions[].destination",
+      "description": "A spec transition's destination is FREE PROSE, not an identifier. The validator requires only that the key exists (condition + destination), so nothing has ever constrained its shape, and the corpus shows at least six different kinds of value in that one column.",
+      "measured": {
+        "date": "2026-09-09",
+        "scanRoot": "<face>/docs/screens/json/*.spec.json (the generated <face>/docs/html/screens tree is NOT the corpus)",
+        "idSpace": "the spec stems under that root, UNION the layout basenames under <face>/docs/screens/layouts (variant-normalized)",
+        "faces": 4,
+        "transitions": 271,
+        "note": "Two of the four faces carry exactly 93 transitions. A count reported without naming its face is therefore ambiguous, and reads as correct either way."
+      },
+      "kinds": {
+        "description": "CLOSED vocabulary. It exists so that a destination which is not a screen id stops being reported as a defect. Declaring only 'screen' would make 119 of 271 measured destinations spec errors, when they are other kinds of transition — that turns a reporting gap into a rejection of correct input, which is the worse direction.",
+        "values": [
+          {"kind": "screen", "meaning": "resolves to a screen id in this face's id space", "drawn": "a node and an edge"},
+          {"kind": "route", "meaning": "a URL path owned by a web router, e.g. '/admin/login'", "drawn": "an edge once the route is mapped to a screen; until then, reported"},
+          {"kind": "external", "meaning": "leaves the app entirely (browser, tel:, map app, mailer)", "drawn": "a terminal node, never a screen"},
+          {"kind": "none", "meaning": "declares that no screen transition happens (in-page tab switch, SPA state change)", "drawn": "nothing. This is a POSITIVE declaration, not a missing value"},
+          {"kind": "back", "meaning": "returns through the navigation stack (pop, dismiss, previous screen)", "drawn": "a return edge, like a flow test's back action"},
+          {"kind": "unknown", "meaning": "none of the above matched", "drawn": "nothing, and it is COUNTED AND LISTED — see unresolvedReporting"}
+        ]
+      },
+      "normalization": {
+        "description": "Applied in order. Every step is here rather than in a resolver because a rule that lives at one call site is absent from the other two (screen_identity.py, mermaid/flow_graph.py, verify_cmd.py each resolve ids today).",
+        "parentheticalsNest": "The strip step COUNTS DEPTH; it is not a match. A flat pattern consumes up to the INNER close of `Name (a=b / onNavigate(Screen.X))` and leaves the OUTER one, producing the candidate `Name )`, which resolves to nothing. Measured 2026-09-09: 5 destinations nest, and 3 of them were unresolvable for this reason alone — the value read like prose the classifier could not handle when it was prose the classifier had damaged.",
+        "pipeline": [
+          "compare case-insensitively with whitespace, '_' and '-' removed",
+          "strip a trailing parenthetical, full-width or half-width, then split on ' or ', '/', and '、' and try each part",
+          "apply the face's declared aliases (below)"
+        ],
+        "aliases": {
+          "shape": "each declared alias is (position, affix); position is drawn from the closed set below",
+          "positions": ["prefix", "suffix"],
+          "positionsNote": "THE TWO POSITIONS OBSERVED SO FAR, not all of them. Infix and partial matches are NOT covered, and saying which is which matters: a generalization that names its coverage makes the third example a counterexample that asks for a redesign, while one that says 'all' makes the same example an exception to be pushed in sideways, leaving the mechanism bent.",
+          "measured": "prefix 'Web' resolves 50 of one face's 93 destinations; suffix '画面' resolves 10 (9 distinct spellings) of another face's 69. The two sit at different ends, which is why the mechanism carries a position rather than a bare string. A THIRD affix then turned up that does not behave like those two: suffix 'View' resolves 8 on one face and 2 on ANOTHER, so an affix is not necessarily one face's convention. Per-face declaration still expresses it — each face declares it separately — but the earlier reading that 'an affix helps exactly one face' was drawn from a sample of two. Whether to declare it is the FACE's call, not the library's — the mechanism already accepts it — so the numbers a face needs are recorded here rather than argued: declaring suffix 'View' resolves 10 destinations (8 on one face, 2 on another) and leaves 5 occurrences / 4 spellings that contain 'View' still unresolved, because stripping it yields no id — FullscreenImageViewer, LicensesView, and the Privacy/Terms WebView pair, whose kind is a separate question (embedded page or external browser) that no measurement here answers.",
+          "scopingIsARiskChoiceNotAMeasuredOne": {
+            "whatWasMeasuredAndFailed": "Applying either affix to ALL FOUR faces unconditionally changes not one count. The other faces' zeros come from having no id that matches after the strip — NOT from the declaration withholding itself. So the corpus cannot tell a per-face declaration from a global rule, and an earlier version of this note claimed it could: it read '0 of the other three faces' as evidence the scoping was working, when that zero was made by the predicate.",
+            "whatCanBeMeasured": "How close the global rule is to going wrong. Ids beginning with 'Web' already exist — `web_view`, in two of the four faces. Strip the prefix and you get `view`, which is no face's id TODAY. The distance is ONE id: a face that adds `view` turns the global rule into a silent misresolution that gets drawn in a diagram.",
+            "conclusion": "Per-face, because the distance is one id — not because the counts said so. The two sentences above are kept apart on purpose: 'we could not measure a difference' and 'we measured how near the failure is' are different claims, and collapsing them is how a withdrawn reason survives a correct decision."
+          }
+        }
+      },
+      "unresolvedReporting": {
+        "rule": "The count of 'unknown' destinations is reported PER FACE, never only as a total, together with the scanned total it was drawn from.",
+        "rationale": "Measured unresolved rates were 28% / 61% / 50% / 100%. Summed, the face at 100% disappears into the average — and a face that resolves nothing looks exactly like a face with nothing to resolve. A bare zero, or a bare average, cannot tell an instrument that found nothing from one that never reached the corpus."
+      }
+    },
     "fileReferences": {
       "rule": "A file-reference step ({ file, case }) becomes a node for the SCREEN the referenced test covers — resolved through that test's own source.layout — not for the referenced file's name.",
       "rationale": "A test file NAME is not a screen id. One screen routinely has several test files (login_smoke, booking_complete--bank_pending), so naming the node after the file splits one screen into several nodes; the split-off node also carries no metadata, so it loses the group its test declared and drops into the ungrouped bucket. The basename only looked right because it usually happens to equal the screen id.",

package/dist/spec_loader.d.ts

@@ -31,6 +31,24 @@ export interface FileInfo {
     lastModified: string;
     /** Freshness bucket. "fresh" <= 30d, "aging" <= 90d, "stale" > 90d. */
     freshness: "fresh" | "aging" | "stale";
+    /**
+     * sha256 of the bytes this process actually read.
+     *
+     * 🚨 THE STALENESS QUESTION IS ABOUT CONTENT, NOT ABOUT mtime. Every
+     * jsonui-cli distribution replaces `~/.jsonui-cli` wholesale, so an install
+     * moves every mtime whether or not a byte changed — measured 2026-09-09: a
+     * release whose `shared/core` was blob-identical to the previous one moved
+     * all seven timestamps, and every running server then reported "restart it"
+     * while serving exactly the right content. An alarm that fires on every
+     * distribution stops being read.
+     *
+     * The same toolchain already learned this one repo over: `jui build`'s
+     * generation manifest records a sha256 and says why — "a record that changes
+     * when nothing changed is noise, and noise is what gets ignored" — after an
+     * mtime-based version churned 89 entries between two builds with nothing
+     * edited. Same conclusion, reached twice, applied once.
+     */
+    contentHash: string;
 }
 export interface DataSourceInfo {
     attributeDefinitions: FileInfo;
@@ -87,12 +105,18 @@ export declare class SpecLoader {
     /** ISO 8601 timestamp of when this process loaded its data files. */
     getLoadedAt(): string;
     /**
-     * Paths whose mtime has moved since this process read them.
+     * Paths whose CONTENT differs from what this process read.
+     *
+     * 🔻 mtime is a PRE-FILTER, not the answer. It is cheap and right about the
+     * common case (nothing touched the file), so it saves a read — but a moved
+     * timestamp on identical bytes is not staleness, and that is exactly what a
+     * distribution produces: `~/.jsonui-cli` is replaced wholesale on every
+     * install, so every mtime moves every time. Reporting on mtime alone made
+     * this fire on 100% of distributions, which is the same as not reporting.
      *
-     * Compares against the mtime recorded AT LOAD, not against a wall-clock
-     * timestamp: "was this file edited after I read it" is a question about
-     * the file, and comparing a file mtime to Date.now() is a race whenever
-     * the two land in the same millisecond.
+     * ⚠️ A file that disappeared is still reported: the server is serving
+     * content whose source is gone, which a reader needs to know even though no
+     * hash can be computed for it.
      */
     getChangedSinceLoad(): string[];
     getScreenIdentity(): any;

package/dist/spec_loader.js

@@ -1,8 +1,23 @@
+import { createHash } from "crypto";
 import { existsSync, readFileSync, statSync } from "fs";
 import { homedir } from "os";
 import { join, resolve } from "path";
 import { fileURLToPath } from "url";
 import { BINDING_RULES, MODIFIER_ORDER, PLATFORM_MAPPING, categorizeCommonAttributes, } from "./data/derived.js";
+/**
+ * sha256 of a file's bytes, or "" when it cannot be read.
+ *
+ * "" never equals a real digest, so an unreadable file compares as CHANGED
+ * rather than as unchanged — the safe direction for a staleness check.
+ */
+function hashFile(path) {
+    try {
+        return createHash("sha256").update(readFileSync(path)).digest("hex");
+    }
+    catch {
+        return "";
+    }
+}
 const ALL_PLATFORMS = {
     swift_generated: true,
     swift_dynamic: true,
@@ -208,12 +223,18 @@ export class SpecLoader {
         return this.loadedAt;
     }
     /**
-     * Paths whose mtime has moved since this process read them.
+     * Paths whose CONTENT differs from what this process read.
+     *
+     * 🔻 mtime is a PRE-FILTER, not the answer. It is cheap and right about the
+     * common case (nothing touched the file), so it saves a read — but a moved
+     * timestamp on identical bytes is not staleness, and that is exactly what a
+     * distribution produces: `~/.jsonui-cli` is replaced wholesale on every
+     * install, so every mtime moves every time. Reporting on mtime alone made
+     * this fire on 100% of distributions, which is the same as not reporting.
      *
-     * Compares against the mtime recorded AT LOAD, not against a wall-clock
-     * timestamp: "was this file edited after I read it" is a question about
-     * the file, and comparing a file mtime to Date.now() is a race whenever
-     * the two land in the same millisecond.
+     * ⚠️ A file that disappeared is still reported: the server is serving
+     * content whose source is gone, which a reader needs to know even though no
+     * hash can be computed for it.
      */
     getChangedSinceLoad() {
         const tracked = [
@@ -228,8 +249,15 @@ export class SpecLoader {
         const changed = [];
         for (const file of tracked) {
             try {
-                const now = statSync(file.path).mtime.toISOString();
-                if (now !== file.lastModified)
+                // 🚫 NO mtime PRE-FILTER. An earlier draft skipped the read when the
+                // timestamp had not moved, to save I/O — and an arm caught it missing
+                // an edit that landed in the same millisecond as the load. The saving
+                // was seven small reads on a diagnostic call nobody runs in a loop;
+                // the cost was a checker that answers "unchanged" for a file it never
+                // looked at. That is the same shape as the mtime comparison this
+                // replaced: a cheap proxy standing in for the question.
+                statSync(file.path); // still there? (throws into the catch if not)
+                if (hashFile(file.path) !== file.contentHash)
                     changed.push(file.path);
             }
             catch {
@@ -482,6 +510,7 @@ export class SpecLoader {
                     path: candidate.path,
                     lastModified: mtime.toISOString(),
                     freshness,
+                    contentHash: hashFile(candidate.path),
                 };
             }
         }

package/dist/tools/spec/get_data_source.js

@@ -1,12 +1,20 @@
 export function register(server, loader) {
     server.tool("get_data_source", "Report where the MCP server loaded EVERY canonical data file from — attribute_definitions.json (raw schema), component_metadata.json (presentation metadata), screen_identity.json and binding_semantics.json. Shows layer (env / cwd / home / bundled), the absolute path actually read, file mtime and freshness per file, plus when this server process loaded them. Use it when the CLI and the MCP seem to disagree about the canon: it distinguishes a stale file from a server that simply has not been restarted since the file changed.", {}, async () => {
         const info = loader.getDataSource();
+        // 🚨 THE SAME SEVEN THE STALENESS CHECK WATCHES. This list held five
+        // while `getChangedSinceLoad` tracked seven, so `staleInMemory` could
+        // name a path that appeared in no per-file entry — and a reader who
+        // "checked every file reported" had two outside their view. Reported by
+        // a consumer lane 2026-09-09. Aligning the two beats documenting the
+        // difference: a documented difference asks the reader to count.
         const files = [
             info.attributeDefinitions,
             info.componentMetadata,
             info.screenIdentity,
             info.bindingSemantics,
             info.attributeSemantics,
+            info.platformSemantics,
+            info.coverage,
         ].filter((f) => f != null);
         const stale = files.some((f) => f.freshness === "stale");
         // The data is read once at construction and cached in memory, so a
@@ -24,12 +32,20 @@ export function register(server, loader) {
                         screenIdentity: info.screenIdentity,
                         bindingSemantics: info.bindingSemantics,
                         attributeSemantics: info.attributeSemantics,
+                        platformSemantics: info.platformSemantics,
+                        coverage: info.coverage,
                         componentCount: info.componentCount,
                         commonAttributeCount: info.commonAttributeCount,
                         loadedAt,
                         staleInMemory: changedSinceLoad.length > 0 ? changedSinceLoad : undefined,
+                        //  `freshness` is a property of the FILE (how old it is);
+                        //  `staleInMemory` is a property of THIS SERVER (whether what
+                        //  it holds still matches disk). They are different
+                        //  quantities, and a reader who checks only the first gets
+                        //  "fresh" on every file while the server serves something
+                        //  else. The hint names which one fired.
                         hint: changedSinceLoad.length
-                            ? "These files changed on disk AFTER this server loaded them. The server is serving the older content from memory — restart it."
+                            ? "The CONTENT of these files differs from what this server loaded (compared by sha256, not by timestamp — a distribution moves every mtime without changing bytes). The server is serving the older content from memory — restart it."
                             : stale
                                 ? "At least one data file is > 90 days old. Re-fetch via `npm rebuild jui-tools-mcp-server` or point JSONUI_CLI_PATH at a fresher checkout."
                                 : undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jui-tools-mcp-server",
-  "version": "2.10.3",
+  "version": "2.11.0",
   "description": "MCP server for JsonUI project management - wraps jui and jsonui-doc CLIs plus component spec lookup",
   "main": "dist/index.js",
   "scripts": {

package/src/spec_loader.ts

@@ -1,3 +1,4 @@
+import { createHash } from "crypto";
 import { existsSync, readFileSync, statSync } from "fs";
 import { homedir } from "os";
 import { join, resolve } from "path";
@@ -37,6 +38,20 @@ export interface ComponentSpec {
 
 export type FallbackLayer = "env" | "cwd" | "home" | "bundled";
 
+/**
+ * sha256 of a file's bytes, or "" when it cannot be read.
+ *
+ * "" never equals a real digest, so an unreadable file compares as CHANGED
+ * rather than as unchanged — the safe direction for a staleness check.
+ */
+function hashFile(path: string): string {
+  try {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+  } catch {
+    return "";
+  }
+}
+
 export interface FileInfo {
   /** Which fallback layer provided the file. */
   layer: FallbackLayer;
@@ -46,6 +61,24 @@ export interface FileInfo {
   lastModified: string;
   /** Freshness bucket. "fresh" <= 30d, "aging" <= 90d, "stale" > 90d. */
   freshness: "fresh" | "aging" | "stale";
+  /**
+   * sha256 of the bytes this process actually read.
+   *
+   * 🚨 THE STALENESS QUESTION IS ABOUT CONTENT, NOT ABOUT mtime. Every
+   * jsonui-cli distribution replaces `~/.jsonui-cli` wholesale, so an install
+   * moves every mtime whether or not a byte changed — measured 2026-09-09: a
+   * release whose `shared/core` was blob-identical to the previous one moved
+   * all seven timestamps, and every running server then reported "restart it"
+   * while serving exactly the right content. An alarm that fires on every
+   * distribution stops being read.
+   *
+   * The same toolchain already learned this one repo over: `jui build`'s
+   * generation manifest records a sha256 and says why — "a record that changes
+   * when nothing changed is noise, and noise is what gets ignored" — after an
+   * mtime-based version churned 89 entries between two builds with nothing
+   * edited. Same conclusion, reached twice, applied once.
+   */
+  contentHash: string;
 }
 
 export interface DataSourceInfo {
@@ -313,12 +346,18 @@ export class SpecLoader {
   }
 
   /**
-   * Paths whose mtime has moved since this process read them.
+   * Paths whose CONTENT differs from what this process read.
+   *
+   * 🔻 mtime is a PRE-FILTER, not the answer. It is cheap and right about the
+   * common case (nothing touched the file), so it saves a read — but a moved
+   * timestamp on identical bytes is not staleness, and that is exactly what a
+   * distribution produces: `~/.jsonui-cli` is replaced wholesale on every
+   * install, so every mtime moves every time. Reporting on mtime alone made
+   * this fire on 100% of distributions, which is the same as not reporting.
    *
-   * Compares against the mtime recorded AT LOAD, not against a wall-clock
-   * timestamp: "was this file edited after I read it" is a question about
-   * the file, and comparing a file mtime to Date.now() is a race whenever
-   * the two land in the same millisecond.
+   * ⚠️ A file that disappeared is still reported: the server is serving
+   * content whose source is gone, which a reader needs to know even though no
+   * hash can be computed for it.
    */
   getChangedSinceLoad(): string[] {
     const tracked = [
@@ -334,8 +373,15 @@ export class SpecLoader {
     const changed: string[] = [];
     for (const file of tracked) {
       try {
-        const now = statSync(file.path).mtime.toISOString();
-        if (now !== file.lastModified) changed.push(file.path);
+        // 🚫 NO mtime PRE-FILTER. An earlier draft skipped the read when the
+        // timestamp had not moved, to save I/O — and an arm caught it missing
+        // an edit that landed in the same millisecond as the load. The saving
+        // was seven small reads on a diagnostic call nobody runs in a loop;
+        // the cost was a checker that answers "unchanged" for a file it never
+        // looked at. That is the same shape as the mtime comparison this
+        // replaced: a cheap proxy standing in for the question.
+        statSync(file.path); // still there? (throws into the catch if not)
+        if (hashFile(file.path) !== file.contentHash) changed.push(file.path);
       } catch {
         // Disappeared since load — also a reason to restart.
         changed.push(file.path);
@@ -649,6 +695,7 @@ export class SpecLoader {
           path: candidate.path,
           lastModified: mtime.toISOString(),
           freshness,
+          contentHash: hashFile(candidate.path),
         };
       }
     }

package/src/tools/spec/get_data_source.ts

@@ -8,12 +8,20 @@ export function register(server: McpServer, loader: SpecLoader) {
     {},
     async () => {
       const info = loader.getDataSource();
+      // 🚨 THE SAME SEVEN THE STALENESS CHECK WATCHES. This list held five
+      // while `getChangedSinceLoad` tracked seven, so `staleInMemory` could
+      // name a path that appeared in no per-file entry — and a reader who
+      // "checked every file reported" had two outside their view. Reported by
+      // a consumer lane 2026-09-09. Aligning the two beats documenting the
+      // difference: a documented difference asks the reader to count.
       const files = [
         info.attributeDefinitions,
         info.componentMetadata,
         info.screenIdentity,
         info.bindingSemantics,
         info.attributeSemantics,
+        info.platformSemantics,
+        info.coverage,
       ].filter((f): f is NonNullable<typeof f> => f != null);
       const stale = files.some((f) => f.freshness === "stale");
       // The data is read once at construction and cached in memory, so a
@@ -32,12 +40,20 @@ export function register(server: McpServer, loader: SpecLoader) {
                 screenIdentity: info.screenIdentity,
                 bindingSemantics: info.bindingSemantics,
                 attributeSemantics: info.attributeSemantics,
+                platformSemantics: info.platformSemantics,
+                coverage: info.coverage,
                 componentCount: info.componentCount,
                 commonAttributeCount: info.commonAttributeCount,
                 loadedAt,
                 staleInMemory: changedSinceLoad.length > 0 ? changedSinceLoad : undefined,
+                //  `freshness` is a property of the FILE (how old it is);
+                //  `staleInMemory` is a property of THIS SERVER (whether what
+                //  it holds still matches disk). They are different
+                //  quantities, and a reader who checks only the first gets
+                //  "fresh" on every file while the server serves something
+                //  else. The hint names which one fired.
                 hint: changedSinceLoad.length
-                  ? "These files changed on disk AFTER this server loaded them. The server is serving the older content from memory — restart it."
+                  ? "The CONTENT of these files differs from what this server loaded (compared by sha256, not by timestamp — a distribution moves every mtime without changing bytes). The server is serving the older content from memory — restart it."
                   : stale
                     ? "At least one data file is > 90 days old. Re-fetch via `npm rebuild jui-tools-mcp-server` or point JSONUI_CLI_PATH at a fresher checkout."
                     : undefined,

package/tests/spec_loader.test.ts

@@ -4,7 +4,7 @@
  * Layer order under test:
  *   1. $JSONUI_CLI_PATH  2. ./.jsonui-cli/  3. ~/.jsonui-cli/  4. bundled data/
  */
-import { utimesSync } from "fs";
+import { utimesSync, writeFileSync } from "fs";
 import { join, resolve, sep } from "path";
 import { pathToFileURL } from "url";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
@@ -527,17 +527,35 @@ describe("SpecLoader coverage ledger", () => {
   // The ledger is served from the same in-memory cache as everything else,
   // so an on-disk refresh MUST surface in getChangedSinceLoad — a tracked
   // list that omits a file is the "silently stale" trap in a second costume.
+  //
+  // 🔻 THE PROVOCATION CHANGED 2026-09-10, THE INTENT DID NOT. This used to
+  // move the mtimes with utimesSync and expect both paths back, which encoded
+  // the old mtime-based comparison. That comparison fired on every jsonui-cli
+  // distribution (each install replaces ~/.jsonui-cli wholesale, so every
+  // timestamp moves whether or not a byte changed) and was replaced by a
+  // sha256 comparison. The claim this arm makes — "the ledger is in the
+  // tracked set" — is unaffected; only the way it provokes a change is.
   it("counts the ledger among the files tracked by getChangedSinceLoad", () => {
     expect(loader.getChangedSinceLoad()).toEqual([]);
 
     const ledgerPath = loader.getDataSource().coverage!.path;
     const attrPath = loader.getDataSource().attributeDefinitions.path;
-    const later = new Date(Date.now() + 5000);
-    utimesSync(ledgerPath, later, later);
-    utimesSync(attrPath, later, later);
+    writeFileSync(ledgerPath, JSON.stringify({ schemaVersion: 1, entries: [] }));
+    writeFileSync(attrPath, JSON.stringify({ common: {} }));
 
     const changed = loader.getChangedSinceLoad();
     expect(changed).toContain(ledgerPath);
     expect(changed).toContain(attrPath);
   });
+
+  // 逆向きの腕。Without it, an implementation that reported every tracked file
+  // unconditionally would pass the one above — and that is precisely the
+  // implementation this release removed.
+  it("does not count a tracked file whose bytes did not move", () => {
+    const ledgerPath = loader.getDataSource().coverage!.path;
+    const later = new Date(Date.now() + 5000);
+    utimesSync(ledgerPath, later, later);
+
+    expect(loader.getChangedSinceLoad()).toEqual([]);
+  });
 });

package/tests/staleness_is_content_not_mtime.test.ts

@@ -0,0 +1,179 @@
+/**
+ * `staleInMemory` answers "is what I hold still what is on disk" — and that is
+ * a question about CONTENT.
+ *
+ * 🚨 WHY THIS FILE EXISTS. It used to compare mtimes. Every jsonui-cli
+ * distribution replaces `~/.jsonui-cli` wholesale, so an install moves every
+ * timestamp whether or not a byte changed. Measured 2026-09-09: a release
+ * whose `shared/core` blobs were IDENTICAL to the previous release's moved all
+ * seven, and three running servers then reported "restart it" while serving
+ * exactly the right content. An alarm with a 100% fire rate cannot be a gate.
+ *
+ * The same toolchain had already reached this conclusion one repo over — the
+ * `jui build` generation manifest records a sha256 and its docstring says why:
+ * "a record that changes when nothing changed is noise, and noise is what gets
+ * ignored". Two implementations of one rule; only one had read it.
+ *
+ * ⚠️ `freshness` and `staleInMemory` are DIFFERENT QUANTITIES: the first is
+ * about the file (how old), the second about this process (what it holds). A
+ * reader who checks only the first sees "fresh" on every file while the server
+ * serves something else. One arm below pins that they can disagree.
+ */
+import { rmSync, statSync, utimesSync, writeFileSync } from "fs";
+import { join } from "path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { SpecLoader } from "../src/spec_loader.js";
+import { register as registerDataSource } from "../src/tools/spec/get_data_source.js";
+import {
+  cleanupTempDirs,
+  createToolHarness,
+  makeCliDataset,
+  makeTempDir,
+  FIXTURE_ATTRIBUTE_DEFINITIONS,
+  FIXTURE_COVERAGE,
+} from "./helpers.js";
+
+const originalCwd = process.cwd();
+let cliRoot: string;
+let loader: SpecLoader;
+
+/** The file every arm here pokes at. */
+function attrPath(): string {
+  return join(cliRoot, "shared", "core", "attribute_definitions.json");
+}
+
+/** Rewrite a file with the SAME bytes, then move its mtime forward. */
+function touchWithoutChanging(path: string): void {
+  const bytes = require("fs").readFileSync(path);
+  writeFileSync(path, bytes);
+  const future = new Date(Date.now() + 60_000);
+  utimesSync(path, future, future);
+}
+
+beforeEach(() => {
+  cliRoot = makeTempDir("cli");
+  makeCliDataset(cliRoot, { coverage: FIXTURE_COVERAGE });
+  process.env.JSONUI_CLI_PATH = cliRoot;
+  process.chdir(makeTempDir("cwd"));
+  process.env.HOME = makeTempDir("home");
+  process.env.USERPROFILE = process.env.HOME;
+  loader = new SpecLoader(makeTempDir("mcp"));
+});
+
+afterEach(() => {
+  delete process.env.JSONUI_CLI_PATH;
+  process.chdir(originalCwd);
+  cleanupTempDirs();
+});
+
+describe("a moved timestamp on identical bytes is not staleness", () => {
+  it("reports nothing when nothing was touched", () => {
+    expect(loader.getChangedSinceLoad()).toEqual([]);
+  });
+
+  it("reports nothing when the file is rewritten with the same bytes", () => {
+    const before = statSync(attrPath()).mtime.toISOString();
+    touchWithoutChanging(attrPath());
+    // 陽性対照 ON THE FIXTURE: without this, an arm that passes because the
+    // rewrite silently failed looks identical to one that passes correctly.
+    expect(statSync(attrPath()).mtime.toISOString()).not.toBe(before);
+
+    expect(loader.getChangedSinceLoad()).toEqual([]);
+  });
+
+  it("reports the file when the bytes actually change", () => {
+    writeFileSync(
+      attrPath(),
+      JSON.stringify({ ...FIXTURE_ATTRIBUTE_DEFINITIONS, Extra: {} }, null, 2)
+    );
+    expect(loader.getChangedSinceLoad()).toContain(attrPath());
+  });
+
+  it("reports the file when it disappears", () => {
+    // No hash can be computed, and the server is serving content whose source
+    // is gone — the reader needs that, so absence counts as changed.
+    rmSync(attrPath());
+    expect(loader.getChangedSinceLoad()).toContain(attrPath());
+  });
+
+  it("does not report a sibling that was left alone", () => {
+    // 陰性対照: an implementation that reported everything passes the two
+    // positive arms above.
+    writeFileSync(
+      attrPath(),
+      JSON.stringify({ ...FIXTURE_ATTRIBUTE_DEFINITIONS, Extra: {} }, null, 2)
+    );
+    const changed = loader.getChangedSinceLoad();
+    expect(changed).toContain(attrPath());
+    expect(changed.some((p) => p.endsWith("component_metadata.json"))).toBe(false);
+  });
+});
+
+describe("freshness and staleInMemory are different quantities", () => {
+  it("a file can be fresh on disk while the server holds something else", async () => {
+    writeFileSync(
+      attrPath(),
+      JSON.stringify({ ...FIXTURE_ATTRIBUTE_DEFINITIONS, Extra: {} }, null, 2)
+    );
+    const harness = createToolHarness();
+    registerDataSource(harness.server, loader);
+    const out = JSON.parse(await harness.call("get_data_source"));
+
+    // The file is minutes old, so freshness says "fresh" …
+    expect(out.attributeDefinitions.freshness).toBe("fresh");
+    // … and the server is still serving what it read before the edit.
+    expect(out.staleInMemory).toContain(attrPath());
+  });
+
+  it("the hint says the comparison is by content, not by timestamp", async () => {
+    writeFileSync(
+      attrPath(),
+      JSON.stringify({ ...FIXTURE_ATTRIBUTE_DEFINITIONS, Extra: {} }, null, 2)
+    );
+    const harness = createToolHarness();
+    registerDataSource(harness.server, loader);
+    const out = JSON.parse(await harness.call("get_data_source"));
+    expect(out.hint).toContain("sha256");
+  });
+
+  it("says nothing when the server is current", async () => {
+    // 陰性対照 for both arms above.
+    const harness = createToolHarness();
+    registerDataSource(harness.server, loader);
+    const out = JSON.parse(await harness.call("get_data_source"));
+    expect(out.staleInMemory).toBeUndefined();
+  });
+});
+
+describe("the per-file report covers what the check tracks", () => {
+  it("names every file that staleInMemory can name", async () => {
+    // The two lists were 5 and 7. A reader who checked "every file reported"
+    // had two outside their view — reported by a consumer lane 2026-09-09.
+    const harness = createToolHarness();
+    registerDataSource(harness.server, loader);
+    const out = JSON.parse(await harness.call("get_data_source"));
+
+    const reported = new Set(
+      ["attributeDefinitions", "componentMetadata", "screenIdentity",
+       "bindingSemantics", "attributeSemantics", "platformSemantics", "coverage"]
+        .map((k) => out[k]?.path)
+        .filter(Boolean)
+    );
+    // Every path the checker watches must appear in the per-file section.
+    // Touch them all so the checker returns its full set.
+    for (const p of reported) {
+      writeFileSync(p as string, require("fs").readFileSync(p as string));
+    }
+    for (const p of loader.getChangedSinceLoad()) {
+      expect(reported.has(p)).toBe(true);
+    }
+  });
+
+  it("reports the coverage ledger, which the five-file version omitted", async () => {
+    const harness = createToolHarness();
+    registerDataSource(harness.server, loader);
+    const out = JSON.parse(await harness.call("get_data_source"));
+    expect(out.coverage?.path).toContain("coverage.json");
+  });
+});