monkrb 0.15.0

data/lib/monk/environment.rb

@@ -0,0 +1,50 @@
+require_relative "settings"
+
+module Monk
+  # The tier an app is running under -- CONTEXT.md's MONK_ENV entry.
+  # A small, frozen value object wrapping Settings[:monk_env] (never
+  # cached across calls itself: each Monk.env call builds a fresh, local
+  # instance, cheap since it never crosses a Ractor boundary -- only the
+  # String it wraps, read from Settings' already-frozen values, does).
+  #
+  # Predicates are four plain, hand-written methods, not one
+  # define_method(&block) per MONK_ENV_VALUES entry: a method backed by a
+  # Proc closure raises "defined with an un-shareable Proc in a different
+  # Ractor" the first time a *different* Ractor than the one that defined
+  # it calls it -- discovered by this class's own real-Ractor test.
+  # Ordinary `def` methods compile to plain bytecode with no Proc
+  # involved, so they carry no such restriction (the same reason View's
+  # compiled templates -- ADR 0004 -- are real methods, not blocks).
+  class Environment
+    attr_reader :value
+
+    def initialize(value)
+      @value = value
+      freeze
+    end
+
+    def development?
+      value == "development"
+    end
+
+    def test?
+      value == "test"
+    end
+
+    def staging?
+      value == "staging"
+    end
+
+    def production?
+      value == "production"
+    end
+
+    def to_s
+      value
+    end
+  end
+
+  def self.env
+    Environment.new(Settings[:monk_env])
+  end
+end

data/lib/monk/errors.rb

@@ -0,0 +1,37 @@
+module Monk
+  class InvalidMonkEnvError < StandardError
+  end
+
+  class InvalidLogLevelError < StandardError
+  end
+
+  class DuplicateSettingError < StandardError
+  end
+
+  class MissingSettingError < StandardError
+  end
+
+  class UnknownSettingError < StandardError
+  end
+
+  class SettingsFrozenError < StandardError
+  end
+
+  class UnshareableBlockError < StandardError
+  end
+
+  class UnshareableModelError < StandardError
+  end
+
+  class UnshareableRouteError < StandardError
+  end
+
+  class TemplateNotFoundError < StandardError
+  end
+
+  class TemplateSyntaxError < StandardError
+  end
+
+  class ScaffoldExistsError < StandardError
+  end
+end

data/lib/monk/freeze_hooks.rb

@@ -0,0 +1,23 @@
+module Monk
+  # Objects responding to #freeze_registry! that Base#freeze! (Seam B) must
+  # seal at boot, so a worker Ractor can read their config without tripping
+  # Ractor::IsolationError. Not persistence-specific: Monk::Persistence::
+  # Registry backends and Monk::Auth both register themselves here.
+  def self.freeze_hooks
+    @freeze_hooks ||= []
+  end
+
+  # Extracted out of Base#freeze! (docs/history/plan-websocket.md Phase 5 step 20):
+  # Monk::Base.freeze! calls this, but so can any process that never
+  # touches Monk::Base at all -- Monk::WebSocket::Server's boot script,
+  # per Decision 1 -- and still needs Monk::Auth/Monk::Persistence config
+  # readable from a worker Ractor. Without this, that config stays an
+  # unfrozen Hash, and the first Monk::Auth.verify call from inside a
+  # connection Ractor raises Ractor::IsolationError -- the same bug class
+  # already hit and fixed for persistence (Phase 4/5) and for Base-booted
+  # auth (docs/history/plan-auth.md Phase 5 step 17).
+  def self.freeze!
+    freeze_hooks.each(&:freeze_registry!)
+    Persistence::Model.freeze_all!
+  end
+end

data/lib/monk/live/client/idiomorph.LICENSE

@@ -0,0 +1,13 @@
+Zero-Clause BSD
+=============
+
+Permission to use, copy, modify, and/or distribute this software for
+any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE
+FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY
+DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
+OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

data/lib/monk/live/client/idiomorph.js

