we-promise/sure · error · Provenance::Citation::InvalidError

source citation must name the document it came from

Error message

source citation must name the document it came from

What it means

Provenance::Citation.parse! raises InvalidError 'source citation must name the document it came from' when the text captured by FORMAT is shorter than MIN_TEXT_LENGTH (3) after stripping. This catches citations that are technically present but content-free — e.g. 'x' or a lone character — which would give a number the appearance of being sourced without identifying anything.

Source

Thrown at app/models/provenance/citation.rb:59

        value = raw.to_s.strip

        raise InvalidError, "source citation is required" if value.blank?
        raise InvalidError, "source citation must be #{MAX_LENGTH} characters or fewer" if value.length > MAX_LENGTH

        if value.match?(ESTIMATED_MARKER) && !value.start_with?(ESTIMATED_PREFIX)
          raise InvalidError, "estimated values must start with the exact prefix #{ESTIMATED_PREFIX.inspect}"
        end

        if (suffix = value.match(GRADE_SUFFIX)) && !GRADES.include?(suffix[:grade])
          raise InvalidError, "reliability grade must be one of #{GRADES.join(", ")} (got #{suffix[:grade].inspect})"
        end

        match = value.match(FORMAT)
        raise InvalidError, "source citation does not match #{grammar}" unless match

        text = match[:text].to_s.strip
        if text.length < MIN_TEXT_LENGTH
          raise InvalidError, "source citation must name the document it came from"
        end

        estimated = match[:estimated].present?
        grade = match[:grade]

        if estimated && grade.blank?
          raise InvalidError, "estimated values must carry a reliability grade, e.g. \"#{ESTIMATED_PREFIX}... (grade: C)\""
        end

        new(raw: value, text: text, estimated: estimated, grade: grade)
      end

      def valid?(raw)
        parse!(raw)
        true
      rescue InvalidError
        false
      end

View on GitHub (pinned to e69894adb9)

Solutions

  1. Write an actual document name of at least 3 characters: 'Broker statement 2025-12'.
  2. Reject placeholder input upstream (treat 'x', '-', 'tbd' as blank).
  3. Check length pre-parse: value.strip.length >= 3.

Example fix

# before
Provenance::Citation.parse!("x")

# after
Provenance::Citation.parse!("Broker statement 2025-12")
Defensive patterns

Strategy: validation

Validate before calling

value.to_s.strip.length >= Provenance::Citation::MIN_TEXT_LENGTH # 3

Type guard

def citation_text_long_enough?(v) = v.to_s.strip.length >= Provenance::Citation::MIN_TEXT_LENGTH

Try / catch

begin
  Provenance::Citation.parse!(source)
rescue Provenance::Citation::InvalidError => e
  errors.add(:source, e.message)
end

Prevention

When it happens

Trigger: Citations like 'a', 'ab', ' x ', or a value that is only the grade suffix with near-empty text ('(grade: A)' with nothing before it).

Common situations: Placeholder values from forms ('-', 'n/a' survives only if 3+ chars, so mostly single/double chars); agent emitting a stub; whitespace-padded short tokens.

Related errors

AI-assisted analysis of we-promise/sure@e69894adb9 (2026-08-21). Data as JSON: /api/errors/eb78af092902257c. Report an issue: GitHub.