relaton-render 0.4.2 → 3.0.0.pre.alpha.26

data/docs/citation-style-pack.adoc

@@ -0,0 +1,370 @@
+= Defining a Citation Style: the Pack Format
+
+This document is the authoritative authoring specification for a
+CitationStyle pack: the one file that fully describes a citation style.
+It is the contract between three parties — style authors, the rendering
+engine, and the relaton-models citation schema.
+
+Status markers: **[impl]** shipped on this engine line; **[spec]** the
+committed design this engine line converges to (tracked in the
+promotion backlog, section 12).
+
+== 1. The laws
+
+1. **Models are ISO 690.** The relaton-models citation module
+   (`Relaton::Bib::Item` and friends) is the single data substrate for
+   every style. There are no LNCS models, no Chicago models. A
+   bibliographic item is parsed, stored and exchanged once.
+2. **A citation style is one encapsulated data pack.** Everything a
+   style knows lives in the pack: the scheme (name forms, citation
+   system), the locale (labels, punctuation), the presentation
+   templates (citation, reference, per-type patterns), and the
+   presentation-of-models (how each 690 model element presents).
+   Nothing lives in flavor Ruby.
+3. **The pack's field vocabulary is a superset of CSL-JSON.** Every
+   CSL-JSON term has a home; the standards-specific extensions CSL
+   lacks (designations/docids, typed stages, host relations, ordinal
+   editions, bilingual and CJK forms) extend it. The same is true of
+   the logic vocabulary (section 8): it supersets CSL's condition
+   grammar, not a general template engine.
+4. **Engines hold zero styles.** The engine is a generic evaluator of
+   packs. Canonical packs (the ISO 690 default, LNCS, Chicago,
+   IEEE-SA) ship beside the engine while the vocabulary co-evolves and
+   extract to a data repository once it stabilises — the CSL precedent
+   being a separate styles distribution consumed by many processors.
+5. **No Liquid.** The template language is the chunk grammar
+   (section 8): declarative, schema-validated, sandboxed, identical in
+   Ruby and relaton-ts. A fenced `procedural:` escape may exist for
+   experimental packs; canonical styles never reference it.
+
+== 2. The pack file
+
+One YAML document. **[impl]** Loaded and validated by the
+CitationStyle model (`Relaton::Render::Iso690::Style.load` accepts a
+path or a hash; unknown keys are rejected). **[spec]** The model
+itself is owned by relaton-models' citation module; this engine loads
+it, and relaton-ts loads its mirror.
+
+Skeleton — every key, in order:
+
+....
+name: "ISO 690 (metanorma-iso flavour)"
+family: iso690                      # [spec] iso690 | lncs | chicago | ieee-sa
+extends: null                      # [spec] name of a base pack this deltas
+requires:                          # [spec] capability gates this pack needs
+  - extent_group_separator
+
+scheme:
+  system: name-date                # name-date | numeric | designation
+  shortFromReference: true
+  homeDocidType: [ISO, IEC]         # docid types that mark a "home" standard
+  defaultKind: ""                  # kind for types the taxonomy leaves unmapped
+  nameForm:  { ... }               # section 7
+  locale:     { ... }              # section 6
+
+templates:                         # style-wide templates, section 5
+  titleOpen: "_"
+  titleClose: "_"
+  citation: "{{surname}}, {{date}}"
+  reference: "{{creator}}. {{title}}. ..."
+  name: "{{surname}}, {{givenNames}}"
+  series: ""
+  creators: ""
+  uri: "<fmt-link target='{{uri}}'>{{uri}}</fmt-link>"
+  uriShort: ""
+  identifierMode: all              # all | first
+
+types:                             # [spec] section 4: the resource-type taxonomy
+  article-journal: { alias: continuing }
+  standard:      { alias: report }
+
+perType:                           # section 5: the presentation patterns
+  - type: report
+    home: true
+    template: "{{title}}"
+    title: "<span class='stddocTitle'>{{title}}</span>"
+    short: "{{title}}, {{extent}}"
+  - type: monograph
+    noPlace: true
+    fallbacks: { date: "n.d" }
+    template: "{{creator}}{{role}}. {{title}}. ..."
+
+sortKey:                           # index sorting
+  - attribute: creator
+  - attribute: date
+
+rules:                             # [spec] section 9: presentation-of-models
+  identifier: itu                  # named engine rule selections
+  creator: nist_series_publisher
+
+postProcess:                       # [spec] ordered gsub rule chain
+  - pattern: "。+"
+    replace: "。"
+....
+
+== 3. Lifecycle
+
+* **Adopt** — a flavor points its `bibrenderer` at a named canonical
+  pack. Zero code, zero YAML. The target state for new and generic
+  flavors.
+* **Inherit-and-override** — **[spec]** `extends: <pack>` plus a delta.
+  The merge semantics are part of this specification (section 11):
+  `perType`/`types` merge per type key (a delta re-declaring `article`
+  never drops the base's `monograph`); `labels`, `punct`, `fallbacks`
+  and rule selections merge per key; scheme scalars replace. The
+  merge is deterministic and identical in Ruby and TS.
+* **Own pack** — a fully self-contained instance. Last resort; the
+  existing flavor YAMLs are this, and most should collapse into deltas
+  over a canonical base.
+
+**[spec] `requires:`** names engine capabilities, so a resolver fails
+loudly (`pack requires extent_group_separator`) instead of silently
+mis-rendering. Capability names are frozen per engine minor line.
+
+== 4. Info-resource-types
+
+Different information resource types present with different patterns
+in nearly every citation style. The pack's type taxonomy is the axis
+those patterns hang on.
+
+**[impl]** The engine normalises a bibliographic item's wire `type`
+value to an ISO 690 clause-8 resource *kind* through the Kinds table;
+perType entries select on kinds. **[spec]** The taxonomy becomes pack
+data (`types:`), aligned name-for-name with the CSL resource types —
+the same superset law as the fields — with the standards extensions
+CSL lacks.
+
+.Kind taxonomy (ISO 690 clause 8) and its wire-type synonyms [impl]
+[cols="1,3"]
+|===
+|Kind |Wire types
+
+|`monograph` |book, booklet, manual, proceedings, thesis
+|`report` |standard, techreport, report *(the clause 8.11 fallback)*
+|`patent` |patent
+|`continuing` |journal, serial, article-journal, article-magazine
+|`component_part` |inbook, incollection, inproceedings
+|`serial_part` |article
+|`online` |software, unpublished, dataset, webpage, online
+|`webdoc` |website, webresource
+|===
+
+**[spec]** The full recommended taxonomy carries every CSL type
+(`article-journal`, `article-magazine`, `article-newspaper`, `bill`,
+`book`, `broadcast`, `chapter`, `classic`, `collection`, `dataset`,
+`document`, `entry`, `entry-dictionary`, `entry-encyclopedia`,
+`event`, `figure`, `graphic`, `hearing`, `interview`, `legal_case`,
+`legislation`, `manuscript`, `map`, `motion_picture`, `musical_score`,
+`pamphlet`, `paper-conference`, `patent`, `performance`, `periodical`,
+`personal_communication`, `post`, `post-weblog`, `regulation`,
+`report`, `review`, `review-book`, `software`, `song`, `speech`,
+`standard`, `statute`, `thesis`, `treaty`, `webpage`) plus the
+relaton extensions (`techreport`, `inbook`, `incollection`,
+`inproceedings`, `webresource`, `webdoc`, `online`). Rules of the
+taxonomy:
+
+* **Complete, explicit coverage.** Every type resolves to a declared
+  pattern — through an entry, an `alias`, or the declared `fallthrough`
+  (`report`). Nothing inherits silently.
+* **Aliasing is declared**, never engine-hardcoded: `booklet: book`.
+* **Home/external splits sit on top** — for standards-producing
+  bodies, the *same* type carries two patterns, selected by whether
+  the item bears one of `scheme.homeDocidType`'s designations.
+  IEEE-SA's `standard` pattern is *only* designation + title; a
+  Chicago `standard` is cited differently again — same type, different
+  packs, different patterns.
+
+== 5. Presentation patterns (`perType`)
+
+The pattern — not the template — is the unit. A journal-article
+pattern is not a reordered book template; it is its own arrangement
+(quoted title form, italic container, vol/no/pp placement,
+month-abbreviated dates) *plus* its own short cite, fallbacks and
+terminator behaviour. The perType entry carries all of it:
+
+[cols="1,3"]
+|===
+|Field |Meaning
+
+|`type` |the kind (or **[spec]** taxonomy type) this pattern serves
+|`template` |the reference (bibliography entry) arrangement
+|`title`, `series` |per-slot form overrides for this pattern
+|`short` |the short-cite template (falls back to the reference in short mode)
+|`home` |`true` marks the pattern serving items bearing a home docid; two entries of one type split on it
+|`fallbacks` |absent-slot replacement texts, per slot (`date: "n.d"`, `dategroup: "(n.d.)"`)
+|`noPlace` |render the locale's `no_place` label when production lacks a place
+|===
+
+Multiple entries of one `type` resolve: home-flagged variants split by
+the home test; otherwise the first match wins; unmatched kinds fall to
+`templates.reference`.
+
+== 6. Locale, labels and punctuation
+
+**[impl]** Packs overlay the engine language packs (`i18n/<lang>.yml`)
+per language; the pack wins. Adding a language is a new language pack,
+never code.
+
+* `locale.and|others|noDate|noAuthor|in|at|availableAt` — connective
+  strings.
+* `locale.labels` — arbitrary label overrides merged verbatim:
+  `and`, `oxford_comma`, `list_separator`, `series_no`, `no_place`,
+  `available_from`, `ed`/`eds`, `edition_ordinal`/`edition_cardinal`/
+  `version_cardinal` (locale templates, `{{ var1 }}` with the
+  `ordinal_word` filter), extent unit templates (`volume: "vol. %"`,
+  `page: "%頁"` — the `%` carries the value, so a CJK locale places
+  its unit after the number), `extent_group_separator`, month names.
+* `locale.punct` — typographic punctuation: `production_sep`,
+  `production_order` (`publisher_first` for LNCS-style orders),
+  `open-paren`/`close-paren` (ASCII vs fullwidth), `cjk-latin-separator`,
+  `size-join`, `marker-space`.
+* **[spec] `postProcess:`** — the CJK spacing rules that flavors
+  carry as Ruby today become ordered `pattern/replace` rule chains in
+  the pack, so bilingual typography travels with the style.
+
+== 7. Name forms (`scheme.nameForm`) [impl]
+
+Every knob of creator presentation:
+
+[cols="1,3"]
+|===
+|Knob |Effect
+
+|`initials`, `initialsSeparator`, `initialsPeriod` |initials vs given names, "A. B." vs "AB"
+|`invertedAll`, `givenNameFirst` |surname-first for all names / direct order
+|`surnameUpcase`, `subsequentSurnameUpcase`, `subsequentInitials` |caps and second-name forms
+|`completenameUpcase`, `orgUpcase` |verbatim names and organisations
+|`editorsMarked`, `loneEditorMarked`, `rolePlacement` |"(eds.)" markers and their placement
+|`listStyle`, `creatorFallback` |join style; fallback source when no personal creator (OGC: `publisher_abbrev`)
+|`etalCount`, `etalDisplay` |bibliography et-al truncation
+|`inTextEtalCount`, `inTextEtalDisplay` |in-text et-al truncation
+|===
+
+== 8. The template language
+
+**[impl]** Templates are chunk strings: `{{slot}}` fields and literal
+text. The evaluator carries the segment-join semantics — a literal
+renders when it separates two present fields, so absent elements
+swallow their separators; leading and trailing literals drop with
+their fields; parenthetical literals (`({{series}})`, `（{{series}}）`)
+pair as groups that drop whole when the field is absent, balanced on
+the template's literal parens alone; stacked separators collapse;
+trailing terminators apply per style. The short-cite evaluator splits
+after the leading field run at the first-biblio delimiter, which the
+presentation layer turns into the cross-reference capsule.
+
+Slots resolve to the 690 model presentations: `creator`, `title`,
+`edition`, `medium`, `series`, `production`, `date`, `numeration`,
+`component_part`, `identifier`, `location`, `size`, `extent`,
+`access`, `stddoc`, `status`, `citeid`, `authorizer`, `updated`;
+derived fields `role`, `dategroup` (the parenthesised date group),
+`disambiguateddate` (the batch-suffixed date, "2022a"); and the name
+fields (`surname`, `givenNames`, ...).
+
+**[spec]** The logic vocabulary supersets CSL's condition grammar:
+
+* **Conditionals** — `choose`/`if`/`else-if` over `type`, field
+  presence, `home`, and `disambiguated` ( CSL `position`-adjacent ),
+  as declarative blocks inside `perType` entries and templates.
+* **Fallback chains** — `creator: [authors, publisher_abbrev]`:
+  first present source wins, replacing today's single `creatorFallback`
+  knob and OGC's hack.
+* No loops, no arbitrary filters, no string mutation — those are
+  `postProcess` rules or named rules, never template logic.
+
+== 9. Model presentation templates (`rules`) — presentation-of-models
+
+Each 690 model element has a declarative presentation vocabulary; the
+pack selects per-slot rule implementations by name. **[impl]** the
+declarative surface (extent unit `%`-templates, production orders,
+group separators, locale templates, fallbacks); **[spec]** the
+registry: engine implements each named rule once, conformance-tested
+per rule, mirrored in relaton-ts, and addressable as pack data —
+`identifier: itu`, `creator: nist_series_publisher`.
+
+The promotion backlog — every flavor element override still standing
+is a rule to promote:
+
+[cols="2,2"]
+|===
+|Flavor override |Becomes rule
+
+|`ItuIdentifier` |`identifier: itu`
+|`NistIdentifier`, `NistCreator`, `NistDate`, `SerialDate`, `NistSeries`, `NistComponentPart`, `NistPublisher`, `Draft` |the NIST author-year rule set
+|`IeeeIdentifier`, `IeeeComponentPart`, `IeeeAccess`, `IeeeMedium` |the IEEE-SA rule set (designation-first standards)
+|`BipmCreator`, `BipmComponentPart`, `BipmProduction`, `BipmExtent`, `BipmMedium`, `BipmEdition`, `BipmVolume` |the BIPM rule set
+|`IhoEdition`, `IhoCreator` |affiliation-composite creators
+|`JisComponentPart`, `JisSeries`, `JisExtent` |the JIS host-citation rules
+|`BsiStatus` |status presentation
+|===
+
+== 10. Citation forms
+
+**[impl]** The renderings capsule every pack produces (the isodoc
+contract): `author`, `date`, `citation{full, default, short,
+author_date, author_date_br, author, date, reference_tag, title,
+title_reference_tag}`, `formattedref`. `templates.citation` is the
+in-text form; `shortFromReference` takes the reference form with the
+first-biblio marker; batch disambiguation suffixes derive from
+author+date collisions; `identifierMode` governs `default` (first vs
+all designations). **[spec]** `system: numeric | designation` selects
+numeric `[1]`/`[B4]` and designation-led citation systems — the
+IEEE-SA and JIS/BSI homes — as first-class engines, not author-date
+approximations.
+
+== 11. Deltas and the flavor triangle
+
+**[spec]** `extends` resolves base-then-delta at load, on model
+instances (never ad-hoc hash merges):
+
+* `perType`, `types`: merge **per type key** — a delta's `article`
+  entry overlays the base's; the base's other entries survive.
+* `labels`, `punct`, `fallbacks`: per-key merge.
+* `nameForm` knobs, `templates.*`, rule selections: replace — with
+  the caveat that a knob left at its model default counts as unset and
+  inherits (a Lutaml model cannot distinguish an explicit default from
+  an absent key).
+* `sortKey`, `requires`: union.
+
+The forcing test: PLATEAU's four near-copy styles (document-language
+x item-language quadrants) collapse to `extends: jis` plus two
+punct/label deltas. If the merge cannot express that, the merge is
+wrong.
+
+== 12. Validation, versioning, conformance
+
+* **Schema** — the CitationStyle model validates every pack; unknown
+  keys fail at load, not at render. [impl]
+* **`requires:`** — capability gating, frozen names per engine minor
+  line. [spec]
+* **Conformance corpora** — every canonical pack ships a corpus of
+  examples with expected renderings, in the iso690-test tradition:
+  LNCS from Springer's authors' instructions; Chicago from CMOS;
+  IEEE-SA from the Standards Style Manual clause 17 (`[B1] ASME
+  BPVC-I-2004, Title.` designation-only standards; Chicago-derived
+  books/articles with only the first name inverted). CI renders the
+  matrix: every declared type, every pattern, both engine ports.
+* **Portability & safety** — packs are data: they validate, sandbox
+  and render identically server-side (the CF Workers API) and in
+  relaton-ts. No interpreters, no Liquid, no flavor Ruby.
+
+== 13. Authoring walkthrough (LNCS, abridged)
+
+. Declare the pack: `family: lncs`, `extends: null` (canonical),
+  `requires: [production_order, extent_units]`.
+. Name forms: initials without periods, `invertedAll`, direct-order
+  subsequent names, `creatorFallback: [publisher_abbrev]` for
+  standards with no personal authors.
+. Locale: `production_order: publisher_first`, `production_sep: ", "`,
+  year trailing in parentheses (the `dategroup` form).
+. Types and patterns: `paper-conference` ("`{{creator}}: {{title}}.
+  In: {{componentpart}} {{extent}} {{production}} {{dategroup}}.`"),
+  `chapter`, `article-journal`, `book`, `thesis`, `webpage` — one
+  entry each, own `title`/`series` forms, own `short` cites.
+. Rules: `identifier: lncs-series` (LNCS vol./pp. forms).
+. Conformance: the Springer instruction examples become the corpus;
+  the pack merges only when the matrix is green.
+
+The same walk with CMOS examples yields Chicago; with the IEEE-SA
+manual, `family: ieee-sa` — whose `standard` pattern is two fields
+long.

data/lib/relaton/render/general.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Render
+    # Compatibility entry point (relaton-render#90).
+    #
+    # The v2 engine replaced the liquid/config/i18n machinery with the
+    # template evaluator over CitationStyle instances
+    # (Relaton::Render::Iso690). isodoc main's render-isodoc subclasses
+    # this constant, so it must exist for all-git-main stacks to boot.
+    # This facade delegates rendering to the v2 engine; the retired
+    # options (config:, template overrides in liquid syntax) are ignored
+    # with one warning — migrate to a CitationStyle instance, which
+    # expresses everything the old config.yml did (see the citation
+    # module in relaton-models).
+    class General
+      # The eref `style=` vocabulary metanorma-standoc validates against
+      # (cleanup/xref.rb reads citetemplate.template_raw's keys) — the
+      # 1.x default config's top-level citation styles.
+      CITE_STYLES = %i[
+        author_date author_date_br author date reference_tag title
+        title_reference_tag short
+      ].freeze
+
+      CiteTemplate = Struct.new(:template_raw)
+
+      def initialize(options = {})
+        options = deep_symbolize(options)
+        @lang = options[:language] || options[:lang] || "en"
+        renderer_opts = { lang: @lang, script: options[:script] || "Latn",
+                          labels: options[:i18nhash] || {} }
+        # A flavor names its own CitationStyle instance (name or YAML path)
+        options[:style] and renderer_opts[:style] = options[:style]
+        @renderer = Iso690::Renderer.new(**renderer_opts)
+        @renderer_opts = renderer_opts
+        @renderers_by_lang = {}
+        warn_general_config if options[:config]
+      end
+
+      # A collection's items may each declare their own language; the
+      # renderer localizes by language, so a reference renders in its
+      # own language within a document of another (the 1.x plateau
+      # per-reference behaviour)
+      def renderer_for(lang)
+        return @renderer if lang.nil? || lang == @lang
+
+        @renderers_by_lang[lang] ||= Iso690::Renderer.new(
+          **@renderer_opts.merge(lang: lang,
+                                 script: %w(ja ko zh).include?(lang) ? nil : "Latn")
+        )
+      end
+
+      def render(model, embedded: false, **opts)
+        model = to_model(model)
+        text =
+          if model.respond_to?(:formattedref) && model.formattedref
+            model.formattedref.content
+          else
+            @renderer.render(model, **opts)
+          end
+        embedded ? text : "<formattedref>#{text}</formattedref>"
+      end
+
+      def citation(model, **opts)
+        @renderer.citation(to_model(model), **opts)
+      end
+
+      # isodoc's references rendering: renderings[id][:formattedref]
+      # feeds the <formattedref> of every bibitem (isodoc
+      # presentation_function/refs.rb).
+      def render_all(bib, type: "author-date")
+        items = facade_bibitems(bib) or return nil
+        disambiguators = date_disambiguators(items)
+        items.each_with_object({}).with_index do |(item, m), i|
+          renderer = renderer_for(Array(item.language).first)
+          ref = begin
+            renderer.render(item, disambiguator: disambiguators[item.id])
+          rescue ::Relaton::Render::Unrenderable
+            next
+          end
+          m[item.id] = {
+            author: renderer.in_text_author(item),
+            date: renderer.disambiguated_date(item,
+                                              disambiguator:
+                                                disambiguators[item.id]),
+            citation: citation_renderings(item, ref, renderer,
+                                          type: type,
+                                          disambiguator:
+                                            disambiguators[item.id]),
+            formattedref: terminate_reference(ref, item),
+          }
+        end
+      end
+
+      # isodoc's styled citations consume these keys: the default is the
+      # authoritative identifier; the short cite is the style's citation,
+      # falling back to the reference rendering (the 1.x short-cite)
+      FIRST_DELIM = '<span class="fmt-first-biblio-delim"/>'
+
+      # A creator list alone (flavors' document-history name forms)
+      def creator_names(item)
+        @renderer.render_creators(to_model(item))
+      end
+
+      # render_all feeds the bibliography list: a reference not ending
+      # in the biblio terminator takes one (the 1.x render1 behaviour;
+      # single-item render stays verbatim)
+      # The batch disambiguation suffixes ("2022a"): items sharing a
+      # principal-creator surname and a date take alphabetical
+      # suffixes in bibliography order (the 1.x
+      # disambig_author_date_citations)
+      def date_disambiguators(items)
+        keys = items.filter_map do |item|
+          begin
+            [item.id, @renderer.author_key(item),
+             @renderer.citation(item)]
+          rescue ::Relaton::Render::Unrenderable
+            nil
+          end
+        end
+        groups = keys.group_by { |_, author, cite| [author, cite] }
+        suffixes = {}
+        groups.each_value do |group|
+          next if group.size < 2
+
+          group.each_with_index do |(id, _author, _cite), i|
+            suffixes[id] = ("a".ord + i).chr
+          end
+        end
+        suffixes
+      end
+
+      # The bibliography terminator; flavors override to suppress it
+      # (1.x use_terminator?), receiving the item it terminates
+      def terminate_reference(ref, _item = nil)
+        return ref if ref.empty? || ref.rstrip.end_with?(".")
+
+        "#{ref}."
+      end
+
+      # The style-keyed capsule ("citation" => { author_date: "..." })
+      # is what isodoc's styled erefs consume (their style attribute
+      # names the key)
+      def citation_renderings(item, ref, renderer, type: "author-date",
+                              disambiguator: nil)
+        # A style declaring shortFromReference takes the reference form
+        # with the first-biblio marker (the 1.x citetemplate short)
+        short = if renderer.short_from_reference?
+                  renderer.render_short(item, FIRST_DELIM)
+                else
+                  short = renderer.citation(item)
+                  short.empty? ? renderer.render_short(item, FIRST_DELIM) :
+                    short
+                end
+
+        title = renderer.title_citation(item)
+
+        {
+          full: ref,
+          default: item.docidentifier.first&.content.to_s,
+          short: short,
+          author_date: renderer.citation(item,
+                                         disambiguator: disambiguator),
+          author_date_br: renderer.bracketed_date_citation(
+            item, disambiguator: disambiguator,
+          ),
+          author: renderer.in_text_author(item),
+          date: renderer.disambiguated_date(item),
+          # reference_tag: no rendering — isodoc falls back to the
+          # biblio-tag anchor (the 1.x nil)
+          title: title,
+          title_reference_tag: title,
+        }
+      end
+
+      # isodoc's pref_ref_code_parse reads
+      # data[:authoritative_identifier] to build biblio-tag identifiers
+      # (presentation_function/docid.rb). Returns [data, self] as the
+      # 1.x signature did.
+      def parse(doc)
+        [{ authoritative_identifier: facade_docids(doc) }, self]
+      end
+
+      def citetemplate
+        CiteTemplate.new(CITE_STYLES.to_h { |s| [s, ""] })
+      end
+
+      private
+
+      # 1.x accepted a <references> XML string (isodoc strips namespaces
+      # before building it) or a ready array of models.
+      def facade_bibitems(bib)
+        case bib
+        when Array then bib
+        when String
+          require "moxml"
+          root = Moxml.parse(bib).root
+          return nil unless root&.name == "references"
+
+          klass = facade_bibitem_class
+          root.xpath("./bibitem").filter_map { |b| klass.from_xml(b.to_xml) }
+        end
+      end
+
+      def facade_bibitem_class
+        Relaton::Bib::Bibitem
+      rescue NameError
+        Relaton::Bib::Item
+      end
+
+      # 1.x Parse#authoritative_identifier semantics: the
+      # primary/language cascade, the excluded types (URN, DOI, ISBN...)
+      # dropped, and scoped ids (biblio-tag duplicates, IEEE trademark)
+      # demoted within their type group. isodoc hands the live bibitem
+      # node with the document's default namespace still attached, so the
+      # element queries must be namespace-agnostic.
+      EXCLUDED_ID_TYPES = %w(METANORMA METANORMA-ORDINAL AUTHOR-DATE TITLE
+                             URN ISO-REFERENCE ISSN ISBN DOI).freeze
+
+      # Flavors extend the authoritative-identifier exclusions by
+      # overriding this reader on their facade subclass
+      def excluded_id_types
+        EXCLUDED_ID_TYPES
+      end
+
+      def facade_docids(doc)
+        node = doc
+        unless node.respond_to?(:xpath)
+          require "moxml"
+          node = Moxml.parse(doc.to_s).root
+        end
+        return [] unless node
+
+        ids = node.xpath("./*[local-name() = 'docidentifier']")
+        ids = facade_scope_filter(ids)
+        out = nil
+        [
+          ->(x) { x["language"] == @lang && x["primary"] },
+          ->(x) { x["primary"] },
+          ->(x) { x["language"] == @lang },
+          ->(_x) { true },
+        ].each do |p|
+          out = ids.select do |x|
+            p.call(x) && !excluded_id_types.include?(facade_id_type(x))
+          end
+          out.empty? or break
+        end
+        # esc-wrapped: isodoc's l10n skips the tags, leaving a standard
+        # identifier's punctuation verbatim (the 1.x Parse behaviour)
+        out.map { |x| "<esc>#{x.text.strip}</esc>" }
+      end
+
+      def facade_id_type(id)
+        t = id["type"] or return nil
+        m = /\A(ISBN|ISSN)\..*/i.match(t) or return t.upcase
+        m[1].upcase
+      end
+
+      def facade_scope_filter(ids)
+        ids.detect { |i| i["scope"] } or return ids
+        ids.group_by { |i| i["type"] }.flat_map do |type, group|
+          grouped = group.group_by { |i| i["scope"] }
+          if type == "IEEE" then grouped["trademark"] || grouped[nil] || []
+          else grouped[nil] || []
+          end
+        end
+      end
+
+      # 1.x accepted string- and symbol-keyed options alike (the old
+      # engine deep-symbolized via metanorma-utils); isodoc's bibrenderer
+      # and every flavor still pass string keys.
+      def deep_symbolize(value)
+        case value
+        # isodoc i18n hashes carry nil keys (an unlabeled punct slot)
+        when Hash then value.to_h { |k, v| [k&.to_sym, deep_symbolize(v)] }
+        when Array then value.map { |v| deep_symbolize(v) }
+        else value
+        end
+      end
+
+      # 1.x render/citation accepted a bibitem XML string; the Iso690
+      # engine consumes model instances.
+      def to_model(model)
+        return model unless model.is_a?(String)
+
+        klass = facade_bibitem_class
+        klass.from_xml(model)
+      end
+
+      def warn_general_config
+        return if General.config_warned
+
+        General.config_warned = true
+        warn "relaton-render: Relaton::Render::General is a compatibility " \
+             "facade over the v2 engine; the liquid config option is " \
+             "retired and ignored. Author a CitationStyle instance " \
+             "(relaton-models citation module) for custom rendering."
+      end
+
+      class << self
+        attr_accessor :config_warned
+      end
+    end
+  end
+end