@@ -0,0 +1,4 @@
+/* idiomorph 0.7.3 (Zero-Clause BSD, see idiomorph.LICENSE), vendored from dist/idiomorph.min.js.
+   Only change: the `export` line at the end, so it loads as an ES module. */
+var Idiomorph=function(){"use strict";const e=()=>{};const n={morphStyle:"outerHTML",callbacks:{beforeNodeAdded:e,afterNodeAdded:e,beforeNodeMorphed:e,afterNodeMorphed:e,beforeNodeRemoved:e,afterNodeRemoved:e,beforeAttributeUpdated:e},head:{style:"merge",shouldPreserve:e=>e.getAttribute("im-preserve")==="true",shouldReAppend:e=>e.getAttribute("im-re-append")==="true",shouldRemove:e,afterHeadMorphed:e},restoreFocus:true};function t(t,e,n={}){t=d(t);const r=f(e);const o=u(t,r,n);const i=a(o,()=>{return c(o,t,r,e=>{if(e.morphStyle==="innerHTML"){s(e,t,r);return Array.from(t.childNodes)}else{return l(e,t,r)}})});o.pantry.remove();return i}function l(e,t,n){const r=f(t);s(e,r,n,t,t.nextSibling);return Array.from(r.childNodes)}function a(e,t){if(!e.config.restoreFocus)return t();let n=document.activeElement;if(!(n instanceof HTMLInputElement||n instanceof HTMLTextAreaElement)){return t()}const{id:r,selectionStart:o,selectionEnd:i}=n;const l=t();if(r&&r!==document.activeElement?.id){n=e.target.querySelector(`[id="${r}"]`);n?.focus()}if(n&&!n.selectionEnd&&i){n.setSelectionRange(o,i)}return l}const s=function(){function e(e,t,n,r=null,o=null){if(t instanceof HTMLTemplateElement&&n instanceof HTMLTemplateElement){t=t.content;n=n.content}r||=t.firstChild;for(const i of n.childNodes){if(r&&r!=o){const a=d(e,i,r,o);if(a){if(a!==r){m(e,r,a)}p(a,i,e);r=a.nextSibling;continue}}if(i instanceof Element&&e.persistentIds.has(i.id)){const s=h(t,i.id,r,e);p(s,i,e);r=s.nextSibling;continue}const l=u(t,i,r,e);if(l){r=l.nextSibling}}while(r&&r!=o){const c=r;r=r.nextSibling;f(e,c)}}function u(e,t,n,r){if(r.callbacks.beforeNodeAdded(t)===false)return null;if(r.idMap.has(t)){const o=document.createElement(t.tagName);e.insertBefore(o,n);p(o,t,r);r.callbacks.afterNodeAdded(o);return o}else{const i=document.importNode(t,true);e.insertBefore(i,n);r.callbacks.afterNodeAdded(i);return i}}const d=function(){function e(e,t,n,r){let o=null;let i=t.nextSibling;let l=0;let a=n;while(a&&a!=r){if(c(a,t)){if(s(e,a,t)){return a}if(o===null){if(!e.idMap.has(a)){o=a}}}if(o===null&&i&&c(a,i)){l++;i=i.nextSibling;if(l>=2){o=undefined}}if(a.contains(document.activeElement))break;a=a.nextSibling}return o||null}function s(e,t,n){let r=e.idMap.get(t);let o=e.idMap.get(n);if(!o||!r)return false;for(const i of r){if(o.has(i)){return true}}return false}function c(e,t){const n=e;const r=t;return n.nodeType===r.nodeType&&n.tagName===r.tagName&&(!n.id||n.id===r.id)}return e}();function f(e,t){if(e.idMap.has(t)){l(e.pantry,t,null)}else{if(e.callbacks.beforeNodeRemoved(t)===false)return;t.parentNode?.removeChild(t);e.callbacks.afterNodeRemoved(t)}}function m(t,e,n){let r=e;while(r&&r!==n){let e=r;r=r.nextSibling;f(t,e)}return r}function h(e,t,n,r){const o=r.target.id===t&&r.target||r.target.querySelector(`[id="${t}"]`)||r.pantry.querySelector(`[id="${t}"]`);i(o,r);l(e,o,n);return o}function i(t,n){const r=t.id;while(t=t.parentNode){let e=n.idMap.get(t);if(e){e.delete(r);if(!e.size){n.idMap.delete(t)}}}}function l(t,n,r){if(t.moveBefore){try{t.moveBefore(n,r)}catch(e){t.insertBefore(n,r)}}else{t.insertBefore(n,r)}}return e}();const p=function(){function e(e,t,n){if(n.ignoreActive&&e===document.activeElement){return null}if(n.callbacks.beforeNodeMorphed(e,t)===false){return e}if(e instanceof HTMLHeadElement&&n.head.ignore){}else if(e instanceof HTMLHeadElement&&n.head.style!=="morph"){m(e,t,n)}else{r(e,t,n);if(!f(e,n)){s(n,e,t)}}n.callbacks.afterNodeMorphed(e,t);return e}function r(e,t,n){let r=t.nodeType;if(r===1){const o=e;const i=t;const l=o.attributes;const a=i.attributes;for(const s of a){if(d(s.name,o,"update",n)){continue}if(o.getAttribute(s.name)!==s.value){o.setAttribute(s.name,s.value)}}for(let e=l.length-1;0<=e;e--){const c=l[e];if(!c)continue;if(!i.hasAttribute(c.name)){if(d(c.name,o,"remove",n)){continue}o.removeAttribute(c.name)}}if(!f(o,n)){u(o,i,n)}}if(r===8||r===3){if(e.nodeValue!==t.nodeValue){e.nodeValue=t.nodeValue}}}function u(n,r,o){if(n instanceof HTMLInputElement&&r instanceof HTMLInputElement&&r.type!=="file"){let e=r.value;let t=n.value;i(n,r,"checked",o);i(n,r,"disabled",o);if(!r.hasAttribute("value")){if(!d("value",n,"remove",o)){n.value="";n.removeAttribute("value")}}else if(t!==e){if(!d("value",n,"update",o)){n.setAttribute("value",e);n.value=e}}}else if(n instanceof HTMLOptionElement&&r instanceof HTMLOptionElement){i(n,r,"selected",o)}else if(n instanceof HTMLTextAreaElement&&r instanceof HTMLTextAreaElement){let e=r.value;let t=n.value;if(d("value",n,"update",o)){return}if(e!==t){n.value=e}if(n.firstChild&&n.firstChild.nodeValue!==e){n.firstChild.nodeValue=e}}}function i(e,t,n,r){const o=t[n],i=e[n];if(o!==i){const l=d(n,e,"update",r);if(!l){e[n]=t[n]}if(o){if(!l){e.setAttribute(n,"")}}else{if(!d(n,e,"remove",r)){e.removeAttribute(n)}}}}function d(e,t,n,r){if(e==="value"&&r.ignoreActiveValue&&t===document.activeElement){return true}return r.callbacks.beforeAttributeUpdated(e,t,n)===false}function f(e,t){return!!t.ignoreActiveValue&&e===document.activeElement&&e!==document.body}return e}();function c(t,e,n,r){if(t.head.block){const o=e.querySelector("head");const i=n.querySelector("head");if(o&&i){const l=m(o,i,t);return Promise.all(l).then(()=>{const e=Object.assign(t,{head:{block:false,ignore:true}});return r(e)})}}return r(t)}function m(e,t,r){let o=[];let i=[];let l=[];let a=[];let s=new Map;for(const n of t.children){s.set(n.outerHTML,n)}for(const u of e.children){let e=s.has(u.outerHTML);let t=r.head.shouldReAppend(u);let n=r.head.shouldPreserve(u);if(e||n){if(t){i.push(u)}else{s.delete(u.outerHTML);l.push(u)}}else{if(r.head.style==="append"){if(t){i.push(u);a.push(u)}}else{if(r.head.shouldRemove(u)!==false){i.push(u)}}}}a.push(...s.values());let c=[];for(const d of a){let n=document.createRange().createContextualFragment(d.outerHTML).firstChild;if(r.callbacks.beforeNodeAdded(n)!==false){if("href"in n&&n.href||"src"in n&&n.src){let t;let e=new Promise(function(e){t=e});n.addEventListener("load",function(){t()});c.push(e)}e.appendChild(n);r.callbacks.afterNodeAdded(n);o.push(n)}}for(const f of i){if(r.callbacks.beforeNodeRemoved(f)!==false){e.removeChild(f);r.callbacks.afterNodeRemoved(f)}}r.head.afterHeadMorphed(e,{added:o,kept:l,removed:i});return c}const u=function(){function e(e,t,n){const{persistentIds:r,idMap:o}=d(e,t);const i=a(n);const l=i.morphStyle||"outerHTML";if(!["innerHTML","outerHTML"].includes(l)){throw`Do not understand how to morph style ${l}`}return{target:e,newContent:t,config:i,morphStyle:l,ignoreActive:i.ignoreActive,ignoreActiveValue:i.ignoreActiveValue,restoreFocus:i.restoreFocus,idMap:o,persistentIds:r,pantry:s(),callbacks:i.callbacks,head:i.head}}function a(e){let t=Object.assign({},n);Object.assign(t,e);t.callbacks=Object.assign({},n.callbacks,e.callbacks);t.head=Object.assign({},n.head,e.head);return t}function s(){const e=document.createElement("div");e.hidden=true;document.body.insertAdjacentElement("afterend",e);return e}function c(e){let t=Array.from(e.querySelectorAll("[id]"));if(e.id){t.push(e)}return t}function u(n,e,r,t){for(const o of t){if(e.has(o.id)){let t=o;while(t){let e=n.get(t);if(e==null){e=new Set;n.set(t,e)}e.add(o.id);if(t===r)break;t=t.parentElement}}}}function d(e,t){const n=c(e);const r=c(t);const o=f(n,r);let i=new Map;u(i,o,e,n);const l=t.__idiomorphRoot||t;u(i,o,l,r);return{persistentIds:o,idMap:i}}function f(e,t){let n=new Set;let r=new Map;for(const{id:i,tagName:l}of e){if(r.has(i)){n.add(i)}else{r.set(i,l)}}let o=new Set;for(const{id:i,tagName:l}of t){if(o.has(i)){n.add(i)}else if(r.get(i)===l){o.add(i)}}for(const i of n){o.delete(i)}return o}return e}();const{normalizeElement:d,normalizeParent:f}=function(){const o=new WeakSet;function e(e){if(e instanceof Document){return e.documentElement}else{return e}}function r(e){if(e==null){return document.createElement("div")}else if(typeof e==="string"){return r(l(e))}else if(o.has(e)){return e}else if(e instanceof Node){if(e.parentNode){return new i(e)}else{const t=document.createElement("div");t.append(e);return t}}else{const t=document.createElement("div");for(const n of[...e]){t.append(n)}return t}}class i{constructor(e){this.originalNode=e;this.realParentNode=e.parentNode;this.previousSibling=e.previousSibling;this.nextSibling=e.nextSibling}get childNodes(){const e=[];let t=this.previousSibling?this.previousSibling.nextSibling:this.realParentNode.firstChild;while(t&&t!=this.nextSibling){e.push(t);t=t.nextSibling}return e}querySelectorAll(r){return this.childNodes.reduce((t,e)=>{if(e instanceof Element){if(e.matches(r))t.push(e);const n=e.querySelectorAll(r);for(let e=0;e<n.length;e++){t.push(n[e])}}return t},[])}insertBefore(e,t){return this.realParentNode.insertBefore(e,t)}moveBefore(e,t){return this.realParentNode.moveBefore(e,t)}get __idiomorphRoot(){return this.originalNode}}function l(n){let r=new DOMParser;let e=n.replace(/<svg(\s[^>]*>|>)([\s\S]*?)<\/svg>/gim,"");if(e.match(/<\/html>/)||e.match(/<\/head>/)||e.match(/<\/body>/)){let t=r.parseFromString(n,"text/html");if(e.match(/<\/html>/)){o.add(t);return t}else{let e=t.firstChild;if(e){o.add(e)}return e}}else{let e=r.parseFromString("<body><template>"+n+"</template></body>","text/html");let t=e.body.querySelector("template").content;o.add(t);return t}}return{normalizeElement:e,normalizeParent:r}}();return{morph:t,defaults:n}}();
+export { Idiomorph };

