rails-markup 1.3.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d852927076b8b5e1774675692c45b575eb9dd6337c934637e90c693310d96f4d
-  data.tar.gz: 3608bdd64056b7cb3373de2cd4ea0797a1e6dc3e021457ec96697a4d3f8c7919
+  metadata.gz: 665bd02a5e8830d8565296c7623f4136513a61a2c1574e68c0c2b6802daf7ea2
+  data.tar.gz: fd6290208722a52ecc255f3d01cdf017de31010157f6c67cc4386423e848eb98
 SHA512:
-  metadata.gz: ac1ee4649e024d9a3fa306bf3fefb9f6443c2d89cec4d33de6b504831123228f1db3cc2e20414914fdec41150e832ea077d76cfe1c606859c2177626eb643251
-  data.tar.gz: e8942c6bcbff10487ab62170039b6c62c0c0ffe87a59cb77ac8df87792c6365109d222451fc8756831fad1284b1336f7d0adff3dbf3698b257e2c0e2b1346899
+  metadata.gz: 32afe3f8d8ea940731cde32f9524738189ca7d54b1bc1d124adc8888adb9fce35347647bc5844ca15dac6c918a546cef2d9ca048e0901e98ebc87f17db34ec4e
+  data.tar.gz: 2c173c2623816601f0cc5ab730960cc035f2523a14adad0de4d130163f358d47562959f8fbd6c4b9e2e2ea9a0442e6d711dc6ba35070d89ae7d23e17c6cb2b15

data/app/assets/javascripts/rails_markup/toolbar.js

@@ -43,6 +43,7 @@
     _syncMaxRetryDelay: 30000,
     _syncMalformedLimit: 3,
     _syncUnavailable: null,
+    legacyStorageEndpoint: null,
 
     // Drawing state
     drawingMode: null,      // null | "arrow" | "rect" | "highlight"
@@ -73,6 +74,7 @@
       this.size = opts.size || "default";
       this.fabVisible = opts.fabVisible !== false;
       this.enableScreenshots = opts.enableScreenshots !== false;
+      this.legacyStorageEndpoint = opts.legacyStorageEndpoint || this.legacyStorageEndpoint;
       this.healthIntervalMs = (opts.healthInterval || 60) * 1000;
 
       if (document.getElementById("rm-toolbar-root")) {
@@ -714,6 +716,7 @@
         id: this.nextId,
         clientId: this._newClientId(),
         serverId: null,
+        serverRevision: 0,
         syncState: "pending",
         serverUpdatedAt: null,
         dirtyFields: [],
@@ -1077,12 +1080,16 @@
     _queueLocalMutation(type, annotation, dirtyFields) {
       const currentEntry = this.outbox[annotation.clientId];
       const revision = Math.max(annotation.revision || 0, currentEntry?.revision || 0) + 1;
+      const baseRevision = Number.isInteger(currentEntry?.baseRevision)
+        ? currentEntry.baseRevision
+        : (Number.isInteger(annotation.serverRevision) ? annotation.serverRevision : 0);
 
       if (type === "delete") {
         this.outbox[annotation.clientId] = {
           type: "delete",
           clientId: annotation.clientId,
           revision,
+          baseRevision,
           syncState: "pending"
         };
       } else {
@@ -1094,6 +1101,7 @@
           type: "upsert",
           clientId: annotation.clientId,
           revision,
+          baseRevision,
           syncState: "pending",
           annotation: this._desiredState(annotation),
           dirtyFields: annotation.dirtyFields.slice()
@@ -1208,6 +1216,16 @@
           this._markSyncFailed(snapshot);
           continue;
         }
+        if (result.kind === "conflict") {
+          const resolution = this._reconcileSyncConflict(snapshot, result);
+          await this._pullAnnotations();
+          if (resolution === "retry" && this.outbox[clientId]) {
+            clientIds.push(clientId);
+            continue;
+          }
+          this._resetSyncRetry();
+          continue;
+        }
         if (result.kind === "malformed") {
           if (!this._outboxEntryMatches(snapshot)) {
             clientIds.push(clientId);
@@ -1235,8 +1253,15 @@
         redirect: "manual",
         signal: AbortSignal.timeout(5000)
       };
-      if (snapshot.type === "upsert") {
-        options.body = JSON.stringify(Object.assign({}, snapshot.annotation, { dirtyFields: snapshot.dirtyFields || [] }));
+      if (snapshot.type === "delete") {
+        options.body = JSON.stringify({
+          baseRevision: Number.isInteger(snapshot.baseRevision) ? snapshot.baseRevision : 0
+        });
+      } else {
+        options.body = JSON.stringify(Object.assign({}, snapshot.annotation, {
+          dirtyFields: snapshot.dirtyFields || [],
+          baseRevision: Number.isInteger(snapshot.baseRevision) ? snapshot.baseRevision : 0
+        }));
       }
 
       const response = await fetch(request.url, options);
@@ -1274,6 +1299,7 @@
       if ([408, 425, 429].includes(status) || status >= 500) {
         return { kind: "retryable", retryAfter: this._retryAfterDelay(response) };
       }
+      if (status === 409) return this._classifyConflictResponse(snapshot, response);
       if (status >= 400) return { kind: "terminal" };
       if (!response.ok) return { kind: "retryable" };
       if (snapshot.type === "delete") return { kind: "success", data: null };
@@ -1292,12 +1318,31 @@
       }
     },
 
+    async _classifyConflictResponse(snapshot, response) {
+      const contentType = response.headers.get("Content-Type") || "";
+      if (!contentType.toLowerCase().includes("application/json")) return { kind: "malformed" };
+
+      try {
+        const body = await response.json();
+        if (!this._plainObject(body) || !Object.prototype.hasOwnProperty.call(body, "annotation")) {
+          return { kind: "malformed" };
+        }
+        if (body.annotation === null && snapshot.type === "upsert") {
+          return { kind: "conflict", missing: true, data: null };
+        }
+        if (!this._validServerAnnotation(body.annotation, snapshot.clientId)) return { kind: "malformed" };
+        return { kind: "conflict", missing: false, data: body.annotation };
+      } catch {
+        return { kind: "malformed" };
+      }
+    },
+
     _validServerAnnotation(data, expectedClientId) {
       if (!this._plainObject(data)) return false;
       const required = [
         "id", "clientId", "userId", "authorName", "content", "intent", "severity",
         "status", "selectedText", "pageUrl", "target", "metadata", "thread",
-        "createdAt", "updatedAt"
+        "createdAt", "updatedAt", "revision"
       ];
       if (!required.every(key => Object.prototype.hasOwnProperty.call(data, key))) return false;
       if (typeof data.id !== "string" || data.id.length === 0) return false;
@@ -1313,6 +1358,7 @@
       if (!this._plainObject(data.target) || !this._plainObject(data.metadata)) return false;
       if (!Array.isArray(data.thread)) return false;
       if (!this._validServerTimestamp(data.createdAt) || !this._validServerTimestamp(data.updatedAt)) return false;
+      if (!Number.isInteger(data.revision) || data.revision < 0) return false;
       return true;
     },
 
@@ -1346,6 +1392,7 @@
         return;
       }
       annotation.serverId = server.id;
+      annotation.serverRevision = server.revision;
       annotation.userId = server.userId;
       annotation.authorName = server.authorName;
       annotation.createdAt = server.createdAt;
@@ -1364,6 +1411,57 @@
       annotation.syncState = "synced";
     },
 
