woods 2.0.0 → 2.1.0

data/lib/woods/retrieval/lexical_assembler.rb

@@ -23,7 +23,7 @@ module Woods
         sources = []
         candidates.each do |candidate|
           unit = candidate.metadata
-          header = "\n\n## #{unit['identifier']} (#{unit['type']})\nFile: #{unit['file_path']}\n" \
+          header = "\n\n## #{unit['identifier']} (#{unit['type']})\n#{SourceContributors.label(unit)}\n" \
                    "Matched: #{candidate.matched_fields.join(', ')}\n\n"
           remaining = (budget * 4) - context.length - header.length
           next unless remaining.positive?
@@ -37,7 +37,7 @@ module Woods
             context += header + selected.text
             sources << { identifier: unit['identifier'], type: unit['type'], file_path: unit['file_path'],
                          score: candidate.score, matched_fields: candidate.matched_fields,
-                         evidence: selected.provenance }
+                         evidence: selected.provenance }.merge(SourceContributors.attribution(unit))
             next
           end
 
@@ -49,6 +49,7 @@ module Woods
           context += header + (truncated ? source[0, remaining - marker.length] + marker : source)
           sources << { identifier: unit['identifier'], type: unit['type'], file_path: unit['file_path'],
                        score: candidate.score, matched_fields: candidate.matched_fields, truncated: truncated }
+                     .merge(SourceContributors.attribution(unit))
           break if truncated
         end
         body = context[notice.length..].to_s

data/lib/woods/retrieval/scope.rb

@@ -3,6 +3,7 @@
 require 'json'
 require 'set'
 require_relative '../storage_identity'
+require_relative '../source_contributors'
 require_relative '../storage/metadata_store'
 
 module Woods
@@ -83,13 +84,28 @@ module Woods
       def validate_packages!(records)
         names = records.filter_map { |unit| unit['identifier'] if unit['type'] == 'package' }
         names.concat(records.filter_map { |unit| unit.dig('metadata', 'package') })
+        names.concat(records.flat_map do |unit|
+          SourceContributors.records(unit).filter_map do |record|
+            record['package']
+          end
+        end)
         unknown = packages - names
         raise InvalidScopeError, "unknown package scope: #{unknown.join(', ')}" unless unknown.empty?
       end
 
       def eligible?(unit, types, excluded)
-        return false unless packages.empty? || packages.include?(unit.dig('metadata', 'package'))
-        return false unless source_paths.empty? || path_match?(unit['file_path'])
+        contributors = SourceContributors.records(unit)
+        owners = if contributors.empty?
+                   [unit.dig('metadata', 'package')]
+                 else
+                   contributors.map do |record|
+                     record['package']
+                   end
+                 end
+        return false unless packages.empty? || owners.all? { |owner| packages.include?(owner) }
+
+        paths = SourceContributors.paths(unit)
+        return false unless source_paths.empty? || (paths.any? && paths.all? { |path| path_match?(path) })
         return Array(types).map(&:to_s).include?(unit['type']) if types && !types.empty?
 
         !Array(excluded).map(&:to_s).include?(unit['type'])

data/lib/woods/retrieval/source_evidence.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../source_contributors'
+
 require 'digest'
 require 'json'
 require_relative '../ast/parser'
@@ -170,7 +172,7 @@ module Woods
 
       def format_evidence(mode, selected, metadata, total)
         parts = ["Evidence: #{mode}; published-unit coordinates (physical location unavailable).",
-                 "Unit: #{field(:type)}:#{field(:identifier)}; path: #{field(:file_path)}",
+                 "Unit: #{field(:type)}:#{field(:identifier)}; #{SourceContributors.label(@unit)}",
                  "Source SHA256: #{Digest::SHA256.hexdigest(@source)}",
                  "Generation: #{@generation || 'unavailable (not recorded by this metadata store)'}"]
         selected.each do |span|