data/lib/monk/live/client/monk_live.js

@@ -0,0 +1,204 @@
+// Monk::Live client runtime: subscribes to the topics a page declares with
+// data-live-topic, applies the HTML patches the server pushes (morphing, so
+// focus and typed text survive), and re-syncs by refetching the page when it
+// may have missed something (ADR 0007, 0011). No JS API: it reports what it
+// does through `monk-live:*` DOM events on `document`.
+//
+//   <meta name="monk-live-url" content="ws://localhost:9293">
+//   <script type="module" src="/js/monk_live.js"></script>
+//
+// The decision logic lives in protocol.js, tested under plain Node.
+
+import { Idiomorph } from "./idiomorph.js";
+import {
+  INITIAL_DELAY, nextDelay, topicsFrom, diffTopics, subscribeMessage, unsubscribeMessage, parseMessage, checkSeq, resyncVerdict,
+} from "./protocol.js";
+
+const emit = (name, detail = {}) => document.dispatchEvent(new CustomEvent(`monk-live:${name}`, { detail }));
+
+// Focus and typed text: idiomorph keeps the focused element (and, with
+// ignoreActiveValue, its value/selection). On top of that:
+//  - [data-live-ignore] subtrees are left exactly as the client has them;
+//  - <details open> is client state the server never sends, so a patch
+//    doesn't close what the user opened.
+const morphOptions = (morphStyle) => ({
+  morphStyle,
+  ignoreActiveValue: true,
+  callbacks: {
+    beforeNodeMorphed: (from) => !(from.nodeType === 1 && from.hasAttribute("data-live-ignore")),
+    beforeAttributeUpdated: (name, node) => !(node.tagName === "DETAILS" && name === "open"),
+  },
+});
+
+const currentTopics = () =>
+  topicsFrom([...document.querySelectorAll("[data-live-topic]")].map((el) => el.getAttribute("data-live-topic")));
+
+let url;
+let socket;
+let delay = INITIAL_DELAY;
+let lastSeq = 0;
+let subscribed = [];
+let everConnected = false;
+let needsResync = false;
+let resyncing = false;
+let resyncAgain = false;
+let resyncRetryDelay = INITIAL_DELAY;
+let resyncRetryTimer = null;
+let stopped = false;
+
+function applyOp({ target, mode, html }) {
+  let nodes;
+  try {
+    nodes = [...document.querySelectorAll(target)];
+  } catch {
+    console.warn(`monk-live: invalid selector ${JSON.stringify(target)}`);
+    return;
+  }
+  const live = nodes.filter((node) => !node.closest("[data-live-ignore]"));
+
+  for (const node of live) {
+    switch (mode) {
+      case "morph": Idiomorph.morph(node, html, morphOptions("outerHTML")); break;
+      case "replace": node.outerHTML = html; break;
+      case "append": node.insertAdjacentHTML("beforeend", html); break;
+      case "prepend": node.insertAdjacentHTML("afterbegin", html); break;
+      case "remove": node.remove(); break;
+    }
+  }
+  emit("patched", { target, mode, matched: live.length });
+}
+
+function onMessage(event) {
+  const message = parseMessage(event.data);
+
+  switch (message.kind) {
+    case "envelope": {
+      const verdict = checkSeq(lastSeq, message.seq);
+      lastSeq = message.seq;
+      message.ops.forEach(applyOp);
+      if (verdict === "gap") {
+        emit("gap", { seq: message.seq });
+        resync();
+      }
+      break;
+    }
+    case "subscribed":
+      subscribed = [...new Set([...subscribed, ...message.topics])].sort();
+      if (message.denied.length) console.warn("monk-live: subscription denied for", message.denied);
+      emit("subscribed", { topics: message.topics, denied: message.denied });
+      if (needsResync) resync();
+      break;
+    case "unsubscribed":
+      subscribed = subscribed.filter((topic) => !message.topics.includes(topic));
+      break;
+    case "error":
+      console.warn("monk-live: server error", message.reason);
+      break;
+    default:
+      break;
+  }
+}
+
+function stop(reason) {
+  stopped = true;
+  needsResync = false;
+  clearTimeout(resyncRetryTimer);
+  socket?.close();
+  emit("stopped", { reason });
+}
+
+// The page's own view is the only definition of what a region looks like
+// (ADR 0011): refetch it and morph it in. If what comes back isn't the app
+// page (an error, a redirect to a login screen), stop instead of morphing.
+async function resync() {
+  if (resyncing) {
+    resyncAgain = true;
+    return;
+  }
+  resyncing = true;
+  try {
+    const response = await fetch(location.href, {
+      credentials: "same-origin", cache: "no-store", headers: { Accept: "text/html" },
+    });
+    const verdict = resyncVerdict({
+      ok: response.ok, redirected: response.redirected, status: response.status,
+      contentType: response.headers.get("content-type"),
+    });
+    if (verdict) {
+      stop(verdict);
+      return;
+    }
+    const page = new DOMParser().parseFromString(await response.text(), "text/html");
+    Idiomorph.morph(document.body, page.body, morphOptions("innerHTML"));
+    needsResync = false;
+    resyncRetryDelay = INITIAL_DELAY;
+    reconcileTopics();
+    emit("resynced");
+  } catch (error) {
+    needsResync = true;
+    console.warn("monk-live: resync failed", error);
+    emit("resync-failed");
+    scheduleResyncRetry();
+  } finally {
+    resyncing = false;
+    if (resyncAgain && !stopped) {
+      resyncAgain = false;
+      resync();
+    }
+  }
+}
+
+// A failed refetch (network down, server restarting) is retried with the same
+// backoff as reconnects, not only on the next reconnect or gap.
+function scheduleResyncRetry() {
+  if (resyncRetryTimer || stopped) return;
+  resyncRetryTimer = setTimeout(() => {
+    resyncRetryTimer = null;
+    if (needsResync && !stopped) resync();
+  }, resyncRetryDelay);
+  resyncRetryDelay = nextDelay(resyncRetryDelay);
+}
+
+// A resync can bring new (or drop old) data-live-topic regions.
+function reconcileTopics() {
+  if (socket?.readyState !== WebSocket.OPEN) return;
+  const { add, remove } = diffTopics(subscribed, currentTopics());
+  if (add.length) socket.send(subscribeMessage(add));
+  if (remove.length) socket.send(unsubscribeMessage(remove));
+}
+
+function connect() {
+  socket = new WebSocket(url);
+  socket.onopen = () => {
+    delay = INITIAL_DELAY;
+    lastSeq = 0;
+    subscribed = [];
+    // Patches may have been missed while we were away: resync once the
+    // server has acknowledged our subscriptions (not before, or a patch
+    // published between the fetch and the subscribe would be lost).
+    needsResync = everConnected;
+    everConnected = true;
+    socket.send(subscribeMessage(currentTopics()));
+    emit("connected");
+  };
+  socket.onmessage = onMessage;
+  socket.onclose = () => {
+    emit("disconnected");
+    if (stopped) return;
+    setTimeout(connect, delay);
+    delay = nextDelay(delay);
+  };
+}
+
+function start() {
+  url = document.querySelector('meta[name="monk-live-url"]')?.content;
+  if (!url) {
+    console.error('monk-live: add <meta name="monk-live-url" content="ws://..."> to the page');
+    return;
+  }
+  if (currentTopics().length === 0) return;
+  connect();
+}
+
+if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", start);
+else start();

