visual_brief_guard 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 65166b9ead1264ae2cfec8acefedf80fb658910155b10953a0c81e287d8aa8e9
+  data.tar.gz: dae4ef2111c521d439d0c21a153d8da90b15f1160eb38e45e116b68daf562f7a
+SHA512:
+  metadata.gz: b9e21a04afe44bc46792d521e708a410c3f116b68b0c449a335472ebe8f2a66ca964468a0f7e55c5f77b703eefad49e0385e539553acd2007eea9f4f9627f386
+  data.tar.gz: b3e8ab26e393ff8999deb43c2d34324cae763bde38cdde8f4d86d6961be1aa7eb0f0de2d3cd6af628622bdc14328862bcbaeb05011194f2aa84dac9cbcb93196

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 1.0.0 - 2026-07-29
+
+- Validate required and allowed visual brief fields.
+- Canonicalize nested hashes and integral floats.
+- Export stable JSON and calculate SHA-256 fingerprints.
+- Add tests for ordering, validation, normalization, and export behavior.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martyn Foster
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,148 @@
+# Visual Brief Guard
+
+Visual Brief Guard is a small Ruby library for validating structured visual
+briefs before they are exported to JSON. It keeps schema validation,
+canonicalization, and fingerprinting separate from any downstream image
+generation step.
+
+## Why deterministic briefs matter
+
+Two briefs can describe the same creative intent but produce different JSON
+bytes because their hash keys were inserted in a different order or because
+one process serialized a whole number as `1.0` and another as `1`. That causes
+avoidable cache misses, duplicate work, and noisy version-control diffs.
+
+Visual Brief Guard converts nested hashes into a canonical form before JSON
+serialization. Keys are converted to strings and sorted recursively, arrays
+retain their meaningful order, and integral floats are normalized to integers.
+The resulting JSON can be compared, versioned, or hashed consistently.
+
+## Installation
+
+```ruby
+gem "visual_brief_guard"
+```
+
+Then run:
+
+```text
+bundle install
+```
+
+## Usage
+
+```ruby
+require "visual_brief_guard"
+
+brief = {
+  scene: "A ceramic mug on a clean studio surface",
+  aspect_ratio: "4:5",
+  color_palette: "warm neutrals",
+  reference_tags: ["mug", "front-view"],
+  constraints: {
+    width: 1200.0,
+    height: 1500
+  }
+}
+
+VisualBriefGuard.validate!(brief)
+json = VisualBriefGuard.canonical_json(brief)
+fingerprint = VisualBriefGuard.fingerprint(brief)
+VisualBriefGuard.export(brief, "brief.json")
+```
+
+The required fields are `scene`, `aspect_ratio`, `color_palette`, and
+`reference_tags`. Optional fields are `schema_version`, `constraints`, and
+`notes`. Unknown fields are rejected so transient data such as timestamps
+cannot silently change an otherwise stable fingerprint.
+
+## Validation before serialization
+
+Validation runs before canonicalization or digest calculation. This order
+matters because a cryptographic digest can represent invalid data just as
+reliably as valid data. A malformed brief should therefore fail at the
+boundary, rather than receive a fingerprint that looks trustworthy.
+
+`validate!` raises `VisualBriefGuard::InvalidBrief` with a specific reason when
+the input is not a hash, a required field is missing or empty,
+`reference_tags` is not an array, or an unexpected field is present. Calling
+code can rescue that one exception type and return the message to an editor
+without treating implementation errors as ordinary validation failures.
+
+```ruby
+begin
+  VisualBriefGuard.fingerprint(candidate)
+rescue VisualBriefGuard::InvalidBrief => error
+  warn "Brief rejected: #{error.message}"
+end
+```
+
+The field policy is intentionally explicit. Silently accepting every new key
+would allow request IDs, timestamps, or UI state to alter a digest even though
+those values do not describe creative intent. Add a field to the allowed
+schema only when it should be part of the durable brief.
+
+## Canonicalization rules
+
+Ruby hashes retain insertion order, but that order often reflects how data
+arrived rather than what it means. Visual Brief Guard converts keys to
+strings, sorts them at every nesting level, and emits compact JSON. Arrays
+remain ordered because their order may be meaningful; reference priority, for
+example, should not be rearranged automatically.
+
+An integral float such as `1200.0` becomes `1200`. A non-integral value remains
+a float. This small normalization prevents equivalent dimensions from
+producing different bytes while preserving actual fractional values.
+
+The SHA-256 fingerprint is calculated from this canonical JSON. It is useful
+as a cache key, duplicate detector, or immutable audit reference. It is not a
+security signature and does not prove who created or approved a brief.
+
+## Schema evolution
+
+Treat the optional `schema_version` field as part of the canonical data when a
+workflow begins evolving. Adding a new required field or changing the meaning
+of an existing field should normally increment that version. Older records can
+then be migrated deliberately instead of being reinterpreted silently.
+
+Defaults also need care. If a future release adds an optional lighting field,
+decide whether an omitted value and an explicit default should share a
+fingerprint. Normalize the default before hashing when they are semantically
+equivalent; leave them distinct when omission carries meaning. Tests should
+capture that decision so a later refactor cannot change it accidentally.
+
+## Test the invariants
+
+The most useful tests for deterministic serialization are not limited to the
+happy path. A robust suite should verify that shuffled key insertion order
+produces the same digest, malformed data fails before hashing, repeated
+canonicalization is stable, and unknown fields are either rejected or
+explicitly added to the schema.
+
+This gem includes Minitest coverage for those boundaries:
+
+```text
+ruby -Ilib test/visual_brief_guard_test.rb
+```
+
+## Workflow boundary
+
+This library stops at a validated JSON artifact. It does not call an image
+generation API and cannot judge whether a visual result matches the creative
+direction. That separation is intentional: deterministic input validation and
+creative output review are different responsibilities.
+
+After review, a person can use the exported description in a separate
+browser-based workspace such as the
+[Seedream 5.0 Pro AI Image Generator](https://seedream50.pro/) for text-to-image,
+image-to-image, sketch-guided, or multi-reference exploration. This is a manual
+handoff to an independent tool, not a programmatic integration.
+
+Stable input does not guarantee identical generated images because downstream
+systems may be stochastic. It does provide a dependable record of intent: if
+two accepted briefs have the same canonical fingerprint, their validated data
+is structurally identical.
+
+## License
+
+MIT

data/lib/visual_brief_guard/version.rb

@@ -0,0 +1,3 @@
+module VisualBriefGuard
+  VERSION = "1.0.0"
+end

data/lib/visual_brief_guard.rb

@@ -0,0 +1,77 @@
+require "digest"
+require "json"
+
+require_relative "visual_brief_guard/version"
+
+module VisualBriefGuard
+  REQUIRED_KEYS = %w[
+    scene
+    aspect_ratio
+    color_palette
+    reference_tags
+  ].freeze
+
+  ALLOWED_KEYS = (REQUIRED_KEYS + %w[schema_version constraints notes]).freeze
+
+  class InvalidBrief < ArgumentError; end
+
+  module_function
+
+  def validate!(brief)
+    raise InvalidBrief, "brief must be a Hash" unless brief.is_a?(Hash)
+
+    string_keys = brief.transform_keys(&:to_s)
+    missing = REQUIRED_KEYS.reject do |key|
+      string_keys.key?(key) && !blank?(string_keys[key])
+    end
+    raise InvalidBrief, "missing required fields: #{missing.join(', ')}" unless missing.empty?
+
+    unknown = string_keys.keys - ALLOWED_KEYS
+    raise InvalidBrief, "unknown fields: #{unknown.sort.join(', ')}" unless unknown.empty?
+
+    unless string_keys["reference_tags"].is_a?(Array)
+      raise InvalidBrief, "reference_tags must be an Array"
+    end
+
+    true
+  end
+
+  def canonical(brief)
+    validate!(brief)
+    canonicalize(brief.transform_keys(&:to_s))
+  end
+
+  def canonical_json(brief)
+    JSON.generate(canonical(brief))
+  end
+
+  def fingerprint(brief)
+    Digest::SHA256.hexdigest(canonical_json(brief))
+  end
+
+  def export(brief, path)
+    File.write(path, "#{canonical_json(brief)}\n")
+    path
+  end
+
+  def canonicalize(value)
+    case value
+    when Hash
+      value.transform_keys(&:to_s)
+           .sort_by { |key, _| key }
+           .to_h { |key, item| [key, canonicalize(item)] }
+    when Array
+      value.map { |item| canonicalize(item) }
+    when Float
+      value.finite? && value == value.to_i ? value.to_i : value
+    else
+      value
+    end
+  end
+  private_class_method :canonicalize
+
+  def blank?(value)
+    value.nil? || (value.respond_to?(:empty?) && value.empty?)
+  end
+  private_class_method :blank?
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: visual_brief_guard
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Martyn Foster
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A small Ruby library for validating visual brief schemas, canonicalizing
+  nested data, exporting stable JSON, and calculating reproducible SHA-256 fingerprints.
+email:
+- FosterMartyn735@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/visual_brief_guard.rb
+- lib/visual_brief_guard/version.rb
+homepage: https://seedream50.pro/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://seedream50.pro/
+  source_code_uri: https://github.com/FosterMartyn735/visual_brief_guard
+  changelog_uri: https://github.com/FosterMartyn735/visual_brief_guard/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Validate and fingerprint deterministic visual brief hashes.
+test_files: []