+    _reconcileSyncConflict(snapshot, conflict) {
+      if (!this._outboxEntryMatches(snapshot)) return "stop";
+
+      let resolution = "stop";
+      const committed = this._commitLocalStateChange(() => {
+        if (!this._outboxEntryMatches(snapshot)) return;
+        const entry = this.outbox[snapshot.clientId];
+        const annotation = this.annotations.find(candidate => candidate.clientId === snapshot.clientId);
+
+        if (snapshot.type === "delete") {
+          delete this.outbox[snapshot.clientId];
+          if (annotation) this._mergePulledAnnotation(annotation, conflict.data, null);
+          else this.annotations.push(this._annotationFromServer(conflict.data));
+          this._assignDisplayIds();
+          return;
+        }
+
+        if (conflict.missing) {
+          if (entry.missingConflictRebased) {
+            entry.syncState = "failed";
+            if (annotation) annotation.syncState = "failed";
+            return;
+          }
+          entry.baseRevision = 0;
+          entry.missingConflictRebased = true;
+          if (annotation) {
+            annotation.serverId = null;
+            annotation.serverRevision = 0;
+          }
+          resolution = "retry";
+          return;
+        }
+
+        if (!annotation) {
+          entry.syncState = "failed";
+          return;
+        }
+        this._mergePulledAnnotation(annotation, conflict.data, entry);
+        entry.annotation = this._desiredState(annotation);
+        entry.dirtyFields = (annotation.dirtyFields || []).slice();
+        entry.baseRevision = conflict.data.revision;
+        delete entry.missingConflictRebased;
+        resolution = "retry";
+      });
+      if (!committed) return "stop";
+      this._renderPins();
+      this._rebuildList();
+      this._updateCount();
+      return resolution;
+    },
+
     _markSyncFailed(snapshot) {
       if (!this._outboxEntryMatches(snapshot)) return;
       this._commitLocalStateChange(() => {
@@ -1447,8 +1545,6 @@
 
     _loadFromStorage() {
       try {
-        // Old unnamespaced keys are intentionally not read because they may belong
-        // to another user or toolbar mount on the same origin.
         let raw = localStorage.getItem(this._storageKey());
         if (raw) {
           const data = JSON.parse(raw);
@@ -1460,8 +1556,11 @@
             ? data.legacyMigrations
             : {};
         }
-        // Migrate any old per-page annotations into global store
-        const migratedKeys = this._migratePageAnnotations();
+        // Pre-1.3 bare storage has no endpoint provenance, so it is left intact
+        // unless the host explicitly designates this endpoint. Page-qualified
+        // legacy keys are only claimed by a toolbar currently on that exact page.
+        const migratedKeys = this._migrateUnnamespacedStorage();
+        migratedKeys.push(...this._migratePageAnnotations());
         this._normalizeStoredState();
         this._recordLegacyMigrations();
         if (this._saveToStorage()) this._cleanupMigratedKeys(migratedKeys);
@@ -1470,6 +1569,58 @@
       } catch (e) { console.warn("[rails-markup] load failed:", e); }
     },
 
+    _migrateUnnamespacedStorage() {
+      const sourceKeys = [];
+      const designatedEndpoint = (this.legacyStorageEndpoint || "").replace(/\/+$/, "");
+      const currentEndpoint = (this.endpoint || "").replace(/\/+$/, "");
+      const claimBareStorage = Boolean(designatedEndpoint) && designatedEndpoint === currentEndpoint;
+      const currentPageKey = `rm-annotations:${this._pageUrl()}`;
+      for (let index = 0; index < localStorage.length; index++) {
+        const key = localStorage.key(index);
+        if ((claimBareStorage && key === "rm-annotations") || key === currentPageKey) sourceKeys.push(key);
+      }
+
+      const migratedKeys = [];
+      const legacyAnnotations = [];
+      const legacyOutbox = {};
+      const consolidatedClientIds = new Set(
+        this.annotations.map(annotation => annotation.clientId).filter(clientId => this._validClientId(clientId))
+      );
+      sourceKeys.forEach(key => {
+        try {
+          const data = JSON.parse(localStorage.getItem(key));
+          if (!this._plainObject(data)) return;
+          const hasAnnotations = Array.isArray(data.annotations);
+          const hasOutbox = key === "rm-annotations" && this._plainObject(data.outbox);
+          if (!hasAnnotations && !hasOutbox) return;
+
+          if (hasAnnotations) {
+            data.annotations.forEach((annotation, index) => {
+              if (!this._plainObject(annotation)) return;
+              const fingerprint = this._legacyMigrationFingerprint(key, index, annotation);
+              const migratedClientId = this.legacyMigrations[fingerprint];
+              if (this._validClientId(migratedClientId) && consolidatedClientIds.has(migratedClientId)) return;
+              if (this._validClientId(migratedClientId)) annotation.clientId = migratedClientId;
+              if (this._validClientId(annotation.clientId) && consolidatedClientIds.has(annotation.clientId)) return;
+              Object.defineProperty(annotation, "_legacyMigrationFingerprint", {
+                configurable: true,
+                value: fingerprint
+              });
+              legacyAnnotations.push(annotation);
+              if (this._validClientId(annotation.clientId)) consolidatedClientIds.add(annotation.clientId);
+            });
+          }
+          if (hasOutbox) Object.assign(legacyOutbox, data.outbox);
+          if (Number.isInteger(data.nextId) && data.nextId > this.nextId) this.nextId = data.nextId;
+          migratedKeys.push(key);
+        } catch {}
+      });
+
+      this.annotations = legacyAnnotations.concat(this.annotations);
+      this.outbox = Object.assign({}, legacyOutbox, this.outbox);
+      return migratedKeys;
+    },
+
     _migratePageAnnotations() {
       // Find and merge per-page annotation keys only within this endpoint namespace.
       const prefix = this._storageKey() + ":";
@@ -1542,6 +1693,11 @@
         }
         if (annotation.serverId == null) annotation.serverId = annotation.server_id ?? null;
         if (annotation.serverUpdatedAt == null) annotation.serverUpdatedAt = annotation.server_updated_at ?? null;
+        if (!Number.isInteger(annotation.serverRevision) || annotation.serverRevision < 0) {
+          annotation.serverRevision = Number.isInteger(annotation.server_revision) && annotation.server_revision >= 0
+            ? annotation.server_revision
+            : 0;
+        }
         if (!Array.isArray(annotation.dirtyFields)) annotation.dirtyFields = [];
         annotation.pageUrl = annotation.pageUrl || annotation.pathname || this._pageUrl();
         annotation.pathname = annotation.pageUrl;
@@ -1576,6 +1732,7 @@
             type: "upsert",
             clientId: annotation.clientId,
             revision: annotation.revision,
+            baseRevision: annotation.serverRevision,
             syncState: "pending",
             annotation: this._desiredState(annotation),
             dirtyFields: annotation.dirtyFields.slice()
@@ -1606,10 +1763,17 @@
         const annotation = this.annotations.find(record => record.clientId === clientId);
         const candidateRevision = Number.isInteger(candidate.revision) && candidate.revision >= 0 ? candidate.revision : 0;
         const annotationRevision = Number.isInteger(annotation?.revision) && annotation.revision >= 0 ? annotation.revision : 0;
+        const candidateBaseRevision = Number.isInteger(candidate.baseRevision) && candidate.baseRevision >= 0
+          ? candidate.baseRevision
+          : 0;
+        const annotationBaseRevision = Number.isInteger(annotation?.serverRevision) && annotation.serverRevision >= 0
+          ? annotation.serverRevision
+          : 0;
         const envelope = Object.assign({}, candidate, {
           type,
           clientId,
           revision: Math.max(candidateRevision, annotationRevision),
+          baseRevision: Math.max(candidateBaseRevision, annotationBaseRevision),
           syncState: candidate.syncState === "failed" ? "failed" : "pending"
         });
 
@@ -1823,6 +1987,7 @@
           if (!annotation) return;
           entry.annotation = this._desiredState(annotation);
           entry.dirtyFields = (annotation.dirtyFields || []).slice();
+          entry.baseRevision = Number.isInteger(annotation.serverRevision) ? annotation.serverRevision : 0;
         });
       });
       if (!committed) return false;
