pubid 2.0.0.pre.alpha.8 → 2.0.0.pre.alpha.11

data/lib/pubid/nist/caster.rb

@@ -32,7 +32,7 @@ module Pubid
         when :publisher
           return nil if value.nil? || value.to_s.strip.empty?
 
-          # publisher is a plain string attribute (see Identifiers::Base).
+          # publisher is a plain string attribute (see Identifier).
           value.to_s
 
         when :dated_date
@@ -48,6 +48,11 @@ module Pubid
 
           { dated_seq: value.to_s }
 
+        when :year
+          # Bare 4-digit year (e.g. from "NIST Research Library (2022)").
+          # The Identifier#year attribute is typed as :integer.
+          value&.to_s&.to_i
+
         when :series
           return nil if value.nil? || value.to_s.strip.empty?
 
@@ -196,9 +201,6 @@ module Pubid
                                            value: data[:letter_suffix].to_s.upcase),
                 edition: Components::Edition.new(type: "r",
                                                  id: data[:revision_id].to_s),
-                edition_component: Components::Edition.new(type: "r",
-                                                            id: data[:revision_id].to_s),
-                revision: "r#{data[:revision_id]}",
               }
             end
 
@@ -633,7 +635,7 @@ module Pubid
 
         when :parsed_format
           # Format detection result from parser. :short is the render default
-          # (a nil parsed_format renders short — see Identifiers::Base#to_s), so
+          # (a nil parsed_format renders short — see Identifier#to_s), so
           # store only non-default formats (e.g. "mr"); "short" stays unset and
           # is omitted from to_hash. detect_format only emits :mr or :short.
           v = value&.to_s
@@ -877,8 +879,6 @@ module Pubid
           # Store as id directly - renders as "e199206"
           {
             edition: Components::Edition.new(type: "e", id: edition_date),
-            edition_component: Components::Edition.new(type: "e",
-                                                       id: edition_date),
           }
 
         when :edition_e
@@ -889,8 +889,6 @@ module Pubid
 
           {
             edition: Components::Edition.new(type: "e", id: edition_id),
-            edition_component: Components::Edition.new(type: "e",
-                                                       id: edition_id),
           }
 
         when :edition_r
@@ -901,9 +899,6 @@ module Pubid
 
           {
             edition: Components::Edition.new(type: "r", id: edition_id),
-            edition_component: Components::Edition.new(type: "r",
-                                                       id: edition_id),
-            revision: "r#{edition_id}", # Also set revision string attribute for compatibility
           }
 
         when :edition_r_no_space
@@ -915,9 +910,6 @@ module Pubid
 
           {
             edition: Components::Edition.new(type: "r", id: edition_id),
-            edition_component: Components::Edition.new(type: "r",
-                                                       id: edition_id),
-            revision: "r#{edition_id}", # Also set revision string attribute for compatibility
           }
 
         when :edition_rev
@@ -928,9 +920,6 @@ module Pubid
 
           {
             edition: Components::Edition.new(type: "r", id: edition_id),
-            edition_component: Components::Edition.new(type: "r",
-                                                       id: edition_id),
-            revision: "r#{edition_id}", # Also set revision string attribute for compatibility
           }
 
         when :edition_r_letter
@@ -943,10 +932,6 @@ module Pubid
           {
             edition: Components::Edition.new(type: "r", id: edition_id,
                                              additional_text: edition_letter),
-            edition_component: Components::Edition.new(type: "r",
-                                                       id: edition_id,
-                                                       additional_text: edition_letter),
-            revision: "r#{edition_id}#{edition_letter}", # Also set revision string attribute for compatibility
           }
 
         when :edition_r_letter_only
@@ -957,9 +942,6 @@ module Pubid
 
           {
             edition: Components::Edition.new(type: "r", id: edition_letter),
-            edition_component: Components::Edition.new(type: "r",
-                                                       id: edition_letter),
-            revision: "r#{edition_letter}", # Also set revision string attribute for compatibility
           }
 
         when :edition_historical
