vicary 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86411ff6192dfe36ba02d8159d4000bc55814d5eb8dd782713f373199d0bef98
-  data.tar.gz: 85ad752a1663010614adec4820efb015e0ee9b63ad74bf048f8869760f438246
+  metadata.gz: 537ad53f4299fd2a3cdfc7bceab94b4678bb3a7da01c2e73f5f0c1883d1dad2e
+  data.tar.gz: e51c1775be63158b1724739c94ddecb48b406c20a339d1b4b8a0acba1d753e5d
 SHA512:
-  metadata.gz: c2197ab3c0b5759a94bd8027e8c4096c886b3186e37be9cd06e562710db94677450cce228c3a9c106156a43857591a1c0c18fd3dd8eddba617c644fa6f3bee6c
-  data.tar.gz: c1a2612a43896411f0462732d37641fb864fb84dc48eef2c81d96e182295bb69c0b4ad8be6c1fa04bc53368ba8a906669bd7e8e58735abc5fd034b7e7821f627
+  metadata.gz: d406808fe2dfc71599bb85516237fe3272876bd2302e3d794c12fb2d296fb2e4f65ea9906be0a8fe1f7deaaf1afab7cb3e6fa3c15dbe5f77f68c861b5f70ad39
+  data.tar.gz: 70e6fbef81ab903425190feda6683d3343604b980da6033f0ad7471816f4c2887eaf8408637dc1092e394e60162b877a1e5de6aa1a91516ba4c5d161bcd0b116

data/README.md

@@ -23,8 +23,21 @@ Vicary.redact("My cousin Terrence Okonkwo came over that summer.", identity)
 
 masked, n, restore_map = Vicary.redact_with_report(essay, identity)
 Vicary.restore(masked, restore_map) == essay   # => true