data/lib/monk/live/client/protocol.js

@@ -0,0 +1,87 @@
+// Pure logic for the Monk::Live client: no DOM, no WebSocket, no globals, so
+// it runs under plain `node --test` (test/js/protocol.test.js). The browser
+// glue that uses it is monk_live.js.
+
+export const INITIAL_DELAY = 500;
+export const MAX_DELAY = 30000;
+
+// Reconnect backoff: double, capped.
+export const nextDelay = (delay) => Math.min(delay * 2, MAX_DELAY);
+
+const MODES = ["morph", "replace", "append", "prepend", "remove"];
+
+// data-live-topic values ("a:1 b:2") -> a sorted, de-duplicated topic list.
+export function topicsFrom(values) {
+  const topics = new Set();
+  for (const value of values) {
+    for (const topic of String(value ?? "").split(/\s+/)) if (topic) topics.add(topic);
+  }
+  return [...topics].sort();
+}
+
+export function diffTopics(current, wanted) {
+  return {
+    add: wanted.filter((topic) => !current.includes(topic)),
+    remove: current.filter((topic) => !wanted.includes(topic)),
+  };
+}
+
+export const subscribeMessage = (topics) => JSON.stringify({ op: "subscribe", topics });
+export const unsubscribeMessage = (topics) => JSON.stringify({ op: "unsubscribe", topics });
+
+const isString = (value) => typeof value === "string";
+
+function validOp(op) {
+  if (op === null || typeof op !== "object" || op.op !== "patch") return false;
+  if (!isString(op.target) || op.target.trim() === "" || !MODES.includes(op.mode)) return false;
+  return op.mode === "remove" ? true : isString(op.html);
+}
+
+const toOp = ({ target, mode, html }) => ({ target, mode, html });
+
+// One server frame -> { kind: "envelope" | "subscribed" | "unsubscribed" |
+// "error" | "unknown" | "invalid", ... }. Never throws: a frame the client
+// can't understand must not take the connection down.
+export function parseMessage(text) {
+  let message;
+  try {
+    message = JSON.parse(text);
+  } catch {
+    return { kind: "invalid" };
+  }
+  if (message === null || typeof message !== "object" || Array.isArray(message)) return { kind: "invalid" };
+
+  switch (message.op) {
+    case "patch":
+      if (!Number.isInteger(message.seq) || !validOp(message)) return { kind: "invalid" };
+      return { kind: "envelope", seq: message.seq, ops: [toOp(message)] };
+    case "batch":
+      if (!Number.isInteger(message.seq) || !Array.isArray(message.ops) || message.ops.length === 0) {
+        return { kind: "invalid" };
+      }
+      if (!message.ops.every(validOp)) return { kind: "invalid" };
+      return { kind: "envelope", seq: message.seq, ops: message.ops.map(toOp) };
+    case "subscribed":
+      return { kind: "subscribed", topics: message.topics ?? [], denied: message.denied ?? [] };
+    case "unsubscribed":
+      return { kind: "unsubscribed", topics: message.topics ?? [] };
+    case "error":
+      return { kind: "error", reason: message.reason };
+    default:
+      return { kind: "unknown", op: message.op };
+  }
+}
+
+// seq is per connection and starts at 1, so anything but last + 1 means a
+// frame was missed, duplicated or reordered: resync.
+export const checkSeq = (last, seq) => (seq === last + 1 ? "ok" : "gap");
+
+// Whether a refetched page may be morphed in. null means yes; anything else
+// is the reason to stop instead. A redirect is checked first: a redirect to a
+// login screen usually answers 200 HTML, which would otherwise pass.
+export function resyncVerdict({ ok, redirected, status, contentType }) {
+  if (redirected) return "redirected";
+  if (!ok) return `status_${status}`;
+  if (!String(contentType ?? "").includes("text/html")) return "not_html";
+  return null;
+}

