@ashley-shrok/viewmodel-shell 3.7.0 → 3.9.0

package/agent-skill.md

@@ -63,6 +63,7 @@ Optional success-path fields, which may appear alone or alongside `vm`/`state`:
 | `busy` | Boolean. While `true`, drop user-initiated dispatches. Polls bypass. The next response that omits or sets `false` clears the lock. |
 | `preventUnload` | Boolean. While `true`, treat the page as having unsaved work — warn before navigating away. |
 | `rejected` | A SOFT (domain/validation) rejection — see below. The action was refused, but `vm`/`state` are still returned. |
+| `serverBuild` | A string id of the client bundle the server currently deploys. Present only when the app enables versioning. If you advertise your own build via the `X-VMS-Client-Build` request header and it differs from `serverBuild`, you are running against a rolled-forward server — see *Client build / version skew*. |
 
 **Failure:**
 
@@ -115,9 +116,17 @@ Optional success-path fields, which may appear alone or alongside `vm`/`state`:
 | `unknown_action` | The `name` in your action envelope does not match any handler in the current tree. |
 | `invalid_tree` | The server built a tree that violates a wire invariant (this is a server bug, not yours). |
 | `uncaught_exception` | The action handler threw. Treat as a 500-class failure. |
+| `stale_client` | Your request advertised an `X-VMS-Client-Build` header that no longer matches the server's current deployed build. The mutation was rejected **before your `_state` was read — nothing was applied.** The fix is to reload to the current app (re-`GET` the endpoint for a fresh `vm`/`state`), not to retry the same request. See *Client build / version skew*. |
 
 Stop on `ok: false`. Surface the message to the user. Do not retry blindly — most of these are deterministic.
 
+## Client build / version skew
+
+Optional, opt-in. When the app enables versioning, every response carries a `serverBuild` string (the client bundle the server currently deploys), and you may advertise the build you are running by sending an `X-VMS-Client-Build: <your-build-id>` header on every action POST.
+
+- **Detection.** On any successful response, if you sent a build and `serverBuild` differs from it, the server has rolled forward while you kept running an old bundle. Reload to the current app (re-`GET` the endpoint) so you are driving the current tree.
+- **Fail-closed guard.** If you send a mismatching `X-VMS-Client-Build`, a *mutating* action is rejected with `ok: false`, HTTP 400, `code: "stale_client"` — **before** your `_state` is deserialized, so nothing is applied. Do not retry the same request against the same build; reload first. If you do NOT send the header, no request is ever rejected on this basis (the guard only fires for a client that advertised a stale build).
+
 ## Auth
 
 The wire does not mandate an auth shape. If the app needs credentials, the app preamble above (or its own README) names them. Common patterns: a `Bearer` token in `Authorization`, a CSRF/anti-forgery token in a custom header, a session cookie. Send the same headers on every request, including polls and downloads. The `download` side-effect re-presents your auth headers when the agent fetches the file.

package/dist/browser.d.ts