@@ -970,8 +952,6 @@ module Pubid
 
           {
             edition: Components::Edition.new(type: "-", id: edition_id),
-            edition_component: Components::Edition.new(type: "-",
-                                                       id: edition_id),
           }
 
         when :edition_r_with_space_letter
@@ -991,10 +971,6 @@ module Pubid
             {
               edition: Components::Edition.new(type: "r", id: edition_id,
                                                additional_text: edition_letter),
-              edition_component: Components::Edition.new(type: "r",
-                                                         id: edition_id,
-                                                         additional_text: edition_letter),
-              revision: "r#{edition_id}#{edition_letter}",
             }
           else
             # Space was in original input - preserve format
@@ -1002,11 +978,6 @@ module Pubid
               edition: Components::Edition.new(type: "r", id: edition_id,
                                                additional_text: edition_letter,
                                                original_prefix: " r"),
-              edition_component: Components::Edition.new(type: "r",
-                                                         id: edition_id,
-                                                         additional_text: edition_letter,
-                                                         original_prefix: " r"),
-              revision: "r#{edition_id}#{edition_letter}",
             }
           end
 
@@ -1027,19 +998,12 @@ module Pubid
             # No original_prefix - space was added by preprocessing
             {
               edition: Components::Edition.new(type: "r", id: edition_id),
-              edition_component: Components::Edition.new(type: "r",
-                                                         id: edition_id),
-              revision: "r#{edition_id}",
             }
           else
             # Space was in original input - preserve format
             {
               edition: Components::Edition.new(type: "r", id: edition_id,
                                                original_prefix: " r"),
-              edition_component: Components::Edition.new(type: "r",
-                                                         id: edition_id,
-                                                         original_prefix: " r"),
-              revision: "r#{edition_id}",
             }
           end
 
@@ -1089,7 +1053,6 @@ module Pubid
                 )
                 return {
                   edition: edition_obj,
-                  edition_component: edition_obj,
                   edition_year: edition_id.to_s,
                 }
               else
@@ -1113,7 +1076,6 @@ module Pubid
           # Return as hash to set edition and edition_year
           {
             edition: edition_obj, # Main attribute for tests
-            edition_component: edition_obj, # V2 component
             edition_year: value.to_s, # Keep string for render logic
           }
 

data/lib/pubid/nist/circular_supplement_builder.rb

@@ -25,7 +25,7 @@ module Pubid
         @builder = builder
       end
 
-      # Build CircularSupplement with base_identifier wrapping
+      # Build CircularSupplement with base wrapping
       # @param parsed_hash [Hash] the parsed supplement data
       # Build a CIRC/LCIRC supplement. Most forms collapse onto the base
       # identifier's normal class (Circular / LetterCircular) with isolated
@@ -56,10 +56,12 @@ module Pubid
           ys = range[:supp_year_start]&.to_s
           me = range[:supp_month_end]&.to_s
           ye = range[:supp_year_end]&.to_s
+          # Month is optional: a year-only range ("sup1925-1926") passes just the
+          # bare year, which supplement_from parses into year/year_end.
           identifier.supplement = @builder.supplement_from(
             value: nil, has_revision: false,
-            range_start: (ms && ys ? "#{ms}#{ys}" : nil),
-            range_end: (me && ye ? "#{me}#{ye}" : nil)
+            range_start: (ys ? "#{ms}#{ys}" : nil),
+            range_end: (ye ? "#{me}#{ye}" : nil)
           )
           return identifier
         end
@@ -216,7 +218,7 @@ module Pubid
 
           # Recursively build base identifier
           # This will go through normal build() process which extracts edition from "101e2"
-          supplement.base_identifier = @builder.build(base_hash)
+          supplement.base = @builder.build(base_hash)
 
           # NEW: Handle revision + implicit supplement pattern (e.g., "145r11/1925")
           # Create update format: "Upd1-{year}{revision_number}"
@@ -246,7 +248,7 @@ module Pubid
           }
 
           # Recursively build base identifier
-          supplement.base_identifier = @builder.build(base_hash)
+          supplement.base = @builder.build(base_hash)
         end
 
         # Build supplement edition from captured data

data/lib/pubid/nist/components/stage.rb