data/lib/monk/live/envelope.rb

@@ -0,0 +1,51 @@
+require "json"
+
+module Monk
+  module Live
+    # The server -> client wire shape (docs/history/plan-live.md "Wire protocol"): a
+    # `patch` (one DOM operation: a CSS target, a mode, some html) or a
+    # `batch` of them. Built as frozen Hashes and encoded to one frozen JSON
+    # String, so a publisher can hand the same object to every subscriber
+    # (ADR 0010). No `seq` here: it is per connection, so it can only be
+    # stamped at the edge, where the connection writes the frame.
+    module Envelope
+      MODES = %i[morph replace append prepend remove].freeze
+
+      def self.patch(target:, mode:, html: nil)
+        check_target!(target)
+        check_mode!(mode)
+        if mode == :remove
+          raise ArgumentError, "a remove patch carries no html" if html
+        elsif html.nil?
+          raise ArgumentError, "a #{mode} patch needs html"
+        end
+
+        envelope = { "op" => "patch", "target" => target, "mode" => mode.to_s }
+        envelope["html"] = html if html
+        envelope.freeze
+      end
+
+      def self.batch(ops)
+        raise ArgumentError, "a batch needs at least one op" if ops.empty?
+
+        { "op" => "batch", "ops" => ops.dup.freeze }.freeze
+      end
+
+      def self.encode(envelope)
+        JSON.generate(envelope).freeze
+      end
+
+      def self.check_mode!(mode)
+        return if MODES.include?(mode)
+
+        raise ArgumentError, "unknown mode #{mode.inspect} (known: #{MODES.inspect})"
+      end
+
+      def self.check_target!(target)
+        return if target.is_a?(String) && !target.strip.empty?
+
+        raise ArgumentError, "target must be a non-blank CSS selector String, got #{target.inspect}"
+      end
+    end
+  end
+end