@@ -1856,6 +2021,7 @@
         annotation.pathname = server.pageUrl;
       }
       annotation.serverId = server.id;
+      annotation.serverRevision = server.revision;
       annotation.userId = server.userId;
       annotation.authorName = server.authorName;
       annotation.createdAt = server.createdAt;
@@ -1871,6 +2037,7 @@
         id: null,
         clientId: server.clientId,
         serverId: server.id,
+        serverRevision: server.revision,
         userId: server.userId,
         authorName: server.authorName,
         syncState: "synced",
@@ -1893,6 +2060,9 @@
     },
 
     _serverRepresentationIsStale(annotation, server) {
+      if (Number.isInteger(annotation.serverRevision) && Number.isInteger(server.revision)) {
+        return server.revision < annotation.serverRevision;
+      }
       const localTimestamp = Date.parse(annotation.serverUpdatedAt || "");
       const serverTimestamp = Date.parse(server.updatedAt || "");
       return Number.isFinite(localTimestamp) && Number.isFinite(serverTimestamp) && serverTimestamp < localTimestamp;

data/app/controllers/rails_markup/annotations_controller.rb

@@ -59,31 +59,50 @@ module RailsMarkup
 
       dirty_fields = normalized_dirty_fields
       return render_invalid_dirty_fields unless dirty_fields
+      base_revision = normalized_base_revision
+      return render_invalid_base_revision unless base_revision
 
       attributes = browser_attributes
       return render_invalid_status if dirty_fields.include?("status") && !Annotation::STATUSES.include?(attributes["status"])
 
       annotation = Annotation.find_or_initialize_by(client_uuid: client_uuid)
       created = annotation.new_record?
-      apply_desired_state(annotation, attributes, dirty_fields)
-      annotation.save!
+      save_browser_state!(annotation, attributes, dirty_fields, base_revision)
       fire_create_callback(annotation) if created
       render json: annotation.as_api_json
+    rescue Annotation::RevisionConflict => error
+      render_revision_conflict(error)
     rescue ActiveRecord::RecordInvalid => error
       render json: { errors: error.record.errors.full_messages }, status: :unprocessable_entity
     rescue ActiveRecord::RecordNotUnique
       annotation = Annotation.find_by!(client_uuid: client_uuid)
-      apply_desired_state(annotation, attributes, dirty_fields)
-      annotation.save!
-      render json: annotation.as_api_json
+      begin
+        save_browser_state!(annotation, attributes, dirty_fields, base_revision)
+        render json: annotation.as_api_json
+      rescue Annotation::RevisionConflict => error
+        render_revision_conflict(error)
+      end
     end
 
     # DELETE /feedback/api/annotations/:client_uuid
     def destroy
       client_uuid = normalized_route_uuid
       return render_invalid_uuid unless client_uuid
+      base_revision = normalized_base_revision
+      return render_invalid_base_revision unless base_revision
+
+      annotation = Annotation.find_by(client_uuid: client_uuid)
+      return head :no_content unless annotation
+
+      annotation.with_lock do
+        raise Annotation::RevisionConflict, annotation unless annotation.revision == base_revision
 
-      Annotation.find_by(client_uuid: client_uuid)&.destroy!
+        annotation.destroy!
+      end
+      head :no_content
+    rescue Annotation::RevisionConflict => error
+      render_revision_conflict(error)
+    rescue ActiveRecord::RecordNotFound
       head :no_content
     end
 
@@ -183,9 +202,25 @@ module RailsMarkup
       permitted.to_h.stringify_keys
     end
 
-    def apply_desired_state(annotation, attributes, dirty_fields)
-      assign_current_user(annotation) if annotation.new_record?
-      annotation.apply_browser_state(attributes, dirty_fields: dirty_fields)
+    def save_browser_state!(annotation, attributes, dirty_fields, base_revision)
+      if annotation.new_record?
+        assign_current_user(annotation)
+        annotation.apply_browser_state(
+          attributes,
+          dirty_fields: dirty_fields,
+          base_revision: base_revision
+        )
+        annotation.save!
+      else
+        annotation.with_lock do
+          annotation.apply_browser_state(
+            attributes,
+            dirty_fields: dirty_fields,
+            base_revision: base_revision
+          )
+          annotation.save!
+        end
+      end
     end
 
     def normalized_route_uuid
@@ -201,6 +236,11 @@ module RailsMarkup
       fields if (fields - ALLOWED_DIRTY_FIELDS).empty?
     end
 
+    def normalized_base_revision
+      revision = params[:baseRevision]
+      revision if revision.is_a?(Integer) && revision >= 0
+    end
+
     def client_supplied_author?
       metadata = params[:metadata]
       metadata.respond_to?(:key?) && (metadata.key?(:author) || metadata.key?("author"))
@@ -226,6 +266,17 @@ module RailsMarkup
       render json: { error: "invalid status" }, status: :unprocessable_entity
     end
 
+    def render_invalid_base_revision
+      render json: { error: "base revision must be a non-negative integer" }, status: :unprocessable_entity
+    end
+
+    def render_revision_conflict(error)
+      render json: {
+        error: "revision conflict",
+        annotation: error.annotation.new_record? ? nil : error.annotation.as_api_json
+      }, status: :conflict
+    end
+
     def normalize_target(target)
       case target
       when String then { "selector" => target }

data/app/controllers/rails_markup/dashboard_controller.rb

@@ -106,7 +106,10 @@ module RailsMarkup
         return redirect_to root_path, alert: "Invalid status for bulk dismiss."
       end
 
-      count = Annotation.where(status: status).update_all(status: "dismissed")
+      # Bump revision per row so a stale toolbar edit (which checks baseRevision)
+      # conflicts (409) instead of silently overwriting this bulk dismiss.
+      count = Annotation.where(status: status)
+        .update_all("status = 'dismissed', revision = revision + 1")
       redirect_to root_path(status: "dismissed"), notice: "#{count} annotations dismissed."
     end
 
@@ -122,7 +125,11 @@ module RailsMarkup
       when "transition"
         new_status = params[:status]
         if Annotation::STATUSES.include?(new_status)
-          @annotation.update!(status: new_status)
+          # Lock + bump revision so a concurrent toolbar edit conflicts (409)
+          # instead of this board move silently losing to (or clobbering) it.
+          @annotation.with_lock do
+            @annotation.update!(status: new_status, revision: @annotation.revision + 1)
+          end
           return head :ok
         else
           return render json: { error: "invalid status" }, status: :unprocessable_entity

data/app/controllers/rails_markup/external/annotations_controller.rb

@@ -61,7 +61,10 @@ module RailsMarkup
         return if Rails.env.development? && !RailsMarkup.config.require_api_token_in_development
 
         token = RailsMarkup.config.api_token
-        return head(:not_found) if token.nil?
+        # Treat a nil OR blank token as "external API disabled" — otherwise a
+        # token of "" would make secure_compare("", "") true and authenticate
+        # every request (including ones with no Authorization header).
+        return head(:not_found) if token.nil? || token.to_s.strip.empty?
 
         provided = request.headers["Authorization"]&.delete_prefix("Bearer ")
         head(:unauthorized) unless ActiveSupport::SecurityUtils.secure_compare(provided.to_s, token)

data/app/models/rails_markup/annotation.rb

@@ -5,6 +5,15 @@ require "digest/sha1"
 
 module RailsMarkup
   class Annotation < ActiveRecord::Base
+    class RevisionConflict < StandardError
+      attr_reader :annotation
+
+      def initialize(annotation)
+        @annotation = annotation
+        super("annotation revision conflict")
+      end
+    end
+
     self.table_name = RailsMarkup.config.table_name
 
     INTENTS = %w[fix change question approve].freeze
@@ -17,6 +26,10 @@ module RailsMarkup
     LEGACY_SESSION_PATTERN = /\Arm-[0-9a-f]{16}\z/i
     LEGACY_CLIENT_ID_LIMIT = 256
     LEGACY_UUID_NAMESPACE = "265e7cf0-8be6-5e21-8f31-a582cfde8646"
+    # Bound thread growth so large or many reply/summary/reason messages (incl.
+    # via the MCP tools) can't grow a row without limit.
+    MAX_THREAD_ENTRIES = 500
+    MAX_THREAD_MESSAGE = 5000
 
     # Optional user association — no FK constraint, engine doesn't know host users table
     belongs_to :user, optional: true
@@ -36,6 +49,7 @@ module RailsMarkup
     validates :severity, inclusion: { in: SEVERITIES }
     validates :status, inclusion: { in: STATUSES }
     validate :thread_must_be_array
+    validate :thread_within_limits
 
     def self.valid_client_uuid?(value)
       value.is_a?(String) && CLIENT_UUID_PATTERN.match?(value)
@@ -99,18 +113,33 @@ module RailsMarkup
       metadata&.dig("author")
     end
 
-    def apply_browser_state(attributes, dirty_fields: [])
-      assign_attributes(attributes.slice(*BROWSER_ATTRIBUTES))
-      self.metadata = (metadata || {}).merge(attributes.fetch("metadata", {}).slice(*BROWSER_METADATA_KEYS))
-      self.status = attributes["status"] if dirty_fields.include?("status")
+    def apply_browser_state(attributes, dirty_fields:, base_revision:)
+      raise RevisionConflict, self unless base_revision == revision
+
+      dirty_fields.each do |field|
+        if BROWSER_ATTRIBUTES.include?(field)
+          public_send("#{field}=", attributes[field]) if attributes.key?(field)
+        elsif field == "metadata" && attributes.key?("metadata")
+          self.metadata = (metadata || {}).merge(attributes["metadata"].slice(*BROWSER_METADATA_KEYS))
+        elsif field == "status" && attributes.key?("status")
+          self.status = attributes["status"]
+        end
+      end
+      self.revision += 1 if changed?
       self
     end
 
     def acknowledge!
-      return self if status == "acknowledged" # idempotent — re-acknowledging is a no-op
-      raise "Cannot acknowledge a #{status} annotation" unless status == "pending"
+      # Lock + reload so a concurrent resolve!/dismiss! can't be clobbered:
+      # without it, an acknowledge validated against a stale "pending" could
+      # write "acknowledged" over an already-resolved record.
+      with_lock do
+        return self if status == "acknowledged" # idempotent — re-acknowledging is a no-op
+        raise "Cannot acknowledge a #{status} annotation" unless status == "pending"
 
-      update!(status: "acknowledged")
+        update!(status: "acknowledged", revision: revision + 1)
+      end
+      self
     end
 
     def resolve!(summary: nil)
@@ -121,7 +150,7 @@ module RailsMarkup
         raise "Cannot resolve a #{status} annotation" unless status.in?(%w[pending acknowledged])
 
         add_thread_entry(role: "agent", message: summary) if summary.present?
-        update!(status: "resolved")
+        update!(status: "resolved", revision: revision + 1)
       end
       self
     end
@@ -132,7 +161,7 @@ module RailsMarkup
         raise "Cannot dismiss a #{status} annotation" unless status.in?(%w[pending acknowledged])
 
         add_thread_entry(role: "agent", message: reason) if reason.present?
-        update!(status: "dismissed")
+        update!(status: "dismissed", revision: revision + 1)
       end
       self
     end
@@ -140,6 +169,7 @@ module RailsMarkup
     def add_reply!(message:, role: "agent")
       with_lock do
         add_thread_entry(role: role, message: message)
+        self.revision += 1
         save!
       end
       self
@@ -161,7 +191,8 @@ module RailsMarkup
         metadata: metadata,
         thread: thread,
         createdAt: created_at&.iso8601,
-        updatedAt: updated_at&.iso8601
+        updatedAt: updated_at&.iso8601,
+        revision: revision
       }
     end
 