@@ -16,10 +16,10 @@ module Pubid
         attribute :id, :string          # i, f, 1-9
         attribute :type, :string        # pd, wd, prd
 
-        # Load stages from V1 YAML config
+        # Load stages from data/nist/stages.yaml
         STAGES = YAML.load_file(
           File.join(File.dirname(__FILE__),
-                    "../../../../archived-gems/pubid-nist/stages.yaml"),
+                    "../../../../data/nist/stages.yaml"),
         ).freeze
 
         # Render stage in specified format

data/lib/pubid/nist/components/supplement.rb

@@ -139,8 +139,9 @@ module Pubid
         end
 
         # A range is marked by the presence of an END; START reuses month/year.
+        # Months are optional, so a year-only range ("1925-1926") also counts.
         def date_range?
-          month && year && month_end && year_end
+          year && year_end
         end
 
         def build_date_range_format
@@ -164,7 +165,9 @@ module Pubid
         end
 
         def build_long_date_range_format
-          "Supplement #{month} #{year}-#{month_end} #{year_end}"
+          start = [month, year].compact.join(" ")
+          finish = [month_end, year_end].compact.join(" ")
+          "Supplement #{start}-#{finish}"
         end
 
         def build_long_month_year_format

data/lib/pubid/nist/configuration.rb

@@ -58,7 +58,7 @@ module Pubid
       private
 
       def default_series_path
-        File.join(__dir__, "../../../gems/pubid-nist/series.yaml")
+        File.join(__dir__, "../../../data/nist/series.yaml")
       end
 
       def load_series
@@ -72,6 +72,10 @@ module Pubid
       end
     end
 
-    class ConfigurationError < StandardError; end
+    # Raised when the NIST series YAML cannot be loaded. Included in the
+    # marker module so `rescue Pubid::Errors::Error` stays exhaustive.
+    class ConfigurationError < StandardError
+      include ::Pubid::Errors::Error
+    end
   end
 end

data/lib/pubid/nist/identifier.rb

@@ -3,8 +3,6 @@
 # The NIST flavor base class is Pubid::Nist::Identifier — a real
 # Pubid::Identifier subclass that every concrete NIST identifier descends from,
 # so `id.is_a?(Pubid::Nist::Identifier)` and the shared polymorphic `from_hash`
-# work natively (no facade needed). Its full body, `.parse`, and the
-# Identifiers::Base back-compat alias are defined in identifiers/base.rb to keep
+# work natively (no facade needed). Its full body and `.parse` are defined in identifiers/base.rb to keep
 # that large body in one place; this file just ensures it is loaded when a
 # consumer references Pubid::Nist::Identifier directly.
-require_relative "identifiers/base"

data/lib/pubid/nist/identifiers/base.rb

@@ -3,9 +3,7 @@
 module Pubid
   module Nist
     # NIST/NBS flavor base class. Canonical name Pubid::Nist::Identifier; every
-    # concrete NIST identifier (Identifiers::*) descends from it, and
-    # Identifiers::Base — aliased at the foot of this file — points back to it
-    # for backward compatibility. Being a real Pubid::Identifier subclass gives
+    # concrete NIST identifier (Identifiers::*) descends from it. Being a real Pubid::Identifier subclass gives
     # native `is_a?` identity and the shared polymorphic `from_hash`.
     class Identifier < ::Pubid::Identifier
       # Delegate to the flavor module so callers can use
@@ -14,6 +12,77 @@ module Pubid
         Pubid::Nist.parse(identifier)
       end
 