data/lib/monk/live/errors.rb

@@ -0,0 +1,9 @@
+module Monk
+  module Live
+    class NotFrozenError < StandardError
+    end
+
+    class NotConfiguredError < StandardError
+    end
+  end
+end

data/lib/monk/live/helpers.rb

@@ -0,0 +1,22 @@
+module Monk
+  module Live
+    # View helpers, mixed into Monk::Context when "monk/live" is required
+    # (before Boot, like any other Context method).
+    module Helpers
+      # The attribute the client runtime subscribes from:
+      #   <ul id="contacts" <%= live_topic "contacts:#{current_user.id}" %>>
+      # Refuses, at render time, a topic the server would refuse at
+      # subscribe time (Session::TOPIC_FORMAT), so the mistake shows up in
+      # the developer's page instead of as a silent denial in production.
+      def live_topic(*topics)
+        raise ArgumentError, "live_topic needs at least one topic" if topics.empty?
+
+        names = topics.map(&:to_s)
+        bad = names.grep_v(Session::TOPIC_FORMAT)
+        raise ArgumentError, "invalid live topic(s): #{bad.inspect}" unless bad.empty?
+
+        raw(%(data-live-topic="#{names.join(" ")}"))
+      end
+    end
+  end
+end

data/lib/monk/live/policy.rb

