parsanol 1.3.129 → 1.3.131

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 623a4617740df84b93eae20fe1b76ed37e12dbffd6fac0061c73d577896e4b18
-  data.tar.gz: 2334da3b6da14bfcf5b72fdfbe1a4f2fef45da0863b625461cea5460f66841f4
+  metadata.gz: fda87ae372d092b330079308377f9ed93a5cf03d79a42a9e3e24a82fb82775d3
+  data.tar.gz: b4e249f4d827cb56d027d9f0dd05d333870e862a11a71e9de6ada0cc695a2d47
 SHA512:
-  metadata.gz: cb9eb9b290b8f38a3620fdd881980d167d8cdd48f6b070300b543750db0cb3f99bf9bbaa356c19c0727dfdd9ca11c6fa823d7f938ddfe20764582aa06cf6994c
-  data.tar.gz: 5685083eb1045fd5fa3c7ed8d54e5530d941ac164b3d519f7a4d238bd79a53ccccc41fa526aa897376df8c23aa906ecbcd85030ad494d8388c169378f90c482b
+  metadata.gz: ac94ae5b14c7fe2c7300d45cf230c2a5210199d7645432a343eb730061644b00014209c678be05b4416717e7bd97e8b5c04dcb906f1c8289016a7e283c49ad57
+  data.tar.gz: 83f77073bfbf15550f82b14663a31b2565e9d434444bc46b986cc29d4d225e19dd3e1cf8eba14a16d2c330a0a412cd0cb6911149781ac827072c756148fb2c55

data/Cargo.lock

@@ -307,9 +307,9 @@ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
 [[package]]
 name = "parsanol"