+      # Compact, index-friendly serialization (mirrors the key_value flavors
+      # ISO/ITU/ETSI, without a 38-field key_value block). Two transforms,
+      # applied symmetrically by to_hash/from_hash so the round-trip stays
+      # idempotent:
+      #   - flatten the single-value Code components (series, number) to bare
+      #     scalars — `value` is the only stored field. NIST's
+      #     `Components::Code#part` is a *computed* reader
+      #     (`value.split("-").last`), and prefix/subpart/parts are never
+      #     assigned on series/number, so the scalar `value` is lossless:
+      #     expand recomputes exactly what the object would compute anyway;
+      #   - flatten the plain single-value components (volume) to bare scalars
+      #     too — `Components::Volume` holds only `value`, so it expands to a
+      #     bare { "value" => … } with no part;
+      #   - drop the redundant build artifacts, decomposed pieces of the
+      #     canonical number that identity/rendering never read.
+      COMPACT_FLAT_CODES = %w[series number subseries].freeze
+      COMPACT_FLAT_VALUES = %w[volume].freeze
+      COMPACT_DROP_ATTRS = %w[first_number second_number].freeze
+
+      # Deserialize a (possibly compact) hash: expand the flattened scalars
+      # back into Code sub-hashes, then let the shared polymorphic from_hash
+      # do the real work. Nested `base` documents are expanded recursively by
+      # their own from_hash via apply_mappings, so only this level is touched.
+      def self.from_hash(data, options = {})
+        super(expand_compact_hash(data), options)
+      end
+
+      # Expand a compact hash in place-safe fashion: a scalar series/number
+      # becomes { "value" => …, "part" => <last-dash segment> }.
+      def self.expand_compact_hash(data)
+        return data unless data.is_a?(::Hash)
+
+        out = data.dup
+        COMPACT_FLAT_CODES.each do |key|
+          out[key] = expand_code(out[key]) if out[key].is_a?(::String)
+        end
+        COMPACT_FLAT_VALUES.each do |key|
+          out[key] = { "value" => out[key] } if out[key].is_a?(::String)
+        end
+        out
+      end
+
+      # A flattened Code scalar -> { "value" => …, "part" => <last-dash seg> }.
+      def self.expand_code(value)
+        code = { "value" => value }
+        code["part"] = value.split("-").last if value.include?("-")
+        code
+      end
+
+      # Serialize, then apply the compact transforms (recursing into a nested
+      # `base`, which lutaml serialized via its own transform — bypassing this
+      # override — so it is not compacted otherwise).
+      def to_hash(*args)
+        hash = super
+        compact_hash!(hash) if hash.is_a?(::Hash)
+        hash
+      end
+
+      def compact_hash!(hash)
+        COMPACT_DROP_ATTRS.each { |key| hash.delete(key) }
+        (COMPACT_FLAT_CODES + COMPACT_FLAT_VALUES).each do |key|
+          value = hash[key]
+          next unless value.is_a?(::Hash) && value.key?("value")
+
+          hash[key] = value["value"]
+        end
+        compact_hash!(hash["base"]) if hash["base"].is_a?(::Hash)
+        hash
+      end
+      private :compact_hash!
+
       # Default: no typed stages. Subclasses override as needed.
       def self.typed_stages
         []
@@ -29,11 +98,23 @@ module Pubid
       # raw string the circular/supplement builders pass straight through.
       attribute :publisher, :string
       attribute :series, Components::Code # Set by Builder from parsed data
+      # SP subseries (Appendix A.2 of the NIST PubID Syntax): for "NIST SP 800-53"
+      # the subseries is "800" and the sequence is "53". Populated by the Builder
+      # when the series is "SP" and the first number matches a known subseries
+      # code. Informational metadata derived from series+number — ignored in
+      # equality so a manually-built id (without subseries set) still equals a
+      # parsed one.
+      attribute :subseries, Components::Code
       attribute :number, Components::Code
 
       # V2 COMPONENTS (Lutaml::Model objects) - PROPER SEPARATION
+      # `edition` (Components::Edition: type + id + additional_text) is the
+      # single source of truth for edition/revision. The former
+      # `edition_component` (a byte-identical duplicate) and the `revision`
+      # string (always "#{edition.type}#{edition.id}") were unfinished V1->V2
+      # migration aliases; both removed. `#revision` survives as a derived
+      # reader below.
       attribute :edition, Components::Edition # Edition (type + id): e2, e2021, r5, -3
-      attribute :edition_component, Components::Edition # V2 edition component (alias)
       attribute :volume, Components::Volume # Volume component (v6)
       attribute :part, Components::Part  # Part component (n1 or pt1)
       attribute :stage, Components::Stage