@@ -0,0 +1,58 @@
+module Monk
+  module Live
+    # Who may subscribe to which topic (ADR 0009): deny by default. Rules
+    # are matched in declaration order and the first match decides, like
+    # routes, so a specific rule can sit above a general one. A topic no
+    # rule matches is denied, and so is an anonymous subject (nil) unless
+    # the matching rule says `anonymous: true`: a block like
+    # `topic == "contacts:#{subject}"` would otherwise let a nil subject
+    # in through "contacts:". A block that raises fails closed.
+    module Policy
+      Rule = Data.define(:pattern, :anonymous, :check) do
+        def matches?(topic)
+          if pattern.end_with?("*")
+            topic.start_with?(pattern.chomp("*"))
+          else
+            topic == pattern
+          end
+        end
+      end
+
+      def self.build_rule(pattern, anonymous, block)
+        unless pattern.is_a?(String) && !pattern.strip.empty? && valid_wildcard?(pattern)
+          raise ArgumentError,
+            "pattern must be a topic or a topic prefix ending in a single *, got #{pattern.inspect}"
+        end
+        raise ArgumentError, "authorize needs a block: { |subject, topic| ... }" unless block
+
+        Rule.new(pattern: pattern.dup.freeze, anonymous: anonymous, check: shareable(block))
+      end
+
+      def self.allowed?(rules, subject, topic)
+        rule = rules.find { |candidate| candidate.matches?(topic) }
+        return false unless rule
+        return false if subject.nil? && !rule.anonymous
+
+        rule.check.call(subject, topic) ? true : false
+      rescue StandardError
+        false
+      end
+
+      def self.valid_wildcard?(pattern)
+        pattern.count("*").zero? || (pattern.count("*") == 1 && pattern.end_with?("*"))
+      end
+      private_class_method :valid_wildcard?
+
+      # Same constraint, same message shape, as Server#run's block.
+      def self.shareable(block)
+        Ractor.make_shareable(block)
+      rescue ArgumentError, Ractor::IsolationError => e
+        raise Monk::UnshareableBlockError,
+          "Monk::Live.authorize block is not Ractor-shareable: #{e.message} " \
+          "(build it where self is shareable, e.g. at class-body scope, not inline in a script's " \
+          "top-level block)"
+      end
+      private_class_method :shareable
+    end
+  end
+end

