varar-core 0.6.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 840328108129bed1a48c4a3dc86fa1ca4d13937f0e313ccfa41fcaf0a98f89c3
-  data.tar.gz: 10d2916bda1d520f5521a99ddfd524305170b711fe476359746d83f5fa3f943b
+  metadata.gz: 4e14558a60af014ad7a1e7edfea61644a415408c5da1e384d6c34d4f191a2743
+  data.tar.gz: f91c617e21f8affcd745676fffba8be6b1ab484ec9c2c4e17b7173d6d07e1733
 SHA512:
-  metadata.gz: 579d8c9e3dbb19fb6b29165dd8ba075f9ec4d6cf75808648ffd0bbc49e9d5265c7864b784d5d79a29a1d66f530d4fc5b5b3739c434e60f4541e196421e5c402d
-  data.tar.gz: 42376d608744ce23fd97dc740c024d9432addf7b039a0ddcaa73eceab320c159ea06797e2729c13b4005d76c82a4fefde45af7cdebcaa8eacb1c5cf93a1499cf
+  metadata.gz: 4a89ff743d9d00027565cad5933ad28f2bc05af437a773feeac38f9c7c640ee25d548af761852343259afed64654205360e5e2983df9fbd82bc14a1167746013
+  data.tar.gz: 66c9b893012bd279f337db321fbae0262802bf579f627a7d7e0db37ff4183b3ec3112c413af5614481521d61543ca2e634b966d54260032615cf0c97057fd89f

data/lib/varar/core/ast.rb

@@ -40,8 +40,12 @@ module Varar
       def kind = 'thematic_break'
     end
 
-    Example = Data.define(:scope_stack, :span, :body)
+    # +preceded_by_delimiter+ is true when a heading or thematic break (`---`)
+    # sits between this candidate and the previous one (also true for the first
+    # candidate). The planner uses it to group adjacent matching candidates into
+    # one example. See ADR 0012.
+    Example = Data.define(:scope_stack, :span, :body, :preceded_by_delimiter)
 
-    VarDoc = Data.define(:path, :source, :examples, :orphan_attachments)
+    Doc = Data.define(:path, :source, :examples, :orphan_attachments)
   end
 end

data/lib/varar/core/canonical_json.rb

@@ -4,39 +4,39 @@ require 'json'
 
 module Varar
   module Core
-    # JSON serializers byte-for-byte compatible with JS `JSON.stringify(v, null, 2)`:
+    # Writes varar.lock.json the way JS `JSON.stringify(v, null, 2)` does:
     # 2-space indent, LF, trailing newline, non-ASCII raw, empty containers as
-    # {}/[]. `canonical_stringify` recursively sorts object keys (the goldens);
-    # `ordered_stringify` preserves insertion order (varar.lock.json).
+    # {}/[], keys in insertion order.
     #
-    # The container layout is hand-rolled because Ruby's JSON.pretty_generate
-    # renders empty arrays/objects as "[\n\n]". Scalar encoding is delegated to
-    # the stdlib, which matches JS (escapes " \ control chars, keeps non-ASCII raw).
+    # A committed, language-shared file, so the layout is hand-rolled rather
+    # than left to JSON.pretty_generate, which renders empty arrays/objects as
+    # "[\n\n]" — a Ruby run would otherwise churn the file against every other
+    # port's. Scalar encoding is delegated to the stdlib, which matches JS
+    # (escapes " \ control chars, keeps non-ASCII raw).
+    #
+    # Conformance goldens are NOT compared through here: a port has to agree
+    # with the goldens' CONTENT, and every spec parses them and compares deep
+    # equality.
     module CanonicalJson
       module_function
 
-      def canonical_stringify(value)
-        "#{encode(value, '', sort_keys: true)}\n"
-      end
-
       def ordered_stringify(value)
-        "#{encode(value, '', sort_keys: false)}\n"
+        "#{encode(value, '')}\n"
       end
 
-      def encode(value, indent, sort_keys:)
+      def encode(value, indent)
         case value
         when Hash
           return '{}' if value.empty?
 
-          keys = sort_keys ? value.keys.sort : value.keys
           inner = "#{indent}  "