@@ -183,17 +185,27 @@ module Woods
         parts.join("\n\n")
       end
 
+      def span_provenance(span)
+        result = span.to_h.merge(sha256: Digest::SHA256.hexdigest(span_text(span)))
+        if SourceContributors.multiple?(@unit)
+          result[:physical_location] =
+            SourceContributors.physical_span(@unit, start_byte: span.start_byte, end_byte: span.end_byte)
+        end
+        result
+      end
+
       def provenance(mode, selected, metadata, all)
         { mode: mode, owner: { identifier: field(:identifier), type: field(:type) },
           coordinate_system: 'published_unit', source_sha256: Digest::SHA256.hexdigest(@source),
           source_path: field(:file_path), physical_location: nil,
           physical_location_reason: 'published unit may contain synthesized or inlined source',
           generation: @generation, generation_status: @generation ? 'recorded' : 'unavailable',
-          spans: selected.map { |span| span.to_h.merge(sha256: Digest::SHA256.hexdigest(span_text(span))) },
+          spans: selected.map { |span| span_provenance(span) },
           omitted_spans: all.size - selected.size, runtime_fields: metadata.map(&:first),
           source_complete: false, full_evidence: { tool: 'lookup', evidence: 'full',
                                                    identifier: field(:identifier), type: field(:type),
                                                    source_sha256: Digest::SHA256.hexdigest(@source) } }
+          .merge(SourceContributors.attribution(@unit))
       end
     end
   end

data/lib/woods/source_contributor_validation.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Woods
+  # Checks the versioned contributor boundary before consumers use its paths or coordinates.
+  module SourceContributorValidation
+    class Invalid < ArgumentError; end
+
+    RANGE_KEYS = %w[source_start_line source_end_line published_start_byte published_end_byte
+                    published_start_line published_end_line].freeze
+
+    module_function
+
+    def validate!(records, type:, version:, source:)
+      unless type.to_s == 'lib' && version == 1 && records.is_a?(Array) && records.size.between?(2, 100_000)
+        raise Invalid, 'Invalid library contributor version or records'
+      end
+
+      validate_records!(records)
+      records.each { |record| validate_source!(source, record) } if source.is_a?(String)
+      records
+    end
+
+    def validate_records!(records)
+      previous = 0
+      paths = records.map do |record|
+        unless valid_record?(record) && valid_ranges?(record, previous)
+          raise Invalid, 'Invalid library contributor path or range'
+        end
+
+        previous = record.fetch('published_end_byte')
+        record.fetch('file_path')
+      end
+      raise Invalid, 'Unordered or duplicate library contributor path' unless paths.uniq.sort == paths
+    end
+
+    def valid_record?(record)
+      record.is_a?(Hash) && record.keys.all?(String) && valid_path?(record['file_path']) &&
+        valid_hash?(record['source_sha256']) &&
+        record['facts'].is_a?(Hash) && RANGE_KEYS.all? { |key| record[key].is_a?(Integer) }
+    end
+
+    def valid_hash?(hash)
+      hash.is_a?(String) && hash.match?(/\A[0-9a-f]{64}\z/)
+    end
+
+    def valid_ranges?(record, previous)
+      record['source_start_line'] == 1 && record['source_end_line'].positive? &&
+        record['published_start_byte'] >= previous && record['published_end_byte'] > record['published_start_byte'] &&
+        record['published_start_line'].positive? && record['published_end_line'] >= record['published_start_line']
+    end
+
+    def valid_path?(path)
+      path.is_a?(String) && path.start_with?('lib/') && path.end_with?('.rb') && !path.include?("\0") &&
+        !path.include?('\\') && path.split('/', -1).none? { |part| ['', '.', '..'].include?(part) }
+    end
+
+    def validate_source!(source, record)
+      raise Invalid, 'Contributor range exceeds published source' if record['published_end_byte'] > source.bytesize
+
+      fragment = source.byteslice(record['published_start_byte']...record['published_end_byte'])
+      first = source.byteslice(0...record['published_start_byte']).count("\n") + 1
+      return if valid_fragment?(fragment, first, record)
+
+      raise Invalid, 'Library contributor bytes do not match published provenance'
+    end
+
+    def valid_fragment?(fragment, first, record)
+      Digest::SHA256.hexdigest(fragment) == record['source_sha256'] &&
+        fragment.lines.size == record['source_end_line'] && first == record['published_start_line'] &&
+        first + fragment.lines.size - 1 == record['published_end_line']
+    end
+    private_class_method :validate_records!, :valid_record?, :valid_hash?, :valid_ranges?, :valid_path?,
+                         :validate_source!,
+                         :valid_fragment?
+  end
+end