@@ -52,7 +133,6 @@ module Pubid
 
       # LEGACY attributes (keep for backward compatibility during migration)
       attribute :parts, Components::Code, collection: true
-      attribute :revision, :string
       attribute :revision_year, :string # Year for revision (e.g., r6/1925, r1963, rJun1992)
       attribute :revision_month, :string # Month for revision (e.g., rJun1992)
       attribute :edition_year, :string # Legacy edition year for backward compatibility
@@ -90,6 +170,10 @@ module Pubid
       end
 
       def initialize(**attributes)
+        # This override calls `super()` with no attributes and assigns through
+        # setters instead, so it bypasses the base constructor's coercion and
+        # unknown-key check. Apply them here to keep the cross-flavor contract.
+        attributes = self.class.normalize_init_attributes(attributes)
         super()
 
         attrs = self.class.attributes
@@ -108,12 +192,15 @@ module Pubid
       # Attributes that are build artifacts or rendering aliases, not part
       # of an identifier's logical identity. They diverge between equally-
       # valid spellings of the same id (e.g. long "Rev. 1" vs short "r1"):
-      #   - edition_component: redundant alias of :edition
       #   - first_number/second_number: decomposed parts of the canonical
       #     :number, retained from the parse for building
       #   - parsed_format: records the input format for round-trip rendering
+      #   - subseries: derived from series+number (which SP subseries the
+      #     document belongs to); populated by the Builder for known SP
+      #     subseries codes. Ignored in equality so a manually-built id
+      #     without subseries set still equals a parsed one.
       EQUALITY_IGNORED_ATTRS = %i[
-        edition_component first_number second_number parsed_format
+        first_number second_number parsed_format subseries
       ].freeze
 
       # Logical identity comparison: equal when every attribute except the
@@ -161,21 +248,11 @@ module Pubid
         end
       end
 
-      # Return a copy with the named attributes nil'd. Overrides
-      # Pubid::Identifier#exclude because NIST's initialize is keyword-only
-      # (initialize(**attributes)) while the inherited exclude rebuilds via
-      # the positional self.class.new(attrs) form — passing a positional
-      # hash to a keyword-only initializer raises ArgumentError. Rebuild
-      # with the keyword splat instead.
-      def exclude(*args)
-        excluded_args = args.dup
-        excluded_args << :date if excluded_args.delete(:year)
-
-        attrs = self.class.attributes.each_with_object({}) do |(name, _), h|
-          h[name] = excluded_args.include?(name) ? nil : public_send(name)
-        end
-        self.class.new(**attrs)
-      end
+      # NIST inherits Pubid::Identifier#exclude directly: it now rebuilds via
+      # `self.class.new(**attrs)`, so NIST's keyword-only initialize
+      # (initialize(**attributes)) works without a local override, and the base
+      # version additionally carries the nested-identifier recursion this class's
+      # old copy lacked.
 
       # Short-form supplement fragment ("sup", "sup1924", "supJan1924",
       # "suprev", " supJun1925-Jun1926"), rendered from the structured
@@ -190,15 +267,12 @@ module Pubid
         prefix + (rendered.empty? ? "sup" : rendered)
       end
 
-      # Compute revision from edition component for backward compatibility
+      # Derived, read-only revision string ("r5", "e1979", "-3") for backward
+      # compatibility. `edition` is the single stored representation; this is
+      # never persisted, compared, or merged — just a convenience view of it.
       # @return [String, nil] revision string (e.g., "r5") or nil
       def revision
-        return @revision if @revision
-
-        # Compute from edition component if available
-        if edition&.type && edition.id
-          "#{edition.type}#{edition.id}"
-        end
+        "#{edition.type}#{edition.id}" if edition&.type && edition.id
       end
 
       # Backward compatibility: translation method returns translation_component
@@ -234,13 +308,34 @@ module Pubid
       # @param format [:full, :long, :abbreviated, :short, :mr] output format
       def to_s(format = nil)
         # Handle both keyword argument (hash) and positional argument (symbol/string)