@@ -3,6 +3,7 @@ export declare class BrowserAdapter implements Adapter {
     private container;
     private fileRegistry;
     private sa;
+    private diagWarned;
     private detailsOpenSnapshot;
     private sectionKeyCounter;
     private fitsObservers;
@@ -12,6 +13,13 @@ export declare class BrowserAdapter implements Adapter {
     storage(scope: "local" | "session", key: string, value: string): void;
     saveFile(data: Blob, filename: string, _contentType: string): void;
     setBusy(active: boolean): void;
+    /** 3.8.0 — force a full page reload. The shell calls this as the fail-closed
+     *  recovery for a `stale_client` rejection (a mutation refused because this
+     *  tab is running an out-of-date bundle). `window.location.reload()` pulls the
+     *  fresh, cache-revalidated shell + bundle. Fail-quiet by absence in core (the
+     *  `stale_client` VmsActionError already surfaced via onError), so this is a
+     *  plain implementation, not a fail-loud capability. */
+    reload(): void;
     /** Transient confirmation toast. Lazily creates/reuses a single fixed-corner
      *  host region (.vms-toast-region) appended to <body> so toasts stack and
      *  survive the container's innerHTML wipe on each render(); appends a
@@ -70,6 +78,15 @@ export declare class BrowserAdapter implements Adapter {
     /** FieldNode — reads value from `sa.read(bind)`; writes back on input/change.
      *  When `action` is set, it fires on Enter (text-like) or change (select) —
      *  the new value is already in state by that point. */
+    /** Warn to the dev console at most once per key (deduped over this adapter's
+     *  lifetime). Fires in dev AND prod — the client bundle can't tell them apart,
+     *  and prod telemetry that captures console.warn should see these too. */
+    private warnOnce;
+    /** Read a bind path, tolerating a bind-less field (file inputs) — null bind
+     *  reads nothing. */
+    private readBind;
+    /** Write to a bind path, no-op when the field has no bind (file inputs). */
+    private writeBind;
     private field;
     /** Forms-completeness (3.4.0) — apply disabled/readonly to the control and
      *  render help + error text below it, wiring aria-describedby / aria-invalid.

package/dist/browser.js

@@ -46,6 +46,11 @@ export class BrowserAdapter {
     container;
     fileRegistry = new Map();
     sa = noopStateAccess;
+    // Dev-console diagnostics dedup (3.9.0). Both [vms:no-bind] and
+    // [vms:type-mismatch] warn at most once per key over this adapter's lifetime.
+    // The client bundle can't distinguish dev/prod, so these fire in both — which
+    // is intentional: prod telemetry that captures console.warn sees them too.
+    diagWarned = new Set();
     // 1.2.0 — open-state snapshot for SectionNode.collapsible. Captured by
     // render() BEFORE this.container.innerHTML = "" by walking
     // [data-section-key] details elements; consumed by render() AFTER node()
@@ -198,6 +203,15 @@ export class BrowserAdapter {
     setBusy(active) {
         this.container.classList.toggle("vms-busy", active);
     }
+    /** 3.8.0 — force a full page reload. The shell calls this as the fail-closed
+     *  recovery for a `stale_client` rejection (a mutation refused because this
+     *  tab is running an out-of-date bundle). `window.location.reload()` pulls the
+     *  fresh, cache-revalidated shell + bundle. Fail-quiet by absence in core (the
+     *  `stale_client` VmsActionError already surfaced via onError), so this is a
+     *  plain implementation, not a fail-loud capability. */
+    reload() {
+        window.location.reload();
+    }
     /** Transient confirmation toast. Lazily creates/reuses a single fixed-corner
      *  host region (.vms-toast-region) appended to <body> so toasts stack and
      *  survive the container's innerHTML wipe on each render(); appends a
@@ -666,8 +680,35 @@ export class BrowserAdapter {
     /** FieldNode — reads value from `sa.read(bind)`; writes back on input/change.
      *  When `action` is set, it fires on Enter (text-like) or change (select) —
      *  the new value is already in state by that point. */
+    /** Warn to the dev console at most once per key (deduped over this adapter's
+     *  lifetime). Fires in dev AND prod — the client bundle can't tell them apart,
+     *  and prod telemetry that captures console.warn should see these too. */
+    warnOnce(key, msg) {
+        if (!this.diagWarned.has(key)) {
+            this.diagWarned.add(key);
+            console.warn(msg);
+        }
+    }
+    /** Read a bind path, tolerating a bind-less field (file inputs) — null bind
+     *  reads nothing. */
+    readBind(bind) {
+        return bind == null ? undefined : this.sa.read(bind);
+    }
+    /** Write to a bind path, no-op when the field has no bind (file inputs). */
+    writeBind(bind, value) {
+        if (bind != null)
+            this.sa.write(bind, value);
+    }
     field(n, parent, on) {
-        const stateValue = this.sa.read(n.bind);
+        const stateValue = this.readBind(n.bind);
+        // [vms:no-bind] — a value-bearing input with no bind renders but silently
+        // drops user input (nothing to persist to). Exclude `file` (bind is
+        // legitimately optional — the binary rides multipart) and `hidden`
+        // (server-authoritative, no user input).
+        if (n.inputType !== "file" && n.inputType !== "hidden" && n.bind == null) {
+            this.warnOnce("no-bind:" + n.name, "[vms:no-bind] FieldNode '" + n.name + "' (inputType=" + n.inputType +
+                ") has no bind — value-bearing inputs need a bind path to persist; the field renders but user input is dropped.");
+        }
         if (n.inputType === "hidden") {
             // Hidden fields don't write back — server is authoritative for hidden.
             const inp = document.createElement("input");
@@ -690,7 +731,7 @@ export class BrowserAdapter {
             inp.name = n.name;
             inp.checked = Boolean(stateValue);
             inp.addEventListener("change", () => {
-                this.sa.write(n.bind, inp.checked);
+                this.writeBind(n.bind, inp.checked);
             });
             wrapper.appendChild(inp);
             if (n.label) {
@@ -743,19 +784,19 @@ export class BrowserAdapter {
             // explicit empty the server can reject, never a silently-missing key.
             if (isMulti) {
                 if (!Array.isArray(stateValue)) {
-                    this.sa.write(n.bind, Array.from(sel.selectedOptions, o => o.value));
+                    this.writeBind(n.bind, Array.from(sel.selectedOptions, o => o.value));
                 }
             }
             else if (stateValue === undefined || String(stateValue) !== sel.value) {
-                this.sa.write(n.bind, sel.value);
+                this.writeBind(n.bind, sel.value);
             }
             sel.addEventListener("change", () => {
                 if (isMulti) {
                     const arr = Array.from(sel.selectedOptions).map(o => o.value);
-                    this.sa.write(n.bind, arr);
+                    this.writeBind(n.bind, arr);
                 }
                 else {
-                    this.sa.write(n.bind, sel.value);
+                    this.writeBind(n.bind, sel.value);
                 }
                 if (n.action)
                     on({ name: n.action.name });
@@ -782,14 +823,31 @@ export class BrowserAdapter {
                 const file = inp.files?.[0];
                 if (file) {
                     this.fileRegistry.set(n.name, file);
+                    // [vms:type-mismatch] — OBSERVABLE-SUBSET diagnostic. The client is
+                    // untyped JS: it CANNOT know a state slot's *declared* server type, so
+                    // it only catches the observable case where a file object overwrites a
+                    // slot that already holds a scalar. It does NOT catch an empty/null slot
+                    // typed string-map server-side — certain detection of that is a
+                    // server-side `_state` deserialize diagnostic (a separate follow-up).
+                    if (n.bind != null) {
+                        const existing = this.readBind(n.bind);
+                        if (existing != null && typeof existing !== "object") {
+                            this.warnOnce("type-mismatch:" + n.name + ":" + n.bind, "[vms:type-mismatch] file FieldNode '" + n.name +
+                                "' writes a {filename,size} object into bind '" + n.bind +
+                                "', whose current state value is a " + (typeof existing) +
+                                " — if that slot is typed string/string-map the _state round-trip will FAIL (cannot convert object to String). Give the file field an object-typed slot, or omit bind (the file rides multipart regardless).");
+                        }
+                    }
                     // Per Phase-6 decision: the picked file is visible in state as a
                     // serialization-safe placeholder; the binary travels on the
-                    // multipart side channel.
-                    this.sa.write(n.bind, { filename: file.name, size: file.size });
+                    // multipart side channel. Backward-compat: apps binding a file field
+                    // to an object slot still get the placeholder. A bind-less file input
+                    // writes nothing (writeBind no-ops) — the binary rides multipart.
+                    this.writeBind(n.bind, { filename: file.name, size: file.size });
                 }
                 else {
                     this.fileRegistry.delete(n.name);
-                    this.sa.write(n.bind, null);
+                    this.writeBind(n.bind, null);
                 }
             });
             wrapper.appendChild(inp);
@@ -804,7 +862,7 @@ export class BrowserAdapter {
             ta.value = stateValue == null ? "" : String(stateValue);
             if (n.required)
                 ta.required = true;
-            ta.addEventListener("input", () => { this.sa.write(n.bind, ta.value); });
+            ta.addEventListener("input", () => { this.writeBind(n.bind, ta.value); });
             wrapper.appendChild(ta);
         }
         else if (n.inputType === "code") {
@@ -827,7 +885,7 @@ export class BrowserAdapter {
             ta.value = stateValue == null ? "" : String(stateValue);
             if (n.required)
                 ta.required = true;
-            ta.addEventListener("input", () => { this.sa.write(n.bind, ta.value); });
+            ta.addEventListener("input", () => { this.writeBind(n.bind, ta.value); });
             ta.addEventListener("keydown", (e) => {
                 if (e.key === "Tab") {
                     e.preventDefault();
@@ -835,7 +893,7 @@ export class BrowserAdapter {
                     const end = ta.selectionEnd ?? 0;
                     ta.value = ta.value.slice(0, start) + "\t" + ta.value.slice(end);
                     ta.selectionStart = ta.selectionEnd = start + 1;
-                    this.sa.write(n.bind, ta.value);
+                    this.writeBind(n.bind, ta.value);
                 }
             });
             wrapper.appendChild(ta);
@@ -851,7 +909,7 @@ export class BrowserAdapter {
             inp.value = stateValue == null ? "" : String(stateValue);
             if (n.required)
                 inp.required = true;
-            inp.addEventListener("input", () => { this.sa.write(n.bind, inp.value); });
+            inp.addEventListener("input", () => { this.writeBind(n.bind, inp.value); });
             if (n.action) {
                 const action = n.action;
                 inp.addEventListener("keydown", (e) => {
@@ -860,7 +918,7 @@ export class BrowserAdapter {
                         // Belt-and-suspenders: flush the latest value to state before
                         // dispatching, in case the browser hasn't fired `input` yet
                         // (e.g. an autofill that lands then submits).
-                        this.sa.write(n.bind, inp.value);
+                        this.writeBind(n.bind, inp.value);
                         on({ name: action.name });
                     }
                 });

package/dist/index.d.ts

@@ -74,6 +74,19 @@ export interface Adapter {
         tone?: string;
         durationMs?: number;
     }): void;
+    /** 3.8.0 — force a full reload of the running client (the browser adapter
+     *  calls `window.location.reload()`). The shell invokes this ONLY as the
+     *  fail-closed recovery for a `stale_client` rejection: the server refused a
+     *  mutation because the tab is running an out-of-date bundle, nothing was
+     *  applied, and reloading to the fresh bundle is the only honest recovery.
+     *  FAIL-QUIET BY ABSENCE — modeled on setBusy/toast, NOT on
+     *  navigate/storage/saveFile: the `stale_client` failure ALSO surfaces via
+     *  `onError` (as a VmsActionError), so an adapter without this verb still
+     *  learns of the skew and can recover its own way. A missing `reload` is
+     *  therefore NOT a silent failure, so the core MUST NOT call failCapability
+     *  when it is absent (non-browser targets like the TUI have no reload
+     *  concept). */
+    reload?(): void;
 }
 export type ViewNode = PageNode | SectionNode | ListNode | ListItemNode | FormNode | FieldNode | CheckboxNode | ButtonNode | TextNode | LinkNode | ImageNode | StatBarNode | TabsNode | ProgressNode | ModalNode | TableNode | CopyButtonNode | DividerNode | FitsNode | EmptyStateNode | BadgeNode;
 export interface PageNode {
@@ -254,8 +267,15 @@ export interface FieldNode {
     type: "field";
     name: string;
     inputType: "text" | "email" | "password" | "number" | "date" | "time" | "datetime-local" | "textarea" | "hidden" | "file" | "select" | "select-multiple" | "checkbox" | "code";
-    /** Path into state where this input reads its current value and writes user changes (e.g. `fields.title`). */
-    bind: string;
+    /** Path into state where this input reads its current value and writes user
+     *  changes (e.g. `fields.title`). REQUIRED for value-bearing inputs
+     *  (text/email/password/number/date/time/datetime-local/textarea/select/
+     *  select-multiple/checkbox/code) and OPTIONAL for `file` inputs — a file
+     *  input's binary rides the multipart side channel (fileRegistry keyed on
+     *  `name`), so omit `bind` on a file input to avoid writing a
+     *  `{filename,size}` placeholder object into state (which breaks a
+     *  string/string-map state slot on round-trip). */
+    bind?: string;
     label?: string;
     placeholder?: string;
     required?: boolean;
@@ -620,6 +640,16 @@ export interface ShellOptions {
      *  The server can override the next interval via ShellResponse.nextPollIn, or stop polling by
      *  omitting nextPollIn when no pollInterval is configured. */
     pollInterval?: number;
+    /** 3.8.0 — the id of the client bundle this shell instance is running (the app
+     *  injects it at build time, e.g. from a Vite `define`/env — VMS never derives
+     *  it, staying platform-agnostic). When set, the shell (1) attaches it as the
+     *  `X-VMS-Client-Build` header on every action POST so the server can
+     *  fail-closed on a stale mutation, and (2) compares it against a response's
+     *  `serverBuild` and fires a `VmsVersionSkewError` via `onError` when they
+     *  differ (AFTER rendering — detection never swallows the render). Absent =
+     *  the whole version-skew feature is off; behavior is byte-identical to a
+     *  build without it. */
+    clientBuildId?: string;
 }
 export interface ShellSideEffect {
     /** "set-local-storage" | "set-session-storage" | "download" | "toast" — unknown types are silently ignored. */
@@ -671,6 +701,23 @@ export declare class VmsActionError extends Error {
     /** Shortcut to `errors[0]?.code`. Undefined when the first entry has no code. */
     get code(): string | undefined;
 }
+/**
+ * 3.8.0 — surfaced via `onError` when a SUCCESS response's `serverBuild` differs
+ * from the configured `ShellOptions.clientBuildId` (client/server version skew:
+ * a long-lived tab is running an out-of-date bundle against a server that has
+ * rolled forward). This is fired AFTER the response renders normally — it never
+ * swallows the render — so it is a loud, catchable signal, not a failure. The
+ * app distinguishes it with `if (err instanceof VmsVersionSkewError)` (typically
+ * to prompt the user to reload). Distinct from `VmsActionError`: this rides on a
+ * fully-successful `ok:true` response.
+ */
+export declare class VmsVersionSkewError extends Error {
+    readonly serverBuild: string;
+    readonly clientBuild: string;
+    /** Stable discriminator for this failure class (parallels VmsActionError.code). */
+    readonly code = "version_skew";
+    constructor(serverBuild: string, clientBuild: string);
+}
 export interface ShellResponse {
     vm: ViewNode;
     state: unknown;
@@ -698,6 +745,11 @@ export interface ShellResponse {
     ok?: boolean;
     /** 1.0.0 — structured error entries. Present when `ok: false`. */
     errors?: ErrorEntry[];
+    /** 3.8.0 — the server's current-deployed client-build id, stamped on every
+     *  response when the app configures versioning. Compared against
+     *  `ShellOptions.clientBuildId` to detect a never-reloaded tab running against
+     *  a rolled-forward server. Absent = the feature is off. */
+    serverBuild?: string;
 }
 export declare class ViewModelShell {
     private options;
@@ -747,6 +799,16 @@ export declare class ViewModelShell {
     private stateAccessForAdapter;
     private failCapability;
     private processResponse;
+    /**
+     * 3.8.0 — Phase 1 detection. When the app configured `clientBuildId` and the
+     * response carries a differing `serverBuild`, fire a `VmsVersionSkewError`
+     * through the existing `onError` seam so the app can react (e.g. prompt a
+     * reload). Called from BOTH success paths (`load()` and `processResponse()`)
+     * AFTER the response has rendered — detection is additive and never affects
+     * the render. No-op when `clientBuildId` is unset, `serverBuild` is absent, or
+     * the two ids match.
+     */
+    private checkVersionSkew;
     private schedulePoll;
     /**
      * Authenticated download: fetch the URL with getRequestHeaders() merged

package/dist/index.js

@@ -36,6 +36,29 @@ export class VmsActionError extends Error {
         return this.errors[0]?.code;
     }
 }
+/**
+ * 3.8.0 — surfaced via `onError` when a SUCCESS response's `serverBuild` differs
+ * from the configured `ShellOptions.clientBuildId` (client/server version skew:
+ * a long-lived tab is running an out-of-date bundle against a server that has
+ * rolled forward). This is fired AFTER the response renders normally — it never
+ * swallows the render — so it is a loud, catchable signal, not a failure. The
+ * app distinguishes it with `if (err instanceof VmsVersionSkewError)` (typically
+ * to prompt the user to reload). Distinct from `VmsActionError`: this rides on a
+ * fully-successful `ok:true` response.
+ */
+export class VmsVersionSkewError extends Error {
+    serverBuild;
+    clientBuild;
+    /** Stable discriminator for this failure class (parallels VmsActionError.code). */
+    code = "version_skew";
+    constructor(serverBuild, clientBuild) {
+        super(`Client build "${clientBuild}" is out of date — the server is now serving ` +
+            `build "${serverBuild}". Reload to get the current app.`);
+        this.serverBuild = serverBuild;
+        this.clientBuild = clientBuild;
+        this.name = "VmsVersionSkewError";
+    }
+}
 export class ViewModelShell {
     options;
     currentVm = null;
@@ -92,6 +115,10 @@ export class ViewModelShell {
             this.syncBusy();
             adapter.render(body.vm, (action) => this.dispatch(action), this.stateAccessForAdapter());
             this.schedulePoll(body.nextPollIn);
+            // 3.8.0 — version-skew DETECTION (Phase 1). Render happened above FIRST;
+            // this only fires a loud, catchable signal and never affects the render.
+            // At initial load the ids normally match (fresh bundle) so it's a no-op.
+            this.checkVersionSkew(body);
         }
         catch (err) {
             const error = err instanceof Error ? err : new Error(String(err));
@@ -140,9 +167,15 @@ export class ViewModelShell {
             }
             const extraHeaders = this.options.getRequestHeaders ? await this.options.getRequestHeaders() : {};
             const adapter = this.options.adapter;
+            // 3.8.0 — Phase 2 fail-closed guard: advertise the running bundle id so the
+            // server can reject a mutation from a stale client BEFORE deserializing
+            // _state. Merged AFTER getRequestHeaders() so app headers can't clobber it.
+            const headers = { Accept: "application/json", ...extraHeaders };
+            if (this.options.clientBuildId)
+                headers["X-VMS-Client-Build"] = this.options.clientBuildId;
             const init = {
                 method: "POST",
-                headers: { Accept: "application/json", ...extraHeaders },
+                headers,
                 body: form,
             };
             let res;
@@ -179,6 +212,17 @@ export class ViewModelShell {
         catch (err) {
             const error = err instanceof Error ? err : new Error(String(err));
             onError ? onError(error) : console.error("[ViewModelShell]", error);
+            // 3.8.0 — Phase 2 fail-closed recovery. The server rejected this mutation
+            // because the tab is running a stale bundle (nothing was applied). Order
+            // per the locked design: surface via onError FIRST (done above), THEN
+            // force a reload to the fresh bundle — the only safe recovery. reload is
+            // fail-quiet by absence (the VmsActionError already surfaced), so this is
+            // a plain optional-chain call, and we return before the below re-render
+            // (the page is reloading; re-rendering the stale tree is pointless).
+            if (error instanceof VmsActionError && error.code === "stale_client") {
+                this.options.adapter.reload?.();
+                return;
+            }
             // 0.8.0 (#11) — re-render the current VM on dispatch error. Adapters
             // may have applied client-side ephemeral state in onAction handlers
             // (e.g., BrowserAdapter swaps button text for ButtonNode.pendingLabel).
@@ -337,6 +381,27 @@ export class ViewModelShell {
             this.currentState = body.state;
         }
         this.schedulePoll(body.nextPollIn);
+        // 3.8.0 — version-skew DETECTION (Phase 1) on the dispatch / poll / push
+        // success path. Fired AFTER the render above (never swallows it). A redirect
+        // response returned early above, so this is the non-redirect path only.
+        this.checkVersionSkew(body);
+    }
+    /**
+     * 3.8.0 — Phase 1 detection. When the app configured `clientBuildId` and the
+     * response carries a differing `serverBuild`, fire a `VmsVersionSkewError`
+     * through the existing `onError` seam so the app can react (e.g. prompt a
+     * reload). Called from BOTH success paths (`load()` and `processResponse()`)
+     * AFTER the response has rendered — detection is additive and never affects
+     * the render. No-op when `clientBuildId` is unset, `serverBuild` is absent, or
+     * the two ids match.
+     */
+    checkVersionSkew(body) {
+        const clientBuild = this.options.clientBuildId;
+        const serverBuild = body.serverBuild;
+        if (clientBuild && serverBuild && serverBuild !== clientBuild) {
+            const err = new VmsVersionSkewError(serverBuild, clientBuild);
+            this.options.onError ? this.options.onError(err) : console.error("[ViewModelShell]", err);
+        }
     }
     schedulePoll(nextPollIn) {
         const delay = nextPollIn ?? this.options.pollInterval;

package/dist/server.d.ts

@@ -62,6 +62,12 @@ export interface ShellResponseBody<TState> {
      *  ErrorEntry {path?, message, code?} shape; `path` is OPTIONAL — a violation
      *  with no path is a form/action-level rejection (vs field-bound when set). */
     rejected?: ShellRejection;
+    /** 3.8.0 — the server's current-deployed client-build id. Normally stamped
+     *  automatically by `createAction(handler, { currentBuild })`; also settable
+     *  by hand on a response built outside createAction (e.g. a GET handler or a
+     *  server-pushed SSE/WebSocket body) so those responses carry `serverBuild`
+     *  too. Absent = the versioning feature is off for this response. */
+    serverBuild?: string;
 }
 /** Wrapper for a soft-validation rejection on an ok:true response. */
 export interface ShellRejection {
@@ -207,6 +213,10 @@ export declare const ERR_CODES: {
     readonly INVALID_TREE: "invalid_tree";
     /** App handler threw an unrecognised exception. HTTP 500. */
     readonly UNCAUGHT: "uncaught_exception";
+    /** 3.8.0 — request's `X-VMS-Client-Build` header ≠ the server's current-deployed
+     *  build id (a stale, never-reloaded tab attempting a mutation). The request is
+     *  rejected BEFORE `_state` is deserialized. HTTP 400. */
+    readonly STALE_CLIENT: "stale_client";
 };
 /** Union type of the framework error codes from ERR_CODES. Useful for narrowing `errors[0].code`. */
 export type ErrCode = typeof ERR_CODES[keyof typeof ERR_CODES];
@@ -224,5 +234,19 @@ export type ErrCode = typeof ERR_CODES[keyof typeof ERR_CODES];
  *     const state = applyAction(payload);
  *     return { vm: buildVm(state), state };
  *   }));
+ *
+ * 3.8.0 — optional version-skew half. Pass `{ currentBuild }` (the id of the
+ * client bundle this server currently deploys) to opt in:
+ *   - GUARD (fail-closed): if the request carries an `X-VMS-Client-Build` header
+ *     whose value ≠ `currentBuild`, the mutation is rejected with a 400
+ *     `stale_client` envelope BEFORE the body/`_state` is deserialized (the
+ *     app's typed handler never runs on a stale client's payload).
+ *   - STAMP: every successful response includes `serverBuild: currentBuild` so
+ *     the client can detect a never-reloaded tab.
+ * Omit `currentBuild` (or pass nothing) and behavior is byte-identical to
+ * before — no guard, no stamp. The existing handler-only call signature is
+ * unchanged.
  */
-export declare function createAction<TState>(handler: (payload: ActionPayload<TState>) => Promise<ShellResponseBody<TState>> | ShellResponseBody<TState>): (request: Request) => Promise<Response>;
+export declare function createAction<TState>(handler: (payload: ActionPayload<TState>) => Promise<ShellResponseBody<TState>> | ShellResponseBody<TState>, options?: {
+    currentBuild?: string;
+}): (request: Request) => Promise<Response>;

package/dist/server.js

@@ -574,6 +574,10 @@ export const ERR_CODES = {
     INVALID_TREE: "invalid_tree",
     /** App handler threw an unrecognised exception. HTTP 500. */
     UNCAUGHT: "uncaught_exception",
+    /** 3.8.0 — request's `X-VMS-Client-Build` header ≠ the server's current-deployed
+     *  build id (a stale, never-reloaded tab attempting a mutation). The request is
+     *  rejected BEFORE `_state` is deserialized. HTTP 400. */
+    STALE_CLIENT: "stale_client",
 };
 /**
  * Build a JSON-stringified `{ok: false, errors: [...]}` envelope.
@@ -623,9 +627,35 @@ function jsonResponse(body, status) {
  *     const state = applyAction(payload);
  *     return { vm: buildVm(state), state };
  *   }));
+ *
+ * 3.8.0 — optional version-skew half. Pass `{ currentBuild }` (the id of the
+ * client bundle this server currently deploys) to opt in:
+ *   - GUARD (fail-closed): if the request carries an `X-VMS-Client-Build` header
+ *     whose value ≠ `currentBuild`, the mutation is rejected with a 400
+ *     `stale_client` envelope BEFORE the body/`_state` is deserialized (the
+ *     app's typed handler never runs on a stale client's payload).
+ *   - STAMP: every successful response includes `serverBuild: currentBuild` so
+ *     the client can detect a never-reloaded tab.
+ * Omit `currentBuild` (or pass nothing) and behavior is byte-identical to
+ * before — no guard, no stamp. The existing handler-only call signature is
+ * unchanged.
  */
-export function createAction(handler) {
+export function createAction(handler, options) {
+    const currentBuild = options?.currentBuild;
     return async (request) => {
+        // 3.8.0 — fail-closed stale-client guard. Runs FIRST, before any body parse,
+        // so a stale client's `_state` is never deserialized. Only when the app
+        // configured `currentBuild` AND the header is present AND it mismatches.
+        if (currentBuild) {
+            const clientBuild = request.headers.get("x-vms-client-build");
+            if (clientBuild !== null && clientBuild !== currentBuild) {
+                return jsonResponse(errorEnvelope([{
+                        message: `Stale client: request build "${clientBuild}" does not match the ` +
+                            `current deployed build "${currentBuild}". Reload to continue.`,
+                        code: ERR_CODES.STALE_CLIENT,
+                    }]), 400);
+            }
+        }
         const contentType = request.headers.get("content-type") ?? "";
         let payload;
         try {
@@ -676,6 +706,12 @@ export function createAction(handler) {
         }
         // Phase 07 / ERROR-01 — every successful response acquires ok:true at the
         // response edge. Controllers / app handlers do NOT set ok themselves.
-        return jsonResponse(JSON.stringify({ ok: true, ...result }), 200);
+        // 3.8.0 — stamp serverBuild when versioning is configured. Placed after the
+        // result spread so `currentBuild` wins over any hand-set result.serverBuild.
+        return jsonResponse(JSON.stringify({
+            ok: true,
+            ...result,
+            ...(currentBuild ? { serverBuild: currentBuild } : {}),
+        }), 200);
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "3.7.0",
+  "version": "3.9.0",
   "description": "A server-driven UI framework where the wire format is structured enough that agents can build full-stack apps without ever opening a browser and all UI tests are pure unit tests with no browser runtime. Server returns a JSON tree of typed nodes; a thin TypeScript adapter renders it to DOM. Backend-agnostic \u2014 a .NET reference backend ships with the repo, but any language can produce the JSON contract.",
   "type": "module",
   "license": "MIT",