data/lib/woods/source_contributors.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative 'source_contributor_validation'
+
+module Woods
+  # Provenance for a published unit assembled from several original files.
+  # Byte ranges are half-open and exclude every generated header/separator.
+  module SourceContributors
+    Invalid = SourceContributorValidation::Invalid
+
+    VERSION = 1
+
+    module_function
+
+    # @param unit [ExtractedUnit, Hash]
+    # @return [Array<Hash>] validated, string-keyed contributor records
+    def records(unit)
+      metadata = field(unit, :metadata) || {}
+      raw = field(metadata, :source_contributors)
+      return [] if raw.nil?
+
+      SourceContributorValidation.validate!(raw, type: field(unit, :type),
+                                                 version: field(metadata, :source_contributors_version),
+                                                 source: field(unit, :source_code))
+    end
+
+    # @param unit [ExtractedUnit, Hash]
+    # @return [Array<String>] every physical source, or the legacy primary path
+    def paths(unit)
+      contributors = records(unit)
+      contributors.empty? ? Array(field(unit, :file_path)) : contributors.map { |record| record.fetch('file_path') }
+    end
+
+    # @param unit [ExtractedUnit, Hash]
+    # @return [Boolean]
+    def multiple?(unit)
+      !records(unit).empty?
+    end
+
+    # @param unit [ExtractedUnit, Hash]
+    # @param start_byte [Integer] inclusive published byte offset
+    # @param end_byte [Integer] exclusive published byte offset
+    # @return [Hash, nil] physical coordinates only for an exact original fragment
+    def physical_span(unit, start_byte:, end_byte:)
+      return unless valid_span?(start_byte, end_byte)
+
+      record = records(unit).find do |fragment|
+        start_byte >= fragment['published_start_byte'] && end_byte <= fragment['published_end_byte']
+      end
+      return unless record
+
+      source = field(unit, :source_code)
+      return unless source.is_a?(String)
+
+      first = record['source_start_line'] + source.byteslice(record['published_start_byte']...start_byte).count("\n")
+      { file_path: record['file_path'], source_sha256: record['source_sha256'], start_line: first,
+        end_line: first + source.byteslice(start_byte...end_byte).delete_suffix("\n").count("\n") }
+    end
+
+    def valid_span?(first, last)
+      first.is_a?(Integer) && last.is_a?(Integer) && last > first
+    end
+    private_class_method :valid_span?
+
+    # @param unit [ExtractedUnit, Hash]
+    # @return [String] explicit primary/contributor label, or legacy file label
+    def label(unit)
+      return "File: #{field(unit, :file_path)}" unless multiple?(unit)
+
+      "Primary file: #{field(unit, :file_path)}\nContributing files: #{paths(unit).join(', ')}"
+    end
+
+    # @param unit [ExtractedUnit, Hash]
+    # @return [Hash] additive contributor evidence for response renderers
+    def attribution(unit)
+      multiple?(unit) ? { source_contributors: records(unit) } : {}
+    end
+
+    # @param unit [ExtractedUnit, Hash]
+    # @param resolver [Object] package_for(path) collaborator
+    # @return [String, nil] unanimous package ownership, or nil
+    def annotate_package(unit, resolver)
+      contributors = records(unit)
+      return resolver.package_for(field(unit, :file_path)) if contributors.empty?
+
+      packages = contributors.map do |record|
+        package = resolver.package_for(record['file_path'])
+        package ? record['package'] = package : record.delete('package')
+        package
+      end
+      packages.first if packages.uniq.one?
+    end
+
+    # @param unit [ExtractedUnit, Hash]
+    # @param data [Hash] Git facts keyed by application-relative source path
+    # @return [void]
+    def annotate_git(unit, data)
+      records(unit).each do |record|
+        record.delete('git')
+        record['git'] = data[record['file_path']] if data[record['file_path']]
+      end
+      metadata = field(unit, :metadata)
+      metadata.delete(:git)
+      metadata.delete('git')
+    end
+
+    # @param value [Object, Hash]
+    # @param key [Symbol]
+    # @return [Object]
+    def field(value, key)
+      return value[key] || value[key.to_s] if value.is_a?(Hash)
+
+      value.public_send(key) if value.respond_to?(key)
+    end
+  end
+end

