vicary 0.2.6 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 537ad53f4299fd2a3cdfc7bceab94b4678bb3a7da01c2e73f5f0c1883d1dad2e
-  data.tar.gz: e51c1775be63158b1724739c94ddecb48b406c20a339d1b4b8a0acba1d753e5d
+  metadata.gz: 70cca39c8c91256c36ed5952eb12710da4125bd605f65dc4c1c71de8e0d77395
+  data.tar.gz: 879ab66dc00f074accad84a80887ac48a93fc9fe09968bc04f819bee1e0e20a8
 SHA512:
-  metadata.gz: d406808fe2dfc71599bb85516237fe3272876bd2302e3d794c12fb2d296fb2e4f65ea9906be0a8fe1f7deaaf1afab7cb3e6fa3c15dbe5f77f68c861b5f70ad39
-  data.tar.gz: 70e6fbef81ab903425190feda6683d3343604b980da6033f0ad7471816f4c2887eaf8408637dc1092e394e60162b877a1e5de6aa1a91516ba4c5d161bcd0b116
+  metadata.gz: ecf9bbecf10214d42fc5e495d6b3b161f7d1f1f1a080fb13631c379f06dd609ec182065685060d63f733890c468eacb0b854e371a2fec6b3fdb5bebdd9f45f03
+  data.tar.gz: 704e8aaf854c08b3128299dc425e543c00cf3789909dd98ccbb13509d9c80020d72d991a8e4c690424f9508ba8dfef6a5c9da1c9ca8f513a642407a33bfdf5b5

data/README.md

@@ -31,6 +31,13 @@ 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
+
+# Several fields, one pass, and one restore map per field. Numbering is the
+# JOINED document's, so one person keeps one placeholder across every field —
+# masking field by field renumbers and hands `{NAME_1}` to two people.
+masked, n, maps, batched = Vicary.redact_batch_with_report(fields, identity)
+# `batched == false` means the join did not round-trip and each field was
+# passed separately, so cross-field placeholder identity does NOT hold.
 ```
 
 An offset landing inside a placeholder resolves to the start of the span it

data/lib/vicary/redact.rb

@@ -32,6 +32,15 @@ module Vicary
 
   NAME_DETECTION_ENV_VAR = "VICARY_NAME_DETECTION"
 
+  # Separator for a batched pass, byte-identical to the Python reference's
+  # `BATCH_SEPARATOR`. Chosen to be something a writing-coach model will not
+  # emit and a PII policy will not touch: no words, no digits, no name-shaped or
+  # address-shaped substrings for an entity detector to bite on, and distinctive
+  # enough that a stray single character cannot fake it. A round-trip check runs
+  # anyway — see {redact_batch_with_report} — because a separator that "should"
+  # survive is exactly the kind of assumption that silently mis-aligns fields.
+  BATCH_SEPARATOR = "\n\u241E\u241E\u241E\n"
+
   IDENTITY_ALIASES = Set.new(%w[identity off none 0 false no]).freeze
   GAZETTEER_ALIASES = Set.new(%w[gazetteer on 1 true yes names]).freeze
   LOWERCASE_ALIASES = Set.new(%w[gazetteer-lowercase gazetteer_lowercase lowercase full max]).freeze
@@ -156,6 +165,90 @@ module Vicary
       [masked, n, minter.assigned]
     end
 
+    # Split a joined document's restore map into one map per part.
+    #
+    # By OCCURRENCE, not by re-deriving: the placeholders are unique strings
+    # over the joined document, so a part's map is exactly the entries whose
+    # placeholder survived into that part. Re-running detection per part would
+    # renumber, and renumbering is the one thing this must not do.
+    def split_joined_restore_map(restore_map, parts)
+      parts.map do |part|
+        restore_map.select { |placeholder, _original| part.include?(placeholder) }
+      end
+    end
+
+    # Redact several fields in ONE pass, and return the way back for each.
+    #
+    # Numbering is the JOINED document's, not each field's, so the same entity
+    # carries the same placeholder across fields — which is the property that
+    # lets a reader match a name in one field to the same name in another. A
+    # caller must therefore not assume a field's map starts at `{NAME_1}`.
+    #
+    # **Why a host wants this.** Masking field by field is irreversible in the
+    # way that matters: a caller holding only the masked strings cannot tell
+    # which placeholder belongs to which field, nor what any of them stood for,
+    # so it cannot put back the words its reader is already entitled to see.
+    # It also renumbers, so one entity gets a different token per field.
+    #
+    # **Where it can go wrong, and what happens then.** The join/split round
+    # trip is the risk: masking changes lengths, so offsets cannot be trusted,
+    # and the split relies on {BATCH_SEPARATOR} surviving the pass intact. If
+    # the masked document does not split back into exactly as many parts as
+    # went in, this **falls back to per-field passes and says so**
+    # (`batched == false`) rather than returning a mis-aligned list — one
+    # field's suggestion pasted into another's is a worse outcome than a slower
+    # call. Cross-field placeholder identity does not survive that fallback,
+    # which is stated rather than papered over: a caller correlating names
+    # across fields would otherwise be silently wrong on exactly those inputs.
+    #
+    # Returns `[masked_texts, n_masked, restore_maps, batched]`. `restore_maps`
+    # is positionally aligned with `texts` — one map per field, empty for a
+    # field that was empty or that nothing was masked in.
+    def redact_batch_with_report(texts, identity, options = {})
+      texts = texts.to_a
+      return [[], 0, [], true] if texts.empty?
+
+      empty_maps = texts.map { {} }
+      nonempty = texts.each_index.reject { |i| texts[i].nil? || texts[i].empty? }
+      return [texts.dup, 0, empty_maps, true] if nonempty.empty?
+
+      if nonempty.length == 1
+        only = nonempty.first
+        masked, n, map = redact_with_report(texts[only], identity, options)
+        out = texts.dup
+        out[only] = masked
+        maps = empty_maps.dup
+        maps[only] = map
+        return [out, n, maps, true]
+      end
+
+      joined = nonempty.map { |i| texts[i] }.join(BATCH_SEPARATOR)
+      masked, n, map = redact_with_report(joined, identity, options)
+      parts = masked.split(BATCH_SEPARATOR, -1)
+
+      if parts.length != nonempty.length
+        out = texts.dup
+        maps = empty_maps.dup
+        total = 0
+        nonempty.each do |i|
+          field_masked, field_n, field_map = redact_with_report(texts[i], identity, options)
+          out[i] = field_masked
+          maps[i] = field_map
+          total += field_n
+        end
+        return [out, total, maps, false]
+      end
+
+      out = texts.dup
+      maps = empty_maps.dup
+      split = split_joined_restore_map(map, parts)
+      nonempty.each_with_index do |i, k|
+        out[i] = parts[k]
+        maps[i] = split[k]
+      end
+      [out, n, maps, true]
+    end
+
     # Redact personal names and structured PII from `text`.
     #
     # @param text [String] the composition to redact.

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.6"
+  VERSION = "0.2.8"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vicary
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.8
 platform: ruby
 authors:
 - Blake Thomas
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-09 00:00:00.000000000 Z
+date: 2026-09-10 00:00:00.000000000 Z
 dependencies: []
 description: |
   Finds the names a student writes about — classmates, teachers, relatives — and