-          items = keys.map { |key| "#{inner}#{key.to_s.to_json}: #{encode(value[key], inner, sort_keys: sort_keys)}" }
+          items = value.keys.map { |key| "#{inner}#{key.to_s.to_json}: #{encode(value[key], inner)}" }
           "{\n#{items.join(",\n")}\n#{indent}}"
         when Array
           return '[]' if value.empty?
 
           inner = "#{indent}  "
-          items = value.map { |element| "#{inner}#{encode(element, inner, sort_keys: sort_keys)}" }
+          items = value.map { |element| "#{inner}#{encode(element, inner)}" }
           "[\n#{items.join(",\n")}\n#{indent}]"
         else
           value.to_json

data/lib/varar/core/cell_diff.rb

@@ -5,7 +5,11 @@ module Varar
     # One checked column of one header-bound row: the cell text and its span.
     RowCheck = Data.define(:column, :value, :span)
 
-    # The verdict for one checked column after comparing against the table.
+    # The verdict for one comparison of one CELL — the atomic value a sensor
+    # checks against the document. A cell is a table cell, a header-bound row's
+    # cell, or a value captured from a paragraph by an expression parameter; all
+    # three land here. `column` labels the cell (a header cell's text, or `arg N`
+    # for an inline capture).
     # expected_value/actual_value/formatted are adapter-facing, never serialized.
     CellDiff = Data.define(:column, :span, :expected, :actual, :ok,
                            :expected_value, :actual_value, :formatted) do
@@ -18,7 +22,8 @@ module Varar
     # The step returned the wrong type/shape — an author mistake, not a value diff.
     class ReturnShapeError < StandardError; end
 
-    # Raised when a header-bound row's / a table's returned columns don't match.
+    # Raised when one or more compared CELLS differ — an inline capture, a table
+    # cell, or a header-bound row's cell.
     class CellMismatchError < StandardError
       attr_reader :cells
 

data/lib/varar/core/conformance.rb

@@ -93,12 +93,13 @@ module Varar
         {
           'scopeStack' => example.scope_stack,
           'span' => span_hash(example.span),
-          'body' => example.body.map { |b| block_hash(b) }
+          'body' => example.body.map { |b| block_hash(b) },
+          'precededByDelimiter' => example.preceded_by_delimiter
         }
       end
 