@@ -182,5 +213,15 @@ module RailsMarkup
     def thread_must_be_array
       errors.add(:thread, "must be an array") unless thread.is_a?(Array)
     end
+
+    def thread_within_limits
+      return unless thread.is_a?(Array)
+
+      errors.add(:thread, "cannot exceed #{MAX_THREAD_ENTRIES} entries") if thread.size > MAX_THREAD_ENTRIES
+
+      if thread.any? { |entry| entry.is_a?(Hash) && entry["message"].to_s.length > MAX_THREAD_MESSAGE }
+        errors.add(:thread, "entry message cannot exceed #{MAX_THREAD_MESSAGE} characters")
+      end
+    end
   end
 end

data/app/views/rails_markup/shared/_toolbar.html.erb

@@ -25,6 +25,14 @@
     };
     // Init immediately (DOM is ready — script is at end of body)
     RailsMarkupToolbar.init(opts);
+    // Tear down before Turbo snapshots the page for its cache — otherwise the
+    // cached DOM keeps a toolbar root with no live listeners, and on restore
+    // init() would early-return on that dead root instead of rebinding.
+    document.addEventListener("turbo:before-cache", function() {
+      if (window.RailsMarkupToolbar && typeof RailsMarkupToolbar.destroy === "function") {
+        RailsMarkupToolbar.destroy();
+      }
+    });
     // After Turbo Drive navigations (DOMContentLoaded won't fire again), only
     // re-init when the new page is still authorized (gate sentinel present);
     // otherwise tear the toolbar down so it can't persist past a logout.