data/lib/woods/source_inputs/handoff.rb

@@ -9,9 +9,35 @@ module Woods
     # existing index manifest nor a user-supplied proof of runtime freshness.
     module Handoff
       ENV_KEY = 'WOODS_SOURCE_CAPTURE'
+      class OutputMismatch < StandardError; end
 
       module_function
 
+      # An implicit preboot default cannot override finalized application config.
+      # Explicit launcher outputs remain intentional overrides. Called before
+      # the writer lock/extraction, while the one-use handoff is still present.
+      # @param root [String, Pathname] finalized application root
+      # @param output_dir [String, Pathname] selected writer output
+      # @return [void]
+      def validate_output!(root:, output_dir:)
+        token = ENV.fetch(ENV_KEY, nil)
+        return if token.to_s.empty?
+
+        descriptor = JSON.parse(token)
+        return unless descriptor.is_a?(Hash) && descriptor['implicit_output'] == true
+
+        expected = File.expand_path('tmp/woods', root.to_s)
+        configured = File.expand_path(Woods.configuration.output_dir.to_s, root.to_s)
+        return if configured == expected && File.expand_path(output_dir.to_s, root.to_s) == expected
+
+        raise OutputMismatch,
+              "woods-extract configured output #{configured.inspect} differs from " \
+              "its preboot default #{expected.inspect}; " \
+              'rerun with matching --output PATH or WOODS_OUTPUT so capture and publication use the same index'
+      rescue JSON::ParserError, TypeError
+        nil # Ordinary handoff validation will refuse unverifiable capture.
+      end
+
       # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       # Every independent handoff binding must match before a token is consumed.
       def read(root:, output_dir:, operation:, rules:, key_id:)
@@ -85,6 +111,17 @@ module Woods
 
       # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
+      # An oversized launcher capture conveys only a downgrade, never proof.
+      def unavailable_evidence
+        descriptor = JSON.parse(ENV.fetch(ENV_KEY, '{}'))
+        value = descriptor.is_a?(Hash) && descriptor['unavailable']
+        return unless Manifest.valid_unavailable_evidence?(value)
+
+        value.slice('reason', 'size_bytes', 'limit_bytes')
+      rescue JSON::ParserError
+        nil
+      end
+
       def extra_roots
         token = ENV.fetch(ENV_KEY, nil)
         return [] if token.nil? || token.empty?

data/lib/woods/source_inputs/launcher.rb

@@ -17,22 +17,27 @@ module Woods
 
       def self.run(argv, **options)
         new(argv, **options).run