data/lib/monk/live/publisher.rb

@@ -0,0 +1,91 @@
+module Monk
+  module Live
+    # Renders a fragment once, wraps it in an Envelope, and broadcasts the
+    # frozen JSON to every subscriber of a topic (ADR 0010). Wraps anything
+    # with Registry's #broadcast, so a RedisFanout makes it cross-process
+    # without this class knowing (ADR 0008). Frozen, so a module-level
+    # publisher is readable from any Ractor.
+    #
+    # `to:`, `partial:` and `mode:` are reserved keywords; every other
+    # keyword is a local for the partial (read as `locals[:name]`).
+    class Publisher
+      def initialize(registry)
+        @registry = registry
+        freeze
+      end
+
+      def patch(topic, to:, partial:, mode: :morph, **locals)
+        broadcast(topic, Publisher.build_op(to, partial, mode, locals))
+      end
+
+      def append(topic, to:, partial:, **locals)
+        patch(topic, to: to, partial: partial, mode: :append, **locals)
+      end
+
+      def prepend(topic, to:, partial:, **locals)
+        patch(topic, to: to, partial: partial, mode: :prepend, **locals)
+      end
+
+      def remove(topic, to:)
+        broadcast(topic, Publisher.build_op(to, nil, :remove, {}))
+      end
+
+      # Every op renders inside the block, so a failure raises before
+      # anything is sent; an empty batch sends nothing.
+      def batch(topic)
+        builder = Batch.new
+        yield builder
+        return true if builder.ops.empty?
+
+        broadcast(topic, Envelope.batch(builder.ops))
+      end
+
+      # Collects ops for #batch; same vocabulary as the publisher itself.
+      class Batch
+        attr_reader :ops
+
+        def initialize
+          @ops = []
+        end
+
+        def patch(to:, partial:, mode: :morph, **locals)
+          @ops << Publisher.build_op(to, partial, mode, locals)
+        end
+
+        def append(to:, partial:, **locals)
+          patch(to: to, partial: partial, mode: :append, **locals)
+        end
+
+        def prepend(to:, partial:, **locals)
+          patch(to: to, partial: partial, mode: :prepend, **locals)
+        end
+
+        def remove(to:)
+          @ops << Publisher.build_op(to, nil, :remove, {})
+        end
+      end
+
+      # Validates before rendering, so a bad mode or target never costs a
+      # render (or a half-built batch).
+      def self.build_op(target, partial, mode, locals)
+        Envelope.check_target!(target)
+        Envelope.check_mode!(mode)
+        return Envelope.patch(target: target, mode: :remove) if mode == :remove
+
+        Envelope.patch(target: target, mode: mode, html: Renderer.render(partial, **locals))
+      end
+
+      private
+
+      # Topics are Symbols on the Registry (RedisFanout's channel names
+      # come back as Symbols), Strings in app code.
+      def broadcast(topic, envelope)
+        unless topic.is_a?(String) || topic.is_a?(Symbol)
+          raise ArgumentError, "topic must be a String or Symbol, got #{topic.inspect}"
+        end
+
+        @registry.broadcast(topic.to_sym, Envelope.encode(envelope))
+      end
+    end
+  end
+end