data/db/migrate/20260726000000_add_revision_to_rails_markup_annotations.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class AddRevisionToRailsMarkupAnnotations < ActiveRecord::Migration[7.0]
+  def change
+    table = RailsMarkup.config.table_name
+    return unless table_exists?(table)
+    return if column_exists?(table, :revision)
+
+    add_column table, :revision, :integer, null: false, default: 0
+  end
+end

data/lib/generators/rails_markup/install/templates/create_rails_markup_annotations.rb.erb

@@ -18,6 +18,7 @@ class CreateRailsMarkupAnnotations < ActiveRecord::Migration<%= migration_versio
       t.send json_type, :metadata, default: {}
       t.send json_type, :thread, default: []
       t.string :client_uuid, limit: 64, null: false
+      t.integer :revision, null: false, default: 0
 
       t.timestamps
     end
@@ -28,6 +29,10 @@ class CreateRailsMarkupAnnotations < ActiveRecord::Migration<%= migration_versio
     if connection.adapter_name.downcase.include?("mysql")
       add_index :<%= options[:table_name] %>, :page_url, length: 191
     else
+      # PostgreSQL indexes the full column so `where(page_url:)` lookups stay
+      # fast. A btree entry tops out near 2704 bytes, so a pathological
+      # multibyte URL approaching the 2048-char cap could exceed it; real URLs
+      # are far shorter. Switch to an expression index if that ever bites you.
       add_index :<%= options[:table_name] %>, :page_url
     end
     add_index :<%= options[:table_name] %>, :user_id

data/lib/generators/rails_markup/install_generator.rb

@@ -21,6 +21,20 @@ module RailsMarkup
       class_option :table_name, type: :string, default: "rails_markup_annotations",
         desc: "Database table name for annotations (must match config.table_name)"
 
+      # Conservative SQL identifier: leading letter/underscore, then letters,
+      # digits, underscores. Blocks names that would produce invalid Ruby/SQL or
+      # inject into the migration/initializer templates (e.g. "feedback-items",
+      # quotes, newlines).
+      TABLE_NAME_PATTERN = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
+
+      def validate_table_name
+        return if options[:table_name].match?(TABLE_NAME_PATTERN)
+
+        raise Thor::Error,
+          "Invalid --table-name #{options[:table_name].inspect}: use only letters, " \
+          "digits, and underscores, starting with a letter or underscore."
+      end
+
       def copy_migration
         migration_template "create_rails_markup_annotations.rb.erb",
           "db/migrate/create_rails_markup_annotations.rb"
@@ -76,7 +90,10 @@ module RailsMarkup
           # Upgrade the pre-1.2.3 partial-existence gate, which rendered the
           # toolbar for every visitor, to the admin-gated block. Leave any
           # custom (hand-edited) block untouched so we don't clobber it.
-          legacy = /^[ \t]*<%#\s*Rails Markup annotation toolbar\s*%>\r?\n[ \t]*<%\s*if\s+lookup_context\.exists\?.*?<%\s*end\s*%>\r?\n?/m
+          # Match the exact historical generated block (allowing ERB trim tags)
+          # — including its own render line — so we never swallow a hand-written
+          # block that merely happens to contain lookup_context…end.
+          legacy = /^[ \t]*<%#\s*Rails Markup annotation toolbar\s*%>\r?\n[ \t]*<%-?\s*if\s+lookup_context\.exists\?\("rails_markup\/shared\/toolbar".*?-?%>\r?\n[ \t]*<%=\s*render\s+"rails_markup\/shared\/toolbar"\s*-?%>\r?\n[ \t]*<%-?\s*end\s*-?%>\r?\n?/m
           if content =~ legacy
             gsub_file layout_path, legacy, toolbar_block
             say_status :update, "upgraded toolbar to admin-gated render in #{layout_path}", :green

data/lib/rails_markup/cli.rb

@@ -643,29 +643,30 @@ module RailsMarkup
       "local"
     end
 