-      rescue OptionParser::ParseError, ArgumentError, PrivateKey::Unavailable, SystemCallError => e
+      rescue PrivateKey::Unavailable => e
+        warn "woods-extract: #{e.diagnostic}"
+        1
+      rescue OptionParser::ParseError, ArgumentError, SystemCallError => e
         warn "woods-extract: #{e.message}"
         1
       end
 
-      def initialize(argv, command: %w[bundle exec rake])
+      def initialize(argv, command: nil)
         @arguments = argv.dup
         @command = command
         @original_directory = Dir.pwd
         @root = @original_directory
+        @implicit_output = !ENV.key?('WOODS_OUTPUT')
         @output = ENV.fetch('WOODS_OUTPUT', 'tmp/woods')
         @extra_roots = []
         parse!
+        @command ||= default_command
       end
 
-      def run # rubocop:disable Metrics/MethodLength -- handoff lifetime encloses the fresh child
+      def run
         return 0 if @help
 
         operation, task = task_for_arguments
@@ -40,25 +45,57 @@ module Woods
         rules = Scopes.new(extra_roots: @extra_roots)
         snapshot = Scanner.new(root: @root, output_dir: @output, key: key, scopes: rules).call
         nonce = SecureRandom.hex(32)
+        bytes = capture_bytes(snapshot, nonce, operation, rules)
+        return run_without_capture(task) unless bytes
+
         Tempfile.create(['woods-source-capture-', '.json']) do |file|
           file.binmode
           file.chmod(0o600)
-          file.write(JSON.generate(version: 1, nonce: nonce, root: @root, output: @output,
-                                   operation: operation, rules: rules.fingerprint,
-                                   launcher_pid: Process.pid, snapshot: snapshot))
+          file.write(bytes)
           file.flush
           file.fsync
-          descriptor = JSON.generate(path: file.path, nonce: nonce, extra_roots: @extra_roots)
-          environment = { Handoff::ENV_KEY => descriptor, 'WOODS_OUTPUT' => @output }
-          if ENV['BUNDLE_GEMFILE']
-            environment['BUNDLE_GEMFILE'] = File.expand_path(ENV.fetch('BUNDLE_GEMFILE'), @original_directory)
-          end
-          run_child(environment, task)
+          descriptor = JSON.generate(path: file.path, nonce: nonce, extra_roots: @extra_roots,
+                                     implicit_output: @implicit_output)
+          run_child(child_environment(descriptor), task)
         end
       end
 
       private
 
+      def default_command
+        binstub = File.join(@root, 'bin/rake')
+        File.file?(binstub) && File.executable?(binstub) ? [binstub] : %w[bundle exec rake]
+      end
+
+      def run_without_capture(task)
+        descriptor = JSON.generate(extra_roots: @extra_roots, implicit_output: @implicit_output,
+                                   unavailable: @capture_unavailable)
+        run_child(child_environment(descriptor), task)
+      end
+
+      def capture_bytes(snapshot, nonce, operation, rules)
+        bytes = JSON.generate(version: 1, nonce: nonce, root: @root, output: @output,
+                              operation: operation, rules: rules.fingerprint,
+                              launcher_pid: Process.pid, snapshot: snapshot)
+        return bytes if bytes.bytesize <= Manifest::MAX_BYTES
+
+        @capture_unavailable = { 'reason' => 'source_manifest_too_large', 'size_bytes' => bytes.bytesize,
+                                 'limit_bytes' => Manifest::MAX_BYTES }
+        warn 'woods-extract: source freshness unavailable (source_manifest_too_large): ' \
+             "capture #{bytes.bytesize} bytes exceeds limit #{Manifest::MAX_BYTES}; " \
+             'continuing without verified preboot evidence.'
+        nil
+      end
+
+      def child_environment(descriptor)
+        environment = { Handoff::ENV_KEY => descriptor }
+        environment['WOODS_OUTPUT'] = @output unless @implicit_output
+        if ENV['BUNDLE_GEMFILE']
+          environment['BUNDLE_GEMFILE'] = File.expand_path(ENV.fetch('BUNDLE_GEMFILE'), @original_directory)
+        end
+        environment
+      end
+
       def parse!
         parser.permute!(@arguments)
         validate_arguments! unless @help