-      # Project a VarDoc to the wire dict for the var-doc artifact.
-      def to_var_doc_artifact(doc)
+      # Project a Doc to the wire dict for the var-doc artifact.
+      def to_doc_artifact(doc)
         {
           'path' => doc.path,
           'examples' => doc.examples.map { |ex| example_hash(ex) },
@@ -136,7 +137,7 @@ module Varar
 
       # Project an ExecutionPlan to the wire dict for the plan artifact.
       def to_plan_artifact(plan)
-        source = plan.var_doc.source
+        source = plan.doc.source
         {
           'examples' => plan.examples.map { |ex| planned_example_hash(ex, source) },
           'diagnostics' => plan.diagnostics.map do |d|
@@ -195,16 +196,6 @@ module Varar
               { 'column' => c.column, 'expected' => c.expected, 'actual' => c.actual, 'span' => span_hash(c.span) }
             end
           }
-        when DocStringMismatchError
-          {
-            'kind' => 'doc-string-mismatch', 'line' => line, 'anchor' => anchor,
-            'message' => error.message,
-            'diff' => {
-              'expected' => error.diff.expected,
-              'actual' => error.diff.actual,
-              'span' => span_hash(error.diff.span)
-            }
-          }
         when ReturnShapeError
           { 'kind' => 'return-shape', 'line' => line, 'anchor' => anchor, 'message' => error.message }
         when UnexpectedPassError
@@ -215,8 +206,8 @@ module Varar
       end
 
       # Run all examples and return the four-artifact bundle. Port of runConformance.
-      def run_conformance(var_doc, registry, create_context, parameter_types = [])
-        execution = Plan.plan(var_doc, registry)
+      def run_conformance(doc, registry, create_context, parameter_types = [])
+        execution = Plan.plan(doc, registry)
         observed = Hash.new { |h, k| h[k] = [] }
         observer = ->(o) { observed[o.example_index] << o }
         queue = Execute.collect_examples(execution, create_context: create_context, observer: observer)
@@ -253,7 +244,7 @@ module Varar
         end
 
         {
-          var_doc: to_var_doc_artifact(var_doc),
+          doc: to_doc_artifact(doc),
           registry: to_registry_artifact(registry, parameter_types),
           plan: to_plan_artifact(execution),
           trace: { 'examples' => trace_examples }

data/lib/varar/core/doc_string_diff.rb

@@ -4,32 +4,30 @@ require 'varar/core/cell_diff'
 
 module Varar
   module Core
-    # A doc-string content difference: fence body span, expected, actual.
-    DocStringDiff = Data.define(:span, :expected, :actual)
-
-    # Raised when a doc-string step's returned string differs from the content.
-    class DocStringMismatchError < StandardError
-      attr_reader :diff
-
-      def initialize(diff)
-        @diff = diff
-        super("doc string: expected #{diff.expected.inspect} but was #{diff.actual.inspect}")
-      end
-    end
+    # The column label a doc-string cell carries in a CellDiff, so its mismatch
+    # message reads `doc string: expected … but was …`.
+    DOC_STRING_COLUMN = 'doc string'
 
     # Pure comparison of a doc-string step's return against the fence body.
     # Port of doc-string-diff.ts.
     module DocStringDiffs
       module_function
 
-      # nil → no check; equal string → nil (pass); unequal → DocStringDiff;
+      # A doc string is ONE CELL, compared whole, so a difference is an ordinary
+      # CellDiff and the executor raises the same CellMismatchError as any other
+      # cell. `expected`/`actual` are quoted: a doc string routinely differs only
+      # in whitespace, and bare text would render a missing trailing newline as
+      # no difference at all.
+      #
+      # nil → no check; equal string → nil (pass); unequal → CellDiff;
       # non-string → ReturnShapeError.
       def compare_doc_string(returned, content, span)
         return nil if returned.nil?
         raise ReturnShapeError, "expected a doc string (string), got #{returned.class}" unless returned.is_a?(String)
         return nil if returned == content
 
-        DocStringDiff.new(span: span, expected: content, actual: returned)
+        CellDiff.new(column: DOC_STRING_COLUMN, span: span, expected: content.inspect,
+                     actual: returned.inspect, ok: false)
       end
     end
   end

data/lib/varar/core/drift.rb

@@ -10,14 +10,14 @@ module Varar
   module Core
     # One example-producing paragraph, as recorded in the baseline.
     BaselineExample = Data.define(:name, :line)
-    # The committed baseline for one spec file.
-    SpecBaseline = Data.define(:source_hash, :examples)
-    # The whole varar.lock.json: every spec keyed by its POSIX path.
-    VarLock = Data.define(:version, :specs)
+    # The committed baseline for one oath file.
+    OathBaseline = Data.define(:source_hash, :examples)
+    # The whole varar.lock.json: every oath keyed by its POSIX path.
+    LockFile = Data.define(:version, :oaths)
     # A paragraph the baseline says was an example and now matches no step.
     Drift = Data.define(:name, :line, :span)
 
-    # Spec drift detection: a paragraph the committed varar.lock.json baseline
+    # Oath drift detection: a paragraph the committed varar.lock.json baseline
     # recorded as an example that now matches no step. Pure, byte-identical to
     # the TS port so varar.lock.json is shared across languages. Port of drift.ts.
     #
@@ -31,12 +31,20 @@ module Varar
 
       module_function
 
-      def within?(inner, outer)
-        inner.start_offset >= outer.start_offset && inner.end_offset <= outer.end_offset
+      # Do the two spans overlap at all (offset ranges intersect)? A candidate
+      # paragraph relates to its planned example either way round: a header-bound
+      # row sits inside its binding paragraph, while a merged example's span
+      # covers each candidate it absorbed (ADR 0012). Overlap catches both.
+      def overlaps?(span_a, span_b)
+        span_a.start_offset < span_b.end_offset && span_b.start_offset < span_a.end_offset
       end
 
+      # A candidate is "live" (still an example) if it overlaps at least one
+      # planned example. A now-prose paragraph — one whose step def was renamed
+      # or deleted — overlaps none (it became a delimiter, splitting any example
+      # it was part of), so drift catches it.
       def live?(candidate_span, plan)
-        plan.examples.any? { |pe| within?(pe.span, candidate_span) }
+        plan.examples.any? { |pe| overlaps?(pe.span, candidate_span) }
       end
 
       # Lower-cased word tokens (letters/digits) — the unit of similarity.
@@ -54,25 +62,25 @@ module Varar
       end
 
       # The current example-producing paragraphs, in document order.
-      def live_examples(var_doc, plan)
-        var_doc.examples.filter_map do |candidate|
+      def live_examples(doc, plan)
+        doc.examples.filter_map do |candidate|
           next unless live?(candidate.span, plan)
 
           BaselineExample.new(name: Plan.derive_example_name(candidate.body), line: candidate.span.start_line)
         end
       end
 
-      def derive_spec_baseline(source, var_doc, plan)
-        SpecBaseline.new(source_hash: Hash32.hash_source(source), examples: live_examples(var_doc, plan))
+      def derive_oath_baseline(source, doc, plan)
+        OathBaseline.new(source_hash: Hash32.hash_source(source), examples: live_examples(doc, plan))
       end
 
       # Paragraphs the baseline recorded as examples that now match zero steps.
       # Each re-identified by the most word-similar current paragraph at/above
       # the threshold (exact name scores 1; ties break toward the nearest line).
-      def detect_drift(baseline, var_doc, plan)
+      def detect_drift(baseline, doc, plan)
         return [] if baseline.nil?
 
-        candidates = var_doc.examples
+        candidates = doc.examples
         tokens = candidates.map { |c| tokenize(Plan.derive_example_name(c.body)) }
         live = candidates.map { |c| live?(c.span, plan) }
 
@@ -103,43 +111,76 @@ module Varar
         drifts.map { |d| Diagnostics.drift_detected(d.name, d.span) }
       end
 
-      # One spec's baseline reconciliation against a BaselineStore. In update
+      # One oath's baseline reconciliation against a BaselineStore. In update
       # mode, accept all drift (re-record, report nothing); otherwise detect
       # drift and rewrite the baseline only on a clean run, so an unacknowledged
       # drift keeps its old entry (and stays red).
-      def reconcile_drift(store, spec_path, source, var_doc, plan, update: false)
+      def reconcile_drift(store, oath_path, source, doc, plan, update: false)
         text = store.read
-        lock = text ? parse_var_lock(text) : nil
-        baseline = lock ? lock.specs[spec_path] : nil
-        drifts = update ? [] : detect_drift(baseline, var_doc, plan)
+        lock = text ? parse_lock_file(text) : nil
+        baseline = lock ? lock.oaths[oath_path] : nil
+        drifts = update ? [] : detect_drift(baseline, doc, plan)
         if update || drifts.empty?
-          specs = lock ? lock.specs.dup : {}
-          specs[spec_path] = derive_spec_baseline(source, var_doc, plan)
-          store.write(stringify_var_lock(VarLock.new(version: 1, specs: specs)))
+          oaths = lock ? lock.oaths.dup : {}
+          oaths[oath_path] = derive_oath_baseline(source, doc, plan)
+          store.write(stringify_lock_file(LockFile.new(version: 2, oaths: oaths)))
         end
         drifts
       end
 
-      def parse_var_lock(text)
+      # Drop every baseline whose oath path is not in +keep_paths+ — the entries
+      # left behind when an oath is deleted or moved. Pure counterpart of
+      # parse_lock_file / stringify_lock_file; the caller decides what "still
+      # exists" means.
+      def prune_lock_file(lock, keep_paths)
+        keep = keep_paths.to_a
+        LockFile.new(version: 2, oaths: lock.oaths.slice(*keep))
+      end
+
+      # The whole-lock counterpart of reconcile_drift, run ONCE per run rather
+      # than per oath: reconciliation cannot see paths that no longer exist, so
+      # without this the lock silently accumulates dead entries and stops being
+      # a faithful inventory of the oath set (#70).
+      #
+      # +keep_paths+ MUST be everything the +docs+ globs currently match — never
+      # the set the run happened to execute. Runs are routinely filtered, and
+      # pruning against a filtered set would delete live baselines.
+      #
+      # Removal is still not *gated*: a deleted oath is a different signal from
+      # drift and stays ungated (ADR 0002). This only stops preserving dead
+      # state, and only under +update+. Returns the paths removed (or, without
+      # +update+, the ones that would be).
+      def prune_baselines(store, keep_paths, update: false)
+        text = store.read
+        lock = text ? parse_lock_file(text) : nil
+        return [] unless lock
+
+        keep = keep_paths.to_a
+        stale = lock.oaths.keys.reject { |path| keep.include?(path) }
+        store.write(stringify_lock_file(prune_lock_file(lock, keep))) if update && !stale.empty?
+        stale
+      end
+
+      def parse_lock_file(text)
         parsed = JSON.parse(text)
-        return nil unless parsed.is_a?(::Hash) && parsed['version'] == 1
+        return nil unless parsed.is_a?(::Hash) && parsed['version'] == 2
 
-        specs_raw = parsed['specs']
-        return nil unless specs_raw.is_a?(::Hash)
+        oaths_raw = parsed['oaths']
+        return nil unless oaths_raw.is_a?(::Hash)
 
-        specs = {}
-        specs_raw.each do |path, value|
-          baseline = parse_spec_baseline(value)
+        oaths = {}
+        oaths_raw.each do |path, value|
+          baseline = parse_oath_baseline(value)
           return nil if baseline.nil?
 
-          specs[path] = baseline
+          oaths[path] = baseline
         end
-        VarLock.new(version: 1, specs: specs)
+        LockFile.new(version: 2, oaths: oaths)
       rescue JSON::ParserError, TypeError
         nil
       end
 
-      def parse_spec_baseline(value)
+      def parse_oath_baseline(value)
         return nil unless value.is_a?(::Hash)
 
         source_hash = value['sourceHash']
@@ -153,7 +194,7 @@ module Varar
 
           examples << parsed
         end
-        SpecBaseline.new(source_hash: source_hash, examples: examples)
+        OathBaseline.new(source_hash: source_hash, examples: examples)
       end
 
       def parse_baseline_example(value)
@@ -166,19 +207,19 @@ module Varar
         BaselineExample.new(name: name, line: line)
       end
 
-      # Serialize varar.lock.json deterministically: spec paths sorted, examples
-      # in document order, insertion-order keys otherwise (version, specs;
+      # Serialize varar.lock.json deterministically: oath paths sorted, examples
+      # in document order, insertion-order keys otherwise (version, oaths;
       # sourceHash, examples; name, line) — NOT canonical JSON's key sort.
-      def stringify_var_lock(lock)
-        specs = {}
-        lock.specs.keys.sort.each do |path|
-          baseline = lock.specs[path]
-          specs[path] = {
+      def stringify_lock_file(lock)
+        oaths = {}
+        lock.oaths.keys.sort.each do |path|
+          baseline = lock.oaths[path]
+          oaths[path] = {
             'sourceHash' => baseline.source_hash,
             'examples' => baseline.examples.map { |e| { 'name' => e.name, 'line' => e.line } }
           }
         end
-        CanonicalJson.ordered_stringify({ 'version' => 1, 'specs' => specs })
+        CanonicalJson.ordered_stringify({ 'version' => 2, 'oaths' => oaths })
       end
     end
   end

data/lib/varar/core/execute.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'varar/core/span'
-require 'varar/core/deep_freeze'
 require 'varar/core/cell_diff'
 require 'varar/core/doc_string_diff'
 require 'varar/core/param_diff'
@@ -43,17 +42,17 @@ module Varar
       def execute_plan(plan, sink:, create_context:, observer: nil, reporter: nil)
         plan.diagnostics.each { |d| reporter.call(d) } if reporter
         create_ctx = create_context || ->(_file) { {} }
-        var_path = plan.var_doc.path
+        oath_path = plan.doc.path
 
         plan.examples.each_with_index do |ex, example_index|
           seen_lines = {}
           ex.steps.each { |s| seen_lines[s.match_span.start_line] = true }
           info = { lines: seen_lines.keys }
-          sink.call(ex.name, build_run(plan, ex, example_index, create_ctx, observer, var_path), info)
+          sink.call(ex.name, build_run(plan, ex, example_index, create_ctx, observer, oath_path), info)
         end
       end
 
-      def build_run(plan, ex, example_index, create_ctx, observer, var_path)
+      def build_run(plan, ex, example_index, create_ctx, observer, oath_path)
         lambda do
           state_by_file = {}
           last_return = nil
@@ -61,7 +60,7 @@ module Varar
 
           ex.steps.each_with_index do |step, i|
             file = step.step_def.expression_source_file
-            state_by_file[file] = DeepFreeze.deep_freeze(create_ctx.call(file)) unless state_by_file.key?(file)
+            state_by_file[file] = create_ctx.call(file) unless state_by_file.key?(file)
             state = state_by_file[file]
 
             extra = []
@@ -76,9 +75,12 @@ module Varar
               last_return = returned
               case step.step_def.kind
               when 'stimulus'
-                # Full replacement: the returned Hash IS the next state (deep-frozen).
-                # There is no merge — a return with fewer keys shrinks the state.
-                # nil is a no-op; any other type is a contract violation.
+                # Full replacement: the returned Hash IS the next state. There is
+                # no merge — a return with fewer keys shrinks the state. nil is a
+                # no-op; any other type is a contract violation.
+                #
+                # The state is the author's own value, handed back untouched: we
+                # do not freeze it. Whether it is immutable is the author's call.
                 unless returned.nil?
                   unless returned.is_a?(Hash)
                     raise ReturnShapeError,
@@ -86,16 +88,16 @@ module Varar
                           'or nothing to leave it unchanged'
                   end
 
-                  state = DeepFreeze.deep_freeze(returned)
+                  state = returned
                   state_by_file[file] = state
                 end
               when 'sensor'
-                compare_sensor_return(plan, ex, step, returned, extra) if ex.row_checks.nil? && !returned.nil?
+                compare_sensor_return(plan, ex, step, returned, extra) if ex.row_checks.nil?
               else
                 raise ReturnShapeError, "unknown step kind: #{step.step_def.kind}"
               end
             rescue StandardError => e
-              augmented = augment_stack(e, step, var_path)
+              augmented = augment_stack(e, step, oath_path)
               observer&.call(observation(ex, example_index, i + 1, file, 'fail', augmented))
               thrown = augmented
               break
@@ -106,10 +108,16 @@ module Varar
 
           # Header-bound row checks (after all steps).
           if thrown.nil? && ex.row_checks && !ex.row_checks.empty?
+            # Like a slotted sensor, a header-bound row step must answer the row
+            # it is bound to: no return means nothing was compared.
+            row_error = if last_return.nil?
+                          ReturnShapeError.new('a header-bound row step must return a row object ' \
+                                               'with one value per bound cell, got nothing')
+                        end
             bad = CellDiffs.compare_row(last_return, ex.row_checks).reject(&:ok)
-            unless bad.empty?
+            if row_error || !bad.empty?
               last_step = ex.steps.last
-              augmented = augment_stack(CellMismatchError.new(bad), last_step, var_path)
+              augmented = augment_stack(row_error || CellMismatchError.new(bad), last_step, oath_path)
               observer&.call(observation(ex, example_index, ex.steps.length,
                                          last_step.step_def.expression_source_file, 'fail', augmented))
               thrown = augmented
@@ -121,7 +129,7 @@ module Varar
             if thrown.nil?
               error = UnexpectedPassError.new
               last = ex.steps.last
-              raise(last ? augment_stack(error, last, var_path) : error)
+              raise(last ? augment_stack(error, last, oath_path) : error)
             end
             raise thrown if ex.expected_error_message && !thrown.message.include?(ex.expected_error_message)
 
@@ -133,20 +141,30 @@ module Varar
       end
 
       # Sensor slot contract: zero slots + a return is a mistake; one slot IS
-      # the return; two+ is a positional array. Raises the appropriate diff error.
+      # the return; two+ is a positional array. With one or more slots the
+      # return is REQUIRED — returning nothing used to skip the comparison
+      # silently, so a typo turned an assertion into a no-op. Raises the
+      # appropriate diff error.
       def compare_sensor_return(plan, _ex, step, returned, extra)
         slot_count = step.args.length + extra.length
         if slot_count.zero?
+          return if returned.nil?
+
           raise ReturnShapeError, 'this sensor has no parameters, data table or doc string — ' \
                                   'nothing to compare a return value against (raise to fail, return nothing to pass)'
         end
 
+        if returned.nil?
+          raise ReturnShapeError,
+                "a sensor with #{slot_count} slot(s) must return one value per slot, got nothing"
+        end
+
         if slot_count == 1
           slots = [returned]
         else
           unless returned.is_a?(Array)
             raise ReturnShapeError,
-                  "a sensor with #{slot_count} parameters must return a list of " \
+                  "a sensor with #{slot_count} slots must return a list of " \
                   "#{slot_count} values, got #{returned.class}"
           end
           unless returned.length == slot_count
@@ -159,7 +177,7 @@ module Varar
 
         inline_returned = slots[0...step.args.length]
         source_texts = step.param_spans.map do |s|
-          Offsets.utf16_slice(plan.var_doc.source, s.start_offset, s.end_offset)
+          Offsets.utf16_slice(plan.doc.source, s.start_offset, s.end_offset)
         end
         param_diffs = ParamDiff.compare_params(inline_returned, step.args, step.param_spans, source_texts,
                                                step.formats).reject(&:ok)
@@ -171,7 +189,7 @@ module Varar
         elsif step.doc_string
           diff = DocStringDiffs.compare_doc_string(slots[step.args.length], step.doc_string.content,
                                                    step.doc_string.span)
-          raise DocStringMismatchError, diff unless diff.nil?
+          raise CellMismatchError, [diff] unless diff.nil?
         end
       end
 
@@ -181,9 +199,12 @@ module Varar
       end
 
       # In TS this injects a synthetic `at <text> (path:line:col)` frame for
-      # editor navigation; the conformance trace derives the anchor separately
-      # via failure_anchor, so here it is a no-op that returns the error.
-      def augment_stack(error, _step, _var_path)
+      # editor navigation. Ruby has no writable stack text to splice into, so
+      # it records the anchor structurally instead — the failing step's span
+      # (or the first mismatched cell's), which Failures.to_failure reads back
+      # so a renderer underlines the step and not its whole line.
+      def augment_stack(error, step, _var_path)
+        FailureAnchor.attach_anchor(error, FailureAnchor.failure_anchor(error, step.match_span))
         error
       end
     end

data/lib/varar/core/failure.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'varar/core/cell_diff'
+require 'varar/core/failure_anchor'
+require 'varar/core/result'
+
+module Varar
+  module Core
+    # Converts a caught step error into the structured ExampleFailure payload —
+    # port of failure.ts / failure.py / Failure.java / failure.rs. Shared by
+    # every producer so failures are byte-identical across ports.
+    #
+    # Where TS scrapes an injected `<path>:line:col` stack frame for the failing
+    # line, Ruby reads it off the anchor the executor attached (the Rust port
+    # does the same): a Ruby backtrace has no synthetic frame to scrape, and the
+    # anchor already carries the line the frame would have named.
+    module Failures
+      module_function
+
+      # A caught step error → the ExampleResult.failure payload.
+      #
+      # `fallback_line` is used when the error carries no anchor, i.e. it never
+      # passed through a step.
+      def to_failure(error, _oath_path, fallback_line)
+        anchor = FailureAnchor.attached_anchor(error)
+
+        ExampleFailure.new(
+          line: anchor ? anchor.start_line : fallback_line,
+          message: error.message,
+          stack: render_stack(error),
+          cells: failing_cells(error),
+          anchor: anchor && AnchorRange.new(from: anchor.start_offset, to: anchor.end_offset)
+        )
+      end
+
+      # Every mismatched cell — table, header-bound row, inline capture or doc
+      # string. nil (not an empty array) when the error is not a mismatch, so
+      # the key stays absent in the serialized payload.
+      def failing_cells(error)
+        return nil unless error.is_a?(CellMismatchError)
+
+        failing = error.cells.reject(&:ok).map do |c|
+          CellFailure.new(from: c.span.start_offset, to: c.span.end_offset, actual: c.actual)
+        end
+        failing.empty? ? nil : failing
+      end
+
+      # Display-only: the message plus Ruby's own backtrace. Runtime-shaped by
+      # design (ADR 0014) — no consumer parses it.
+      def render_stack(error)
+        ([error.message] + Array(error.backtrace)).join("\n")
+      end
+    end
+  end
+end