-    # Merge configs per-key with local taking precedence over global over codex.
-    # Merging (rather than returning the first non-empty config) means a local
-    # config that only defines dev values doesn't shadow production credentials
-    # stored globally or in the codex config.
-    def resolve_mcp_env
-      merged = {}
-      # Reverse so the highest-precedence scope (local) is applied last and wins.
-      McpConfig::SCOPES.reverse_each do |scope|
+    # Return the raw env of the highest-precedence scope (local → global → codex)
+    # that defines any of the given keys. URL, token, and mount are always read
+    # from this single scope so a token is never paired with a URL from another
+    # scope (credential provenance). A local config that only defines dev values
+    # is skipped for production lookups, so it neither shadows nor captures the
+    # production credentials stored globally/in codex.
+    def scoped_env(*keys)
+      McpConfig::SCOPES.each do |scope|
         config = McpConfig.new(scope: scope)
         next unless config.exist?
 
-        # Skip blank values so an empty key in a higher-precedence config
-        # doesn't clobber a real value from a lower-precedence one.
-        config.raw_env.each do |key, value|
-          merged[key] = value unless value.to_s.strip.empty?
-        end
+        env = config.raw_env
+        return env if keys.any? { |k| env[k].to_s.strip != "" }
       end
 
-      merged
+      {}
     end
 
     def resolve_env(production)
-      mcp_env = resolve_mcp_env
+      mcp_env = if production
+        scoped_env("RAILS_MARKUP_PROD_URL", "RAILS_MARKUP_PROD_TOKEN")
+      else
+        scoped_env("RAILS_MARKUP_DEV_URL", "RAILS_MARKUP_DEV_TOKEN")
+      end
 
       if production
         base_url = options[:url] || mcp_env["RAILS_MARKUP_PROD_URL"]

data/lib/rails_markup/http_server.rb

@@ -2,6 +2,8 @@
 
 require "webrick"
 require "json"
+require "ipaddr"
+require "uri"
 
 module RailsMarkup
   # HTTP server providing REST API + SSE for the browser-side annotation controller.
@@ -52,17 +54,17 @@ module RailsMarkup
     end
 
     def do_OPTIONS(req, res)
-      cors(res)
+      cors(req, res)
       res.status = 204
     end
 
     def do_GET(req, res)
-      cors(res)
+      cors(req, res)
       route(req, res)
     end
 
     def do_POST(req, res)
-      cors(res)
+      cors(req, res)
       route(req, res)
     end
 
@@ -161,6 +163,10 @@ module RailsMarkup
       return not_found(res) unless annotation
 
       json_response(res, @store.serialize_annotation(annotation), status: 201)
+    rescue Store::ValidationError => error
+      json_response(res, { error: error.message }, status: 422)
+    rescue Store::CapacityError => error
+      json_response(res, { error: error.message }, status: 507)
     end
 
     # --- SSE ---
@@ -173,8 +179,6 @@ module RailsMarkup
       res["Content-Type"] = "text/event-stream"
       res["Cache-Control"] = "no-cache"
       res["Connection"] = "keep-alive"
-      res["Access-Control-Allow-Origin"] = "*"
-
       res.chunked = true
       res.body = proc do |out|
         sub = @store.subscribe(session_id) do |data|
@@ -200,11 +204,26 @@ module RailsMarkup
 
     # --- Helpers ---
 
-    def cors(res)
-      port = @server[:Port] rescue 4747
-      res["Access-Control-Allow-Origin"]  = "http://localhost:#{port}"
+    def cors(req, res)
+      origin = req["Origin"]
+      res["Access-Control-Allow-Origin"] = origin if loopback_origin?(origin)
       res["Access-Control-Allow-Methods"] = "GET, POST, OPTIONS"
       res["Access-Control-Allow-Headers"] = "Content-Type"
+      res["Vary"] = "Origin"
+    end
+
+    def loopback_origin?(origin)
+      return false unless origin.is_a?(String)
+
+      uri = URI.parse(origin)
+      return false unless %w[http https].include?(uri.scheme)
+      return false if uri.host.nil? || uri.userinfo || uri.query || uri.fragment
+      return false unless uri.path.empty?
+      return true if uri.host.casecmp?("localhost")
+
+      IPAddr.new(uri.host).loopback?
+    rescue URI::InvalidURIError, IPAddr::InvalidAddressError
+      false
     end
 
     def json_response(res, data, status: 200)

data/lib/rails_markup/http_store_proxy.rb

@@ -79,7 +79,11 @@ module RailsMarkup
       data
     end
 
-    # Watch not supported via HTTP proxy — return empty after timeout
+    def supports_subscriptions?
+      false
+    end
+
+    # Watch is rejected by McpServer before subscription in proxy mode.
     def subscribe(_session_id = nil, &_block)
       nil
     end

data/lib/rails_markup/mcp_server.rb

@@ -22,6 +22,9 @@ module RailsMarkup
     class ToolError < StandardError; end
     class TargetError < ToolError; end
 