+
+# Where each replacement came from, for a host that draws on the essay: a
+# placeholder is not the width of the name it replaced, so an offset measured
+# against `masked` is displaced against the composition the student holds.
+spans = Vicary::Spans.derive(masked, restore_map)
+Vicary::Spans.to_original(offset, spans)   # masked coordinates -> the student's
+Vicary::Spans.to_redacted(offset, spans)   # and back
+Vicary::Spans.original(masked, restore_map) == essay   # => true
 ```
 
+An offset landing inside a placeholder resolves to the start of the span it
+replaced. A map that is absent, or that covers only some of the placeholders in
+the text, yields **no** spans and translates as the identity — a caller can
+handle "no spans" and cannot detect a wrong offset.
+
 ## Checking it
 
 Three layers, because each catches what the one above it cannot.
@@ -33,7 +46,7 @@ Three layers, because each catches what the one above it cannot.
 |---|---|
 | `rake conformance` | the scoreboard against the 54 frames — the final bar, and a coarse first one |
 | `rake gates` | the nine gates, all nine measured from what the repository ships |
-| `rake test` | the unit suites, including `primitives_test.rb`: forty-odd primitives over the shared corpus, which says *which brick* is crooked |
+| `rake test` | the unit suites, including `primitives_test.rb` (forty-odd primitives over the shared corpus, which says *which brick* is crooked) and `spans_test.rb` (the offset arithmetic over the shared `spans.json`) |
 | `rake parity` | gazetteer verdicts, name by name, against the Python reference |
 | `rake redaction_parity` | masked bytes against the Python reference, on prose no fixture contains |
 

data/lib/vicary/conformance.rb

@@ -155,6 +155,32 @@ module Vicary
         raw
       end
 
+      # The offset-translation spec — {Vicary::Spans}' cases and their answers.
+      #
+      # A third layer, checking a third thing. `frames.json` says what is masked
+      # and `primitives.json` says which rule decided it; neither constrains
+      # WHERE a replacement came from, and a port can reproduce every byte of
+      # both while being unable to tell a host where to draw a highlight on the
+      # student's own essay.
+      #
+      # Absent is an error rather than an empty document, for the same reason
+      # `just _conformance-check` refuses to run without a spec: a port that
+      # finds no cases and reports success has checked its arithmetic against
+      # nothing.
+      def load_spans(dir = nil)
+        dir = Pathname.new(dir || directory)
+        path = dir.join("spans.json")
+        unless path.file?
+          raise SpecError,
+                "no spans.json at #{path}. The ports would check their offset " \
+                "translation against nothing."
+        end
+
+        raw = JSON.parse(path.read)
+        require_version(raw["document_version"], "spans.json")
+        raw
+      end
+
       # Score an implementation against every frame.
       #
       # The block receives (sentence, identity) — the same input every Python arm

data/lib/vicary/spans.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Vicary
+  # One replacement, located in both the original and the masked text.
+  #
+  # `orig_start...orig_end` is what was removed; `new_start...new_end` is the
+  # placeholder standing in its place. The two widths differ — that difference
+  # is the whole reason this type exists.
+  RedactionSpan = Struct.new(:orig_start, :orig_end, :new_start, :new_end) do
+    # How much this replacement moved everything after it.
+    def delta
+      (new_end - new_start) - (orig_end - orig_start)
+    end
+
+    def to_h
+      { orig_start: orig_start, orig_end: orig_end,
+        new_start: new_start, new_end: new_end }
+    end
+  end
+
+  # Offset translation between the masked text and the composition the student
+  # holds — the Ruby port of `python/src/vicary/redaction.py`'s span layer.
+  #
+  # Why a host needs it. `redact_with_report` hands back masked bytes and a
+  # restore map, and between them they still say nothing about WHERE anything
+  # sits. A host rendering a highlight works in the student's coordinates, the
+  # detector produced its text in masked coordinates, and `{NAME_1}` is not the
+  # width of the name it replaced: every offset after the first replacement is
+  # displaced by the cumulative delta. Measured on a 56-paper corpus, redaction
+  # fired on 43 essays and not one recorded offset pair on those 43 landed on
+  # the original text.
+  #
+  # **Nothing in the masker records anything for this to work.** That is the
+  # point, and it is why this is a pure module rather than instrumentation:
+  # {Vicary::Candidates.mask_candidates} is many passes over a string each pass
+  # mutates, so a span recorded inside one pass is in that pass's intermediate
+  # coordinates and would have to be composed forward through every later one.
+  # It is unnecessary — the finished text still *contains* every placeholder, so
+  # each replacement's new span is where its placeholder sits, and the restore
+  # map gives the original, so its width is a `length`.
+  #
+  # Checked against `conformance/spans.json`, generated from the Python
+  # reference, by `test/spans_test.rb`. The arithmetic is shared with the other
+  # two ports and pinned there rather than described here.
+  module Spans
+    # A placeholder token as it appears in masked text, e.g. `{NAME_1}`.
+    PLACEHOLDER = /\{[A-Z_]+(?:_\d+)?\}/.freeze
+
+    class << self
+      # The span map, derived from the masked text and the restore map alone.
+      #
+      # Replacement preserves order, so one left-to-right walk accumulating the
+      # running delta recovers the original offsets exactly.
+      #
+      # Returns `[]` when `restore_map` is empty or does not cover a placeholder
+      # present in the text. A partial map is refused rather than answered for
+      # the half it can place, because a translation that is right for some
+      # offsets and silently wrong for others is worse than one that declines:
+      # the caller can handle "no map" and cannot detect "wrong offset".
+      def derive(masked, restore_map)
+        return [] if restore_map.nil? || restore_map.empty?
+
+        spans = []
+        delta = 0
+        masked.to_s.enum_for(:scan, PLACEHOLDER).each do
+          match = Regexp.last_match
+          original = restore_map[match[0]]
+          return [] if original.nil?
+
+          orig_start = match.begin(0) - delta
+          span = RedactionSpan.new(orig_start, orig_start + original.length,
+                                   match.begin(0), match.end(0))
+          spans << span
+          delta += span.delta
+        end
+        spans
+      end
+
+      # A redacted-text offset in original coordinates.
+      #
+      # An offset landing INSIDE a placeholder maps to the start of the span it
+      # replaced: the placeholder's interior has no counterpart in the original,
+      # so any position within it is the same position in original terms.
+      def to_original(offset, spans)
+        result = offset
+        spans.each do |span|
+          break if offset < span.new_start
+          return span.orig_start if offset < span.new_end
+
+          result = span.orig_end + (offset - span.new_end)
+        end
+        result
+      end
+
+      # An original-text offset in redacted coordinates.
+      #
+      # An offset inside a replaced span maps to the start of its placeholder,
+      # for the mirror-image reason.
+      def to_redacted(offset, spans)
+        result = offset
+        spans.each do |span|
+          break if offset < span.orig_start
+          return span.new_start if offset < span.orig_end
+
+          result = span.new_end + (offset - span.orig_end)
+        end
+        result
+      end
+
+      # Reconstruct the pre-redaction text from the masked bytes and the map.
+      #
+      # Exact where a span map exists, and the masked text unchanged where one
+      # does not — which is the honest answer rather than a partial restoration,
+      # for the reason {derive} declines.
+      def original(masked, restore_map)
+        masked = masked.to_s
+        out = +""
+        prev = 0
+        derive(masked, restore_map).each do |span|
+          out << masked[prev...span.new_start]
+          out << restore_map[masked[span.new_start...span.new_end]]
+          prev = span.new_end
+        end
+        out << masked[prev..].to_s
+        out
+      end
+    end
+  end
+end

data/lib/vicary/version.rb

@@ -6,5 +6,5 @@ module Vicary
   # Shared across all three front doors on purpose: one detector, one number. A
   # gem 0.3.0 that corresponds to nothing on PyPI cannot be reasoned about, and
   # the parity claim is between *versions*, not between package names.
-  VERSION = "0.2.5"
+  VERSION = "0.2.6"
 end

data/lib/vicary.rb

@@ -43,3 +43,4 @@ require_relative "vicary/census"
 require_relative "vicary/corpus"
 require_relative "vicary/latency_baseline"
 require_relative "vicary/redact"
+require_relative "vicary/spans"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vicary
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.6
 platform: ruby
 authors:
 - Blake Thomas
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-13 00:00:00.000000000 Z
+date: 2026-09-09 00:00:00.000000000 Z
 dependencies: []
 description: |
   Finds the names a student writes about — classmates, teachers, relatives — and
@@ -38,6 +38,7 @@ files:
 - lib/vicary/lexicon.rb
 - lib/vicary/minter.rb
 - lib/vicary/redact.rb
+- lib/vicary/spans.rb
 - lib/vicary/structured.rb
 - lib/vicary/version.rb
 homepage: https://github.com/bwthomas/vicary