+        annotated = format.is_a?(Hash) ? format[:annotated] : nil
         format = format[:format] if format.is_a?(Hash)
 
         # Default to parsed_format if available (preserves input format on round-trip)
         # Falls back to :short format for output (normalization)
         # Explicit format parameter always overrides parsed_format
-        render(format: :human,
-               nist_format: format || parsed_format&.to_sym || :short)
+        rendered = render(format: :human,
+                          nist_format: format || parsed_format&.to_sym || :short)
+
+        # NIST's `to_s` takes a POSITIONAL format and its `render` override
+        # builds no rendering context, so neither the flag nor the context
+        # reaches the shared hook. Apply the annotation fallback here.
+        annotate_plain_render(rendered, annotated: annotated)
+      end
+
+      # NIST has its own defined MR format (to_mr_style) used by relaton-nist
+      # and downstream tooling. The generic Renderers::MrString does not know
+      # about NIST series, revisions, supplements, etc., so delegate to the
+      # established style for losslessness (issue #142).
+      def to_mr_string
+        to_mr_style
+      end
+
+      # NIST's MR shape is fixed by the pubid standard and stays uppercase
+      # (e.g. `NIST.SP.800-53`). The slug, however, must be lowercase to
+      # match the cross-flavor convention; project the MR through `downcase`.
+      def to_slug
+        to_mr_string.downcase
       end
 
       # Returns weight based on amount of defined attributes
@@ -248,6 +343,8 @@ module Pubid
       # @return [Integer] weight score (higher = more specific)
       def weight
         self.class.attributes.keys.inject(0) do |sum, key|
+          next sum if EQUALITY_IGNORED_ATTRS.include?(key)
+
           val = public_send(key)
           val && !val.to_s.empty? ? sum + 1 : sum
         end
@@ -275,7 +372,7 @@ module Pubid
                          when :edition
                            current_val.nil? || edition_greater?(new_val,
                                                                 current_val)
-                         when :volume, :part, :version, :revision
+                         when :volume, :part, :version
                            current_val.nil? || (new_val.to_s.length > current_val.to_s.length)
                          when :supplement, :errata, :index, :insert, :section, :appendix, :translation
                            true
@@ -411,6 +508,10 @@ module Pubid
         result += " #{number}" if number
         result += parts.map { |p| "-#{p}" }.join if parts&.any?
 
+        # "NIST Research Library (YYYY)" — oddball identifier with no number;
+        # the year appears in parens rather than as a date component.
+        result += " (#{year})" if year && !number
+
         # Append every optional component the parser may have attached
         # (volume, part, edition, version, supplement, update, stage, ...).
         # Shared with the lossy subclasses so they cannot silently drop a
@@ -639,12 +740,5 @@ module Pubid
       end
     end
 
-    module Identifiers
-      # Backward-compatible alias: NIST's base class used to be
-      # Pubid::Nist::Identifiers::Base. It is now Pubid::Nist::Identifier; keep
-      # the old constant working for `class Foo < Base` declarations and any
-      # external reference.
-      Base = Pubid::Nist::Identifier
-    end
   end
 end

data/lib/pubid/nist/identifiers/circular.rb

@@ -7,7 +7,7 @@ module Pubid
       # Examples:
       # - "NBS CIRC 13e2revJune1908" = Circular 13, edition 2, revised June 1908
       # - "NBS CIRC 13" = Circular 13