@@ -68,7 +105,10 @@ module Woods
         OptionParser.new do |options|
           options.banner = 'Usage: woods-extract [options] full | incremental PATH... | refresh TYPE...'
           options.on('--root PATH', 'Application root (default: current directory)') { |path| @root = path }
-          options.on('--output PATH', 'Index output (default: WOODS_OUTPUT or tmp/woods)') { |path| @output = path }
+          options.on('--output PATH', 'Custom output (default: WOODS_OUTPUT or tmp/woods)') do |path|
+            @output = path
+            @implicit_output = false
+          end
           options.on('--source-root PATH', 'Additional application-relative runtime source root') do |path|
             @extra_roots << path
           end

data/lib/woods/source_inputs/manifest.rb

@@ -1,15 +1,18 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'digest'
 
 module Woods
   module SourceInputs
     # Compact wire format: consumers refer to a shared identity table. Internal
     # mutation uses expanded digests so table indices never leak across runs.
-    class Manifest
+    class Manifest # rubocop:disable Metrics/ClassLength -- compact wire validation and bounded serialization
       FILE_NAME = 'source_inputs.json'
       VERSION = 1
       MAX_BYTES = 16 * 1024 * 1024
+      UNKNOWN_BASELINES = %w[invalid_source_baseline missing_or_incompatible_source_baseline
+                             incomplete_source_baseline].freeze
       class Invalid < StandardError; end
 
       attr_reader :data
@@ -34,24 +37,73 @@ module Woods
         end
       end
 
+      # Older version-1 writers encoded missing comparison evidence only as
+      # errors. Never interpret their empty ledger as proof of an empty tree.
+      def comparison_complete?
+        @data['complete'] && @data.fetch('comparison_complete', true) &&
+          @data.fetch('errors').none? { |error| UNKNOWN_BASELINES.include?(error['reason']) }
+      end
+
       # Explicit wire fields keep incomplete coverage separate from boot provenance.
       # rubocop:disable Metrics/AbcSize, Metrics/ParameterLists
-      def self.build(snapshot:, scopes:, boot_verified:, generation:, errors: [], unverified_scopes: [])
+      def self.build(snapshot:, scopes:, boot_verified:, generation:, errors: [], unverified_scopes: [],
+                     comparison_complete: true, unavailable: nil)
         identities = scopes.values.flat_map(&:values).uniq.sort
         indices = identities.each_with_index.to_h
         new('version' => VERSION, 'generation' => generation, 'root' => snapshot.fetch('root'),
+            'captured_at' => snapshot['captured_at'],
             'key_id' => snapshot.fetch('key_id'), 'rules' => snapshot.fetch('rules'),
             'extra_roots' => snapshot.fetch('extra_roots'), 'boot_verified' => boot_verified,
             'complete' => snapshot.fetch('complete'), 'errors' => (snapshot.fetch('errors') + errors).uniq,
+            'comparison_complete' => comparison_complete,
             'unverified_scopes' => unverified_scopes.uniq.sort,
             'identities' => identities, 'metrics' => snapshot.fetch('metrics'),
             'scopes' => scopes.sort.to_h.transform_values do |paths|
               paths.sort.to_h.transform_values { |digest| indices.fetch(digest) }
-            end)
+            end).tap { |manifest| manifest.bound_publication!(snapshot: snapshot, unavailable: unavailable) }
       end
 
       # rubocop:enable Metrics/AbcSize, Metrics/ParameterLists
 