-version = "0.20.0"
+version = "0.20.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fa25545d2493d7c0be6e70054f9a8aef360e5ff6046dce5ceae664065e1d5039"
+checksum = "c452ad0ffc59ff11bcdb6c38e24cb0eb4613f0875d912caf10e8d2c58237934c"
 dependencies = [
  "ahash",
  "getrandom 0.3.4",
@@ -326,9 +326,9 @@ dependencies = [
 
 [[package]]
 name = "parsanol-derive"
-version = "0.20.0"
+version = "0.20.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "54c23675b697407e9d2c495c269537407548641b782c6cd79c7c93e079c91988"
+checksum = "c012f01d67b456b25cb64fdc050f56eee2037c30780b2e8143b61d2a08cf5637"
 dependencies = [
  "proc-macro2",
  "quote",

data/lib/parsanol/parg/artifact.rb

@@ -15,13 +15,15 @@ module Parsanol
       attr_reader :envelope, :path, :tables_dir, :imports_dir
 
       def self.load(path, tables_dir: nil, imports_dir: nil)
-        envelope = JSON.parse(PARG.read_utf8(path))
+        text = PARG.read_utf8(path)
+        envelope = JSON.parse(text)
         new(envelope, path, tables_dir || File.dirname(path),
-            imports_dir: imports_dir)
+            imports_dir: imports_dir, raw_text: text)
       end
 
       def self.from_json(text, tables_dir: nil, imports_dir: nil)
-        new(JSON.parse(text), nil, tables_dir, imports_dir: imports_dir)
+        new(JSON.parse(text), nil, tables_dir, imports_dir: imports_dir,
+                                               raw_text: text)
       end
 
       SUPPORTED_SHAPE = "parsanol-tree/v2"
@@ -37,7 +39,7 @@ module Parsanol
         2 => 2, "2" => 2, "v2" => 2
       }.freeze
 
-      def initialize(envelope, path, tables_dir, imports_dir: nil)
+      def initialize(envelope, path, tables_dir, imports_dir: nil, raw_text: nil)
         unless envelope["shape"] == SUPPORTED_SHAPE
           raise ArtifactError,
                 "unsupported artifact shape #{envelope['shape'].inspect} " \
@@ -63,6 +65,7 @@ module Parsanol
         # sources when the pure-Ruby path recompiles the embedded source;
         # in-memory artifacts (path nil) pass the directory explicitly.
         @imports_dir = imports_dir
+        @raw_text = raw_text
         verify_checksum!
         @compiler = nil
       end
@@ -95,6 +98,18 @@ module Parsanol
         source_hash == Digest::SHA256.hexdigest(source_text.to_s)
       end
 
+      # The declared per-target binding artifact for this parse artifact
+      # (parsanol-ruby#432): the entry binding records extracted into
+      # their own checksummed artifact, pinned to this grammar by source
+      # hash. Targets: ruby, rs, ts, python.
+      def bindings_artifact(target)
+        Bindings::Artifact.emit(envelope, target)
+      end
+
+      def bindings_artifact_json(target)
+        Bindings::Artifact.emit_json(envelope, target)
+      end
+
       def entries = envelope["entries"].keys
 
       def entry(name)
@@ -643,7 +658,16 @@ module Parsanol
         @compiled[rule] ||= compiler.atom_for(rule)
       end
 
+      # Two tiers. FAST: when the bake sealed the file, a zero-hole
+      # sha256 over the raw bytes proves byte integrity without parsing
+      # semantics — O(bytes), no canonicalization. DEEP: the canonical
+      # checksum (cross-engine content equality), which also covers
+      # artifacts baked before byte_checksum existed. A sealed artifact
+      # loaded with its raw text verifies BOTH; a bare envelope (direct
+      # construction) verifies canonical only.
       def verify_checksum!
+        verify_byte_checksum! if envelope["byte_checksum"]
+
         stored = envelope["checksum"]
         computed = Compiler.checksum(envelope)
         return if stored == computed
@@ -652,6 +676,26 @@ module Parsanol
               "artifact checksum mismatch: stored #{stored.inspect}, " \
               "computed #{computed.inspect}"
       end
+
+      # The bake computed the digest over the file bytes with the
+      # digest's own 64-hex region zeroed (Compiler.seal_json). Any
+      # flipped bit anywhere else in the file mismatches — corrupted
+      # distribution, wrong file, hand-edited payload: all rejected
+      # before any parse work.
+      def verify_byte_checksum!
+        stored = envelope["byte_checksum"]
+        return if stored.nil? || @raw_text.nil?
+
+        placeholder = Compiler::BYTE_CHECKSUM_PLACEHOLDER
+        zeroed = @raw_text.sub(stored.to_s, placeholder)
+        computed = "sha256:#{Digest::SHA256.hexdigest(zeroed)}"
+        return if stored == computed
+
+        raise ArtifactError,
+              "artifact byte checksum mismatch: stored #{stored.inspect}, " \
+              "computed #{computed.inspect} — the file bytes are not the " \
+              "sealed bake output"
+      end
     end
   end
 end

data/lib/parsanol/parg/bindings/artifact.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Parsanol
+  module PARG
+    module Bindings
+      # The declared per-target binding artifact (parsanol-ruby#432): from
+      # one compiled grammar the toolchain emits one checksummed bindings
+      # artifact per target, each carrying the entry binding records and
+      # pinned to its grammar by source hash. Declared and diffable, not
+      # baked: consumers pin and verify what they load.
+      #
+      # Boundary: the records carry AST construction only — the
+      # production-to-binding mapping. Semantics live in the model layer
+      # (LML), never here. Execution resources (preprocess steps and their
+      # tables) resolve from the PAIRED parse artifact, which is why
+      # #pair_with! is mandatory before #apply.
+      class Artifact
+        KIND = "parg-bindings"
+        TARGETS = %w[ruby rs ts python].freeze
+        SUPPORTED_BINDING_VERSION = 1
+
+        attr_reader :target, :binding_version, :grammar, :grammar_version,
+                    :grammar_source_hash, :entries, :payload
+
+        class << self
+          # Emit the per-target bindings artifact from a compiled parse
+          # artifact envelope. Returns the verified artifact; the payload
+          # is checksummed with the artifact checksum scheme (canonical
+          # JSON sha256 over everything except the checksum itself), so
+          # every engine re-derives it identically.
+          def emit(envelope, target)
+            target = target.to_s
+            unless TARGETS.include?(target)
+              raise ArtifactError,
+                    "unknown binding target #{target.inspect}; known: #{TARGETS.join(', ')}"
+            end
+
+            artifact = new(build(envelope, target))
+            artifact.verify
+          end
+
+          # The emitted artifact as JSON (the bake/CLI surface).
+          def emit_json(envelope, target)
+            JSON.generate(emit(envelope, target).payload)
+          end
+
+          # Parse and fully verify an emitted bindings artifact. `target:`
+          # pins the expected target; omit it in multi-target tooling that
+          # accepts any declared target.
+          def from_json(json, target: nil)
+            artifact = new(JSON.parse(json))
+            artifact.verify
+            artifact.verify_target!(target) unless target.nil?
+            artifact
+          end
+
+          private
+
+          def build(envelope, target)
+            payload = {
+              "artifact_kind" => KIND,
+              "target" => target,
+              "binding_version" => SUPPORTED_BINDING_VERSION,
+              "grammar" => envelope["grammar"],
+              "grammar_version" => envelope["version"],
+              "grammar_source_hash" => envelope["source_hash"],
+              "shape" => envelope["shape"],
+              "entries" => envelope["entries"].to_h do |name, entry|
+                [name, { "bindings" => entry["bindings"].to_a }]
+              end,
+            }
+            payload.merge("checksum" => Compiler.checksum(payload))
+          end
+        end
+
+        def initialize(payload)
+          raise ArtifactError, "bindings artifact payload must be an object" unless payload.is_a?(Hash)
+
+          @payload = payload
+          @target = payload["target"]
+          @binding_version = payload["binding_version"]
+          @grammar = payload["grammar"]
+          @grammar_version = payload["grammar_version"]
+          @grammar_source_hash = payload["grammar_source_hash"]
+          @entries = payload["entries"]
+          @parg_artifact = nil
+        end
+
+        # Structural verification: kind, checksum, binding version,
+        # target, entries map. Every loader path goes through here.
+        def verify
+          unless @payload["artifact_kind"] == KIND
+            raise ArtifactError,
+                  "not a #{KIND} artifact (artifact_kind #{@payload['artifact_kind'].inspect})"
+          end
+
+          expected = Compiler.checksum(@payload)
+          actual = @payload["checksum"]
+          unless actual.is_a?(String) && actual == expected
+            raise ArtifactError,
+                  "bindings artifact checksum mismatch: expected #{expected}, got #{actual.inspect}"
+          end
+
+          unless TARGETS.include?(@target)
+            raise ArtifactError,
+                  "unknown binding target #{@target.inspect}; known: #{TARGETS.join(', ')}"
+          end
+          unless @binding_version == SUPPORTED_BINDING_VERSION
+            raise ArtifactError,
+                  "unsupported binding_version #{@binding_version.inspect} " \
+                  "(supported: #{SUPPORTED_BINDING_VERSION})"
+          end
+          unless @entries.is_a?(Hash)
+            raise ArtifactError, "bindings artifact carries no entries map"
+          end
+
+          self
+        end
+
+        def verify_target!(target)
+          target = target.to_s
+          return if @target == target
+
+          raise ArtifactError,
+                "bindings artifact targets #{@target.inspect}, not #{target.inspect}"
+        end
+
+        # Pair with the parse artifact this layer was compiled from: same
+        # grammar, same version, same source. The pairing is what lets
+        # apply resolve preprocess references — they live in the parse
+        # artifact's checksummed envelope.
+        def pair_with!(parg_artifact)
+          envelope = parg_artifact.envelope
+          mismatches = []
+          mismatches << "grammar (#{@grammar.inspect} vs #{envelope['grammar'].inspect})" if @grammar != envelope["grammar"]
+          if @grammar_version != envelope["version"]
+            mismatches << "version (#{@grammar_version.inspect} vs #{envelope['version'].inspect})"
+          end
+          if @grammar_source_hash != envelope["source_hash"]
+            mismatches << "source_hash (#{@grammar_source_hash.inspect} vs #{envelope['source_hash'].inspect})"
+          end
+          unless mismatches.empty?
+            raise ArtifactError,
+                  "bindings artifact does not pair with the parse artifact: #{mismatches.join(', ')}"
+          end
+
+          @parg_artifact = parg_artifact
+          self
+        end
+
+        def entry(name)
+          @entries.fetch(name) { raise ArtifactError, "unknown entry #{name.inspect}" }
+        end
+
+        def bindings(name)
+          entry(name)["bindings"]
+        end
+
+        def entry_names
+          @entries.keys
+        end
+
+        # Materialize the bound map from a parse shape using the DECLARED
+        # records. The paired parse artifact supplies entry context and
+        # preprocess resolution; the same Bindings.apply runs as for the
+        # embedded records, so a standalone artifact and its parse
+        # artifact's baked records produce identical bound maps.
+        def apply(entry_name, shape)
+          parg = @parg_artifact
+          if parg.nil?
+            raise ArtifactError,
+                  "pair_with! the parse artifact before applying bindings"
+          end
+
+          crafted = { "name" => entry_name, "bindings" => bindings(entry_name) }
+          Bindings.apply(parg, crafted, shape)
+        end
+      end
+    end
+  end
+end

data/lib/parsanol/parg/bindings.rb

@@ -8,6 +8,9 @@ module Parsanol
     # producing the attribute hash that fills a lutaml-model class:
     # capture collection -> preprocessing -> type cast -> path assignment.
     module Bindings
+      # The declared per-target binding artifact (parsanol-ruby#432).
+      autoload :Artifact, "parsanol/parg/bindings/artifact"
+
       module_function
 
       def apply(artifact, entry, shape)

data/lib/parsanol/parg/cli.rb

@@ -18,7 +18,11 @@ module Parsanol
         usage: parsanol parg <command> <grammar> [arguments]
 
         commands:
-          compile <file.parg> [-o out.json]   compile to an artifact envelope
+          compile <file.parg> [-o out.json] [--bindings TARGET|all]
+                                            compile to an artifact envelope;
+                                            --bindings also writes one
+                                            checksummed per-target binding
+                                            artifact beside it (#432)
           test    <file.parg|artifact.json>   run the grammar's test section
           parse   <file> [--entry E] INPUT  parse one input; prints the tree
                                             and the bound captures
@@ -141,11 +145,33 @@ module Parsanol
         source = @argv.shift
         out = flag_value("-o") || default_artifact_name(source)
         envelope = compile_source(source).envelope
-        File.write(out, "#{JSON.generate(envelope)}\n", encoding: Encoding::UTF_8)
+        # Seal: the exact text written is the exact text the byte-level
+        # checksum covers (Compiler.seal_json includes the trailing
+        # newline).
+        File.write(out, Compiler.seal_json(envelope), encoding: Encoding::UTF_8)
         puts "#{out}  #{envelope['checksum']}  warnings=#{envelope['lint']['order_warnings'].size}"
+        bindings_targets.each do |target|
+          # The declared per-target binding artifacts (#432): one
+          # checksummed bindings payload per target, written beside the
+          # artifact. `--bindings all` expands to the full target set.
+          artifact = Artifact.from_json(JSON.generate(envelope))
+          path = out.sub(/\.json\z/i, ".bindings.#{target}.json")
+          File.write(path, "#{artifact.bindings_artifact_json(target)}\n", encoding: Encoding::UTF_8)
+          puts "#{path}  #{artifact.bindings_artifact(target).payload['checksum']}"
+        end
         0
       end
 
+      # Every --bindings flag value, `all` expanded to the target set.
+      # Empty when the flag is absent (compile emits no binding artifacts).
+      def bindings_targets
+        values = []
+        while (value = flag_value("--bindings"))
+          values.concat(value == "all" ? Bindings::Artifact::TARGETS.dup : [value])
+        end
+        values.uniq
+      end
+
       # Freshness (parsanol-ruby#209): verify an artifact was compiled
       # from the given source. The stale-shipped-artifact incident class
       # (an old artifact silently taking precedence over the corrected

data/lib/parsanol/parg/compiler.rb

@@ -25,19 +25,43 @@ module Parsanol
         new(document, tables_dir).compile
       end
 
-      # Canonical checksum over an envelope (everything except the checksum
-      # itself). Used both when building an artifact and when verifying one.
+      # Canonical checksum over an envelope (everything except the
+      # checksum itself and the byte-level checksum — the byte digest
+      # attests the FILE serialization, which is producer-specific and
+      # must never enter the cross-engine canonical payload). Used both
+      # when building an artifact and when verifying one.
       def self.checksum(envelope)
-        payload = envelope.except("checksum")
+        payload = envelope.except("checksum", "byte_checksum")
         "sha256:#{Digest::SHA256.hexdigest(JSON.generate(canonicalize(payload)))}"
       end
 
+      # The byte-level checksum's placeholder: a fixed-width zero region,
+      # so the sealed bytes and the verification bytes differ only inside
+      # that region (sha256 hex is 64 chars — same width).
+      BYTE_CHECKSUM_PLACEHOLDER = ("0" * 64).freeze
+      BYTE_CHECKSUM_TRAILING = "\n"
+
+      # Seal an envelope for writing: stamp the byte-level checksum over
+      # the exact file bytes (the final serialization with a trailing
+      # newline and the digest's own region zeroed) and return the exact
+      # text to write. No sidecar — the integrity travels inside the
+      # artifact. The canonical `checksum` is untouched: it attests
+      # content, `byte_checksum` attests bytes.
+      def self.seal_json(envelope)
+        sealed = envelope.merge("byte_checksum" => BYTE_CHECKSUM_PLACEHOLDER)
+        text = JSON.generate(sealed) + BYTE_CHECKSUM_TRAILING
+        digest = Digest::SHA256.hexdigest(text)
+        sealed["byte_checksum"] = "sha256:#{digest}"
+        JSON.generate(sealed) + BYTE_CHECKSUM_TRAILING
+      end
+
       # Producer metadata: the checksum pins the exact producer, but the
       # semantics hash (ruby#377) skips these fields so a re-bake by a
       # newer compiler — or a different Ruby patch stamping
       # unicode_tables — is byte-stable when the grammar's behavior is
       # unchanged. Mirrors the cross-engine parity view.
-      SEMANTICS_EXCLUDED = %w[checksum compiler_version unicode_tables semantics_hash].freeze
+      SEMANTICS_EXCLUDED = %w[checksum byte_checksum compiler_version
+                              unicode_tables semantics_hash validated].freeze
 
       def self.semantics_hash(envelope)
         payload = envelope.except(*SEMANTICS_EXCLUDED)
@@ -129,6 +153,18 @@ module Parsanol
         failures = self.class.self_test(envelope, tables_dir: @tables_dir)
         raise CompileError, failures.join("\n") unless failures.empty?
 
+        # The validation receipt: what this bake actually checked, inside
+        # the envelope the checksums cover. "valid/validated" is then an
+        # inspectable field of the artifact, not an out-of-band claim.
+        envelope["validated"] = {
+          "lint_errors" => 0, # compile raises on lint errors before this
+          "lint_warnings" => @envelope_warnings.size,
+          "tests_total" => @document.tests.size,
+          "tests_failures" => 0, # run_tests raises on failures before this
+          "self_test" => Native.available?,
+        }
+        envelope["checksum"] = Compiler.checksum(envelope)
+
         Result.new(@atom_cache, @warnings, envelope)
       end
 

data/lib/parsanol/parg/imports.rb

@@ -46,6 +46,12 @@ module Parsanol
 
           document.rules[qualified] = copy(node, prefix)
         end
+        # The `atomic` exemption rides the rule name: a component's
+        # atomic rules qualify with everything else, or the exemption
+        # never matches post-merge.
+        used.atomic_rules.each do |name|
+          document.atomic_rules << "#{prefix}#{name}"
+        end
         used.entries.each do |entry, rule|
           document.entries["#{prefix}#{entry}"] = "#{prefix}#{rule}"
         end
@@ -79,7 +85,17 @@ module Parsanol
         when :pred
           Node.new(:pred, node.a, copy(node.b, prefix), node.c)
         when :cap then Node.new(:cap, node.a, copy(node.b, prefix))
-        when :ref then Node.new(:ref, "#{prefix}#{node.a}")
+        # A qualified reference (`other.rule`) already names its own
+        # imported grammar — prefixing would double-qualify it
+        # (cross-import references compose: the other grammar's rules
+        # are prefixed by their own merge).
+        when :ref
+          name = node.a.to_s
+          if name.include?(".")
+            Node.new(:ref, name)
+          else
+            Node.new(:ref, "#{prefix}#{name}")
+          end
         else node
         end
       end

data/lib/parsanol/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Parsanol
-  VERSION = "1.3.129"
+  VERSION = "1.3.131"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: parsanol
 version: !ruby/object:Gem::Version
-  version: 1.3.129
+  version: 1.3.131
 platform: ruby
 authors:
 - Ribose Inc.
@@ -118,6 +118,7 @@ files:
 - lib/parsanol/parg/artifact.rb
 - lib/parsanol/parg/authoring.rb
 - lib/parsanol/parg/bindings.rb
+- lib/parsanol/parg/bindings/artifact.rb
 - lib/parsanol/parg/cli.rb
 - lib/parsanol/parg/compiler.rb
 - lib/parsanol/parg/derive.rb