+    MAX_ACTION_MESSAGE_LENGTH = 5_000
+    MAX_ACTION_MESSAGE_BYTES = 5_000
+
     ENV_SCHEMA = {
       environment: {
         type: "string",
@@ -74,7 +77,11 @@ module RailsMarkup
           properties: {
             action: { type: "string", enum: %w[acknowledge resolve], description: "State transition to apply." },
             annotationId: { type: "string", description: "The annotation ID" },
-            summary: { type: "string", description: "Optional resolution summary; valid only for resolve." },
+            summary: {
+              type: "string",
+              maxLength: MAX_ACTION_MESSAGE_LENGTH,
+              description: "Optional resolution summary; valid only for resolve."
+            },
             **ENV_SCHEMA
           },
           required: %w[action annotationId],
@@ -89,7 +96,7 @@ module RailsMarkup
           type: "object",
           properties: {
             annotationId: { type: "string", description: "The annotation ID" },
-            message: { type: "string", description: "Reply message" },
+            message: { type: "string", maxLength: MAX_ACTION_MESSAGE_LENGTH, description: "Reply message" },
             **ENV_SCHEMA
           },
           required: %w[annotationId message],
@@ -104,7 +111,7 @@ module RailsMarkup
           type: "object",
           properties: {
             annotationId: { type: "string", description: "The annotation ID" },
-            reason: { type: "string", description: "Reason for dismissal" },
+            reason: { type: "string", maxLength: MAX_ACTION_MESSAGE_LENGTH, description: "Reason for dismissal" },
             **ENV_SCHEMA
           },
           required: %w[annotationId reason],
@@ -372,11 +379,14 @@ module RailsMarkup
         return "action must be acknowledge or resolve." unless %w[acknowledge resolve].include?(args["action"])
         return "annotationId must be a non-empty string." unless nonempty_string?(args["annotationId"])
         return "summary must be a string." if args.key?("summary") && !args["summary"].is_a?(String)
+        return oversized_action_message_error("summary", args["summary"]) if oversized_action_message?(args["summary"])
         return "summary is only valid for resolve." if args["action"] != "resolve" && args.key?("summary")
       when "rails_markup_reply"
         return "annotationId and message must be non-empty strings." unless nonempty_string?(args["annotationId"]) && nonempty_string?(args["message"])
+        return oversized_action_message_error("message", args["message"]) if oversized_action_message?(args["message"])
       when "rails_markup_dismiss"
         return "annotationId and reason must be non-empty strings." unless nonempty_string?(args["annotationId"]) && nonempty_string?(args["reason"])
+        return oversized_action_message_error("reason", args["reason"]) if oversized_action_message?(args["reason"])
       when "rails_markup_watch"
         return "sessionId must be a non-empty string." if args.key?("sessionId") && !nonempty_string?(args["sessionId"])
         unless !args.key?("timeoutSeconds") || numeric_between?(args["timeoutSeconds"], 0, 300)
@@ -400,6 +410,14 @@ module RailsMarkup
       value.is_a?(Numeric) && value.finite? && value.between?(minimum, maximum)
     end
 
+    def oversized_action_message?(value)
+      value.is_a?(String) && value.bytesize > MAX_ACTION_MESSAGE_BYTES
+    end
+
+    def oversized_action_message_error(name, _value)
+      "#{name} exceeds #{MAX_ACTION_MESSAGE_BYTES} bytes."
+    end
+
     def invalid_arguments_response(id, _unknown)
       tool_error_response(id, "Remove unsupported arguments.")
     end
@@ -589,6 +607,10 @@ module RailsMarkup
     # ── Watch mode ────────────────────────────────────────────
 
     def handle_watch(args)
+      unless @store.respond_to?(:supports_subscriptions?) && @store.supports_subscriptions?
+        raise ToolError, "Watch is unsupported in HTTP proxy (mcp-only) mode; poll with rails_markup_read instead."
+      end
+
       sub = nil
       timeout = [args["timeoutSeconds"]&.to_i || 120, 300].min
       batch_window = [args["batchWindowSeconds"]&.to_i || 10, 60].min

data/lib/rails_markup/store.rb

@@ -7,20 +7,35 @@ module RailsMarkup
   # In-memory store for sessions and annotations.
   # Ephemeral by design — data lives for one coding session.
   class Store
+    class ValidationError < StandardError; end
+    class CapacityError < StandardError; end
+
     Session    = Struct.new(:id, :url, :metadata, :created_at, :annotations, keyword_init: true)
     Annotation = Struct.new(:id, :session_id, :target, :content, :intent, :severity, :status,
                             :selected_text, :metadata, :created_at, :thread, keyword_init: true)
 
     MAX_SESSIONS = 100
     SESSION_TTL  = 4 * 3600 # 4 hours
+    MAX_ANNOTATIONS_PER_SESSION = 1_000
+    MAX_ANNOTATION_BYTES = 25_000_000
+    MAX_CONTENT_BYTES = 5_000
+    MAX_TARGET_BYTES = 16_384
+    MAX_SELECTED_TEXT_BYTES = 2_000
+    MAX_METADATA_BYTES = 65_536
+    MAX_THREAD_MESSAGE_BYTES = 5_000
+    INTENTS = %w[fix change question approve].freeze
+    SEVERITIES = %w[suggestion important blocking].freeze
 
     attr_reader :sessions
 
-    def initialize
+    def initialize(max_annotations_per_session: MAX_ANNOTATIONS_PER_SESSION,
+                   max_annotation_bytes: MAX_ANNOTATION_BYTES)
       @sessions          = {}
       @annotations_index = {} # id -> annotation (O(1) lookup)
       @subscribers       = [] # SSE callbacks: [session_id, callback]
       @mutex             = Mutex.new
+      @max_annotations_per_session = max_annotations_per_session
+      @max_annotation_bytes = max_annotation_bytes
     end
 
     # --- Sessions ---
@@ -53,6 +68,9 @@ module RailsMarkup
 
     def create_annotation(session_id:, target:, content:, intent: "change", severity: "suggestion",
                           selected_text: nil, metadata: {})
+      annotation_bytes = validate_annotation!(
+        target:, content:, intent:, severity:, selected_text:, metadata:
+      )
       id = SecureRandom.hex(8)
       annotation = Annotation.new(
         id: id,
@@ -73,6 +91,7 @@ module RailsMarkup
         session = @sessions[session_id]
         return nil unless session
 
+        enforce_session_capacity!(session, annotation_bytes)
         session.annotations << annotation
         @annotations_index[id] = annotation
       end
@@ -101,35 +120,64 @@ module RailsMarkup
     # --- Status transitions ---
 
     def acknowledge(annotation_id)
-      update_status(annotation_id, "acknowledged")
+      @mutex.synchronize do
+        ann = @annotations_index[annotation_id]
+        return nil unless ann
+        return ann if ann.status == "acknowledged"
+
+        validate_transition!(ann, "acknowledged", from: %w[pending])
+        ann.status = "acknowledged"
+        ann
+      end
     end
 
     def resolve(annotation_id, summary: nil)
-      ann = update_status(annotation_id, "resolved")
-      return nil unless ann
+      changed = false
+      ann = @mutex.synchronize do
+        annotation = @annotations_index[annotation_id]
+        return nil unless annotation
+        return annotation if annotation.status == "resolved"
+
+        validate_transition!(annotation, "resolved", from: %w[pending acknowledged])
+        append_thread_message!(annotation, summary) unless summary.nil? || summary == ""
+        annotation.status = "resolved"
+        changed = true
+        annotation
+      end
+      return ann unless changed
 
-      ann.thread << { role: "agent", message: summary, timestamp: Time.now.iso8601 } if summary
       notify(ann.session_id, type: "annotation_update", annotation: serialize_annotation(ann),
                              status: "resolved", summary: summary)
       ann
     end
 
     def dismiss(annotation_id, reason: nil)
-      ann = update_status(annotation_id, "dismissed")
-      return nil unless ann
+      changed = false
+      ann = @mutex.synchronize do
+        annotation = @annotations_index[annotation_id]
+        return nil unless annotation
+        return annotation if annotation.status == "dismissed"
+
+        validate_transition!(annotation, "dismissed", from: %w[pending acknowledged])
+        append_thread_message!(annotation, reason) unless reason.nil? || reason == ""
+        annotation.status = "dismissed"
+        changed = true
+        annotation
+      end
+      return ann unless changed
 
-      ann.thread << { role: "agent", message: reason, timestamp: Time.now.iso8601 } if reason
       notify(ann.session_id, type: "annotation_update", annotation: serialize_annotation(ann),
                              status: "dismissed", reason: reason)
       ann
     end
 
     def reply(annotation_id, message:)
-      ann = get_annotation(annotation_id)
-      return nil unless ann
+      ann = @mutex.synchronize do
+        annotation = @annotations_index[annotation_id]
+        return nil unless annotation
 
-      @mutex.synchronize do
-        ann.thread << { role: "agent", message: message, timestamp: Time.now.iso8601 }
+        append_thread_message!(annotation, message)
+        annotation
       end
       notify(ann.session_id, type: "annotation_update", annotation: serialize_annotation(ann),
                              status: ann.status, message: message)
@@ -148,6 +196,10 @@ module RailsMarkup
       @mutex.synchronize { @subscribers.delete(sub) }
     end
 
+    def supports_subscriptions?
+      true
+    end
+
     # --- Serialization ---
 
     def serialize_session(session)
@@ -179,27 +231,109 @@ module RailsMarkup
 
     private
 
-    def update_status(annotation_id, new_status)
-      ann = get_annotation(annotation_id)
-      return nil unless ann
+    def validate_transition!(annotation, new_status, from:)
+      return if from.include?(annotation.status)
 
-      @mutex.synchronize { ann.status = new_status }
-      ann
+      raise ValidationError, "cannot transition #{annotation.status} annotation to #{new_status}"
+    end
+
+    def append_thread_message!(annotation, message)
+      validate_string!("message", message, maximum: MAX_THREAD_MESSAGE_BYTES)
+      new_thread = annotation.thread + [{ role: "agent", message: message, timestamp: Time.now.iso8601 }]
+      enforce_thread_capacity!(annotation, new_thread)
+      annotation.thread = new_thread
+    end
+
+    def enforce_thread_capacity!(annotation, new_thread)
+      current_bytes = aggregate_annotation_bytes
+      proposed_bytes = current_bytes - annotation_storage_bytes(annotation) +
+        annotation_storage_bytes(annotation, thread: new_thread)
+      return if proposed_bytes <= @max_annotation_bytes
+
+      raise CapacityError, "aggregate annotation byte limit of #{@max_annotation_bytes} reached"
     end
 
     def notify(session_id, data)
+      subscribers = @mutex.synchronize do
+        @subscribers.select { |sid, _callback| sid.nil? || sid == session_id }
+      end
       dead = []
-      @mutex.synchronize do
-        @subscribers.each do |sub|
-          sid, callback = sub
-          next unless sid.nil? || sid == session_id
+      subscribers.each do |sub|
+        _sid, callback = sub
+        callback.call(data)
+      rescue StandardError
+        dead << sub
+      end
+      @mutex.synchronize { dead.each { |sub| @subscribers.delete(sub) } } unless dead.empty?
+    end
 
-          callback.call(data)
-        rescue StandardError
-          dead << sub
-        end
-        dead.each { |s| @subscribers.delete(s) }
+    def validate_annotation!(target:, content:, intent:, severity:, selected_text:, metadata:)
+      validate_target!(target)
+      validate_string!("content", content, maximum: MAX_CONTENT_BYTES)
+      validate_optional_string!("selected_text", selected_text, maximum: MAX_SELECTED_TEXT_BYTES)
+      raise ValidationError, "intent is invalid" unless INTENTS.include?(intent)
+      raise ValidationError, "severity is invalid" unless SEVERITIES.include?(severity)
+      raise ValidationError, "metadata must be an object" unless metadata.nil? || metadata.is_a?(Hash)
+
+      metadata_bytes = JSON.generate(metadata || {}).bytesize
+      raise ValidationError, "metadata exceeds #{MAX_METADATA_BYTES} bytes" if metadata_bytes > MAX_METADATA_BYTES
+
+      JSON.generate(
+        target:, content:, intent:, severity:, selected_text:, metadata: metadata || {}, thread: []
+      ).bytesize
+    rescue JSON::GeneratorError, Encoding::UndefinedConversionError
+      raise ValidationError, "annotation fields must be JSON serializable"
+    end
+
+    def validate_string!(name, value, maximum:)
+      raise ValidationError, "#{name} must be a non-empty string" unless value.is_a?(String) && !value.empty?
+      raise ValidationError, "#{name} exceeds #{maximum} bytes" if value.bytesize > maximum
+    end
+
+    def validate_target!(target)
+      if target.is_a?(String)
+        return validate_string!("target", target, maximum: MAX_TARGET_BYTES)
       end
+      raise ValidationError, "target must be a non-empty string or object" unless target.is_a?(Hash)
+
+      target_bytes = JSON.generate(target).bytesize
+      raise ValidationError, "target exceeds #{MAX_TARGET_BYTES} bytes" if target_bytes > MAX_TARGET_BYTES
+    end
+
+    def validate_optional_string!(name, value, maximum:)
+      return if value.nil?
+
+      raise ValidationError, "#{name} must be a string" unless value.is_a?(String)
+      raise ValidationError, "#{name} exceeds #{maximum} bytes" if value.bytesize > maximum
+    end
+
+    def enforce_session_capacity!(session, incoming_bytes)
+      if session.annotations.length >= @max_annotations_per_session
+        raise CapacityError, "session annotation limit of #{@max_annotations_per_session} reached"
+      end
+
+      current_bytes = aggregate_annotation_bytes
+      return if current_bytes + incoming_bytes <= @max_annotation_bytes
+
+      raise CapacityError, "aggregate annotation byte limit of #{@max_annotation_bytes} reached"
+    end
+
+    def aggregate_annotation_bytes
+      @sessions.values.sum do |stored_session|
+        stored_session.annotations.sum { |annotation| annotation_storage_bytes(annotation) }
+      end
+    end
+
+    def annotation_storage_bytes(annotation, thread: annotation.thread)
+      JSON.generate(
+        target: annotation.target,
+        content: annotation.content,
+        intent: annotation.intent,
+        severity: annotation.severity,
+        selected_text: annotation.selected_text,
+        metadata: annotation.metadata,
+        thread: thread
+      ).bytesize
     end
 
     def evict_stale_sessions

data/lib/rails_markup/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsMarkup
-  VERSION = "1.3.0"
+  VERSION = "1.4.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-markup
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.1
 platform: ruby
 authors:
 - InventList
@@ -139,6 +139,7 @@ files:
 - config/routes.rb
 - db/migrate/20260720000000_add_client_uuid_to_rails_markup_annotations.rb
 - db/migrate/20260721000000_backfill_rails_markup_client_uuids.rb
+- db/migrate/20260726000000_add_revision_to_rails_markup_annotations.rb
 - lib/generators/rails_markup/install/templates/auth_controller.rb.erb
 - lib/generators/rails_markup/install/templates/bin_markup.erb
 - lib/generators/rails_markup/install/templates/create_rails_markup_annotations.rb.erb