+      # Compact watch boundary only: this never certifies runtime freshness.
+      def self.capture_digest(files)
+        Digest::SHA256.hexdigest(JSON.generate(files.sort.to_h))
+      end
+
+      def self.valid_unavailable_evidence?(value)
+        value.is_a?(Hash) && value['reason'] == 'source_manifest_too_large' &&
+          value.values_at('size_bytes', 'limit_bytes').all?(Integer) &&
+          value['limit_bytes'].positive? && value['size_bytes'] > value['limit_bytes']
+      end
+
+      def unavailable?
+        @data['state'] == 'unavailable'
+      end
+
+      # Bind only an already validated, generation-local reference cache. This
+      # preserves its consumed-source proof without publishing the large ledger.
+      def bind_reference_cache!(cache)
+        @data['reference_cache_sha256'] = Digest::SHA256.hexdigest(JSON.generate(cache)) if unavailable? && cache
+      end
+
+      # Source evidence is advisory. Its size limit must not withhold a valid
+      # code index. Keep errors so final publication still refuses unstable input.
+      def bound_publication!(snapshot:, unavailable: nil)
+        size = JSON.pretty_generate(@data).bytesize
+        return unless unavailable || size > MAX_BYTES
+
+        diagnostic = unavailable || { 'reason' => 'source_manifest_too_large',
+                                      'size_bytes' => size, 'limit_bytes' => MAX_BYTES }
+        @data['capture_sha256'] = self.class.capture_digest(snapshot.fetch('files')) if snapshot['complete']
+        @data.merge!('state' => 'unavailable', 'unavailable' => diagnostic,
+                     'complete' => false, 'comparison_complete' => false,
+                     'identities' => [], 'scopes' => {}, 'metrics' => {})
+        warn "[woods] source freshness unavailable: #{diagnostic['reason']}; " \
+             "#{diagnostic['size_bytes']} bytes exceeds limit #{diagnostic['limit_bytes']}. " \
+             'Publishing the code index without freshness comparison evidence; ' \
+             'another full extraction will not reduce this size.'
+      end
+
       private
 
       def validate!
@@ -59,11 +111,28 @@ module Woods
         raise Invalid, 'invalid_source_manifest_header' unless valid_header?
 
         validate_tables!
+        validate_unavailable!
         return if @data['extra_roots'].all? { |path| valid_path?(path) }
 
         raise Invalid, 'invalid_source_roots'
       end
 
+      def validate_unavailable!
+        return if (%w[state unavailable reference_cache_sha256 capture_sha256] & @data.keys).empty?
+
+        valid = unavailable? && self.class.valid_unavailable_evidence?(@data['unavailable']) && empty_comparison?
+        valid &&= valid_optional_digests?
+        raise Invalid, 'invalid_unavailable_source_manifest' unless valid
+      end
+
+      def valid_optional_digests?
+        %w[reference_cache_sha256 capture_sha256].all? { |key| !@data.key?(key) || digest?(@data[key]) }
+      end
+
+      def empty_comparison?
+        !@data['complete'] && !@data['comparison_complete'] && @data['scopes'].empty? && @data['identities'].empty?
+      end
+
       def validate_tables!
         identities = @data['identities']
         scopes = @data['scopes']
@@ -89,9 +158,21 @@ module Woods
 
       def valid_header?
         valid_root? && %w[key_id rules].all? { |key| digest?(@data[key]) } &&
+          valid_capture_time? && valid_comparison_coverage? &&
           %w[boot_verified complete].all? { |key| [true, false].include?(@data[key]) }
       end
 
+      def valid_comparison_coverage?
+        !@data.key?('comparison_complete') || [true, false].include?(@data['comparison_complete'])
+      end
+
+      # Optional so existing version-1 manifests remain readable. Consumers
+      # needing a catch-up boundary must reconcile when it is absent.
+      def valid_capture_time?
+        value = @data['captured_at']
+        value.nil? || (value.is_a?(Numeric) && value.finite? && value.positive?)
+      end
+
       def valid_root?
         root = @data['root']
         root.is_a?(String) && root.start_with?('/') && !root.include?("\0")