-      class Circular < Base
+      class Circular < Identifier
         TYPED_STAGES = [
           Pubid::Components::TypedStage.new(
             abbr: ["CIRC", "NBS CIRC"],
@@ -53,7 +53,14 @@ module Pubid
         # Override to_s for CIRC-specific edition+year rendering
         # CIRC uses dot notation: "NBS CIRC 11e2.1915" instead of "NBS CIRC 11e2-1915"
         def to_s(format = nil)
-          result = super
+          # The rewrite below is `$`-anchored, so it has to run on the PLAIN
+          # string: with the flag set, `super` returns a string ending in
+          # "</span>" and the anchor no longer matches. Render plain, rewrite,
+          # then annotate.
+          annotated = format.is_a?(Hash) ? format[:annotated] : nil
+          format = format[:format] if format.is_a?(Hash)
+
+          result = super(format)
 
           # For CIRC edition patterns with additional_text (year), render with dot notation
           # "11e2-1915" format: edition.id="2", additional_text="1915" → render as "11e2.1915"
@@ -65,7 +72,7 @@ module Pubid
                                  "e#{edition.id || '?'}.#{edition.additional_text}")
           end
 
-          result
+          annotate_plain_render(result, annotated: annotated)
         end
       end
     end

data/lib/pubid/nist/identifiers/circular_supplement.rb

@@ -37,13 +37,22 @@ module Pubid
         attribute :implicit_supplement, :boolean # true for implicit supplements (e.g., "145r11/1925")
 
         def to_s(format = :short)
+          # A caller passing `annotated:` reaches this positional parameter as a
+          # Hash. Normalise it away before `super`, so the annotation is applied
+          # once, here, and covers the date-range branch too — that branch
+          # returns a hand-composed string and never reached `super` at all.
+          annotated = format.is_a?(Hash) ? format[:annotated] : nil
+          format = format[:format] || :short if format.is_a?(Hash)
+
           # Handle date range supplements (no base identifier)
-          if supplement_date_range_start && supplement_date_range_end
-            return "NBS CIRC sup#{supplement_date_range_start}-#{supplement_date_range_end}"
-          end
+          result = if supplement_date_range_start && supplement_date_range_end
+                     "NBS CIRC sup#{supplement_date_range_start}-#{supplement_date_range_end}"
+                   else
+                     # Use parent's rendering for base + supplement
+                     super(format)
+                   end
 
-          # Use parent's rendering for base + supplement
-          super
+          annotate_plain_render(result, annotated: annotated)
         end
       end
     end

data/lib/pubid/nist/identifiers/commercial_standard.rb

@@ -9,7 +9,7 @@ module Pubid
       # - "NBS CS 102" - Basic commercial standard
       # - "NBS CS 102E-42" - With letter suffix and number
       # - "CS 190-58" - With year
-      class CommercialStandard < Base
+      class CommercialStandard < Identifier
         TYPED_STAGES = [
           Pubid::Components::TypedStage.new(
             abbr: ["CS", "NBS CS"],

data/lib/pubid/nist/identifiers/commercial_standard_emergency.rb

@@ -6,7 +6,7 @@ module Pubid
       # NBS Commercial Standard (Emergency) Identifier
       # Format: NBS CS eNNN-YY where NNN is edition number, YY is 2-digit year
       # Example: "NBS CS e104-43" = Commercial Standard Emergency edition 104, year 1943
-      class CommercialStandardEmergency < Base
+      class CommercialStandardEmergency < Identifier
         TYPED_STAGES = [
           Pubid::Components::TypedStage.new(
             abbr: ["CS-E", "NBS CS-E"],

data/lib/pubid/nist/identifiers/commercial_standards_monthly.rb

@@ -6,7 +6,7 @@ module Pubid
       # NBS Commercial Standards Monthly Identifier
       # Format: NBS CSM N where N is simple number
       # Example: "NBS CSM 1", "NBS CSM 40"
-      class CommercialStandardsMonthly < Base
+      class CommercialStandardsMonthly < Identifier
         TYPED_STAGES = [
           Pubid::Components::TypedStage.new(
             abbr: ["CSM", "NBS CSM"],
@@ -41,6 +41,12 @@ module Pubid
         end
 
         def to_s(format = nil)
+          # A caller passing `annotated:` reaches this positional parameter as
+          # a Hash — Ruby converts keywords for a method that accepts none.
+          # The same idiom `Identifiers::Base#to_s` uses. This renderer
+          # ignores `format`, so only the flag is read.
+          annotated = format.is_a?(Hash) ? format[:annotated] : nil
+
           result = "#{publisher} #{series}"
 
           # Proper Volume and Part components
@@ -55,7 +61,7 @@ module Pubid
             result += " #{vol_str}n#{issue_number.number}"
           end
 
-          result
+          annotate_plain_render(result, annotated: annotated)
         end
       end
     end