breadkit 0.1.0 → 0.2.0

data/lib/breadkit/mcp_server.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "mcp"
+require_relative "../breadkit"
+
+module Breadkit
+  class MCPServer
+    EXTENSIONS = %w[.bk.yml .bk.yaml .bk.toml .json].freeze
+    MAX_INPUT_BYTES = 8 * 1024 * 1024
+
+    def initialize(root: Dir.pwd)
+      @root = File.realpath(root)
+      raise ArgumentError, "MCP root must be a directory" unless File.directory?(@root)
+    end
+
+    def server
+      @server ||= build_server
+    end
+
+    def run
+      MCP::Server::Transports::StdioTransport.new(server).open
+    end
+
+    private
+
+    def build_server
+      result = MCP::Server.new(name: "breadkit", version: VERSION,
+                               instructions: "Read-only circuit tools. Inputs must be declarative YAML, TOML, or JSON IR files inside the configured root.")
+      responder, resolver, nets, valid = method(:respond), method(:resolve), method(:inspect_nets), method(:valid_circuit)
+      path_schema = { type: "object", properties: { path: { type: "string", minLength: 1 } },
+                      required: ["path"], additionalProperties: false }
+      result.define_tool(name: "breadkit_resolve", description: "Resolve a circuit and report its parts, wiring, and diagnostics.",
+                         input_schema: path_schema, annotations: read_only_annotations) do |path:|
+        responder.call { resolver.call(path) }
+      end
+      result.define_tool(name: "breadkit_nets", description: "List the resolved electrical nets and potentials of a circuit.",
+                         input_schema: { type: "object", properties: path_schema[:properties].merge(state: { type: "string" }),
+                                         required: ["path"], additionalProperties: false }, annotations: read_only_annotations) do |path:, state: nil|
+        responder.call { nets.call(path, state) }
+      end
+      result.define_tool(name: "breadkit_ir", description: "Export a valid circuit as Breadkit JSON IR.",
+                         input_schema: path_schema, annotations: read_only_annotations) do |path:|
+        responder.call { valid.call(path).to_ir }
+      end
+      result
+    end
+
+    def read_only_annotations
+      { read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false }
+    end
+
+    def respond
+      value = yield
+      MCP::Tool::Response.new([{ type: "text", text: JSON.generate(value) }], structured_content: value)
+    rescue StandardError => e
+      MCP::Tool::Response.new([{ type: "text", text: e.message }], error: true)
+    end
+
+    def resolve(path)
+      circuit = load_circuit(path)
+      { valid: circuit.diagnostics.none? { |item| item.severity == "error" }, title: circuit.title,
+        boards: board_summary(circuit), components: circuit.components.keys, wires: circuit.wires.length,
+        supplies: circuit.supplies.map(&:name), diagnostics: circuit.diagnostics.map { |item| diagnostic_data(item) } }
+    end
+
+    def inspect_nets(path, state_name)
+      circuit = valid_circuit(path)
+      state = circuit.state(state_name) unless state_name == "base"
+      { state: state_name || "base", nets: circuit.nets(state).map do |net|
+        { name: net.name, members: net.members, holes: net.holes, potential: net.potential }
+      end }
+    end
+
+    def valid_circuit(path)
+      circuit = load_circuit(path)
+      errors = circuit.diagnostics.select { |item| item.severity == "error" }
+      raise DSLError, errors.map(&:message).join("; ") unless errors.empty?
+
+      circuit
+    end
+
+    def load_circuit(path)
+      file = circuit_path(path)
+      return IR::Reader.new.read_file(file) if file.end_with?(".json")
+
+      document = StructuredInput.load_file(file)
+      (document.part_paths + document.board_paths).each { |dependency| checked_path(dependency) }
+      PartLock.verify(document, file)
+      Resolver.new.call(document)
+    end
+
+    def circuit_path(path)
+      raise ArgumentError, "path must be text" unless path.is_a?(String) && !path.empty?
+      raise ArgumentError, "MCP accepts only YAML, TOML, or JSON IR circuit files" unless EXTENSIONS.any? { |extension| path.end_with?(extension) }
+
+      file = checked_path(path)
+      unless EXTENSIONS.any? { |extension| file.end_with?(extension) }
+        raise ArgumentError, "MCP accepts only YAML, TOML, or JSON IR circuit files"
+      end
+      file
+    end
+
+    def checked_path(path)
+      expanded = File.expand_path(path, @root)
+      raise ArgumentError, "path is outside the MCP root" unless inside_root?(expanded)
+
+      real = File.realpath(expanded)
+      raise ArgumentError, "path is outside the MCP root" unless inside_root?(real)
+      raise ArgumentError, "path must be a file" unless File.file?(real)
+      raise ArgumentError, "input file exceeds 8 MiB" if File.size(real) > MAX_INPUT_BYTES
+
+      real
+    end
+
+    def inside_root?(path)
+      prefix = @root == File::SEPARATOR ? @root : "#{@root}#{File::SEPARATOR}"
+      path.start_with?(prefix)
+    end
+
+    def board_summary(circuit)
+      if circuit.multi_board?
+        circuit.boards.map { |name, board| { name: name, type: board.definition.id } }
+      else
+        [{ type: circuit.board.definition.id }]
+      end
+    end
+
+    def diagnostic_data(item)
+      location = item.location && { path: item.location.path, line: item.location.line }
+      { code: item.code, severity: item.severity, message: item.message, targets: item.targets, location: location }
+    end
+  end
+end

data/lib/breadkit/model.rb

@@ -1,31 +1,73 @@
 # frozen_string_literal: true
 
 module Breadkit
+  module Geometry
+    def self.transform(offset, rotate: 0, mirror: false)
+      x, y = offset
+      x = -x if mirror
+      case rotate
+      when 90 then [-y, x]
+      when 180 then [-x, -y]
+      when 270 then [y, -x]
+      else [x, y]
+      end
+    end
+  end
+
   SourceLocation = Struct.new(:path, :line, keyword_init: true)
   Diagnostic = Data.define(:code, :severity, :message, :location, :targets)
   Hole = Struct.new(:id, :kind, :row, :col, :rail, :x, :y, :strip_id, keyword_init: true)
   Strip = Struct.new(:id, :hole_ids, keyword_init: true)
   Pin = Struct.new(:name, :number, :hole_id, :node_id, :role, keyword_init: true)
-  Component = Struct.new(:ref, :part, :value, :attrs, :pins, :unused, :location, keyword_init: true) do
+  Component = Struct.new(:ref, :part, :value, :attrs, :pins, :unused, :location, :step, keyword_init: true) do
     def pin(reference)
       definition = part.pin(reference)
       pins[(definition["name"] || definition["num"]).to_s] if definition
     end
+
+    def provided_sources
+      Array(part.data["provides"]).select do |source|
+        (source["when"] || {}).all? do |key, expected|
+          actual = attrs.key?(key.to_sym) ? attrs[key.to_sym] : attrs[key]
+          !actual.nil? && actual.to_s == expected.to_s
+        end
+      end
+    end
+
+    def body_bounds(board)
+      render = part.data["render"] || {}
+      return unless render["size_mm"]
+
+      holes = pins.values.filter_map { |pin| board.hole(pin.hole_id) if pin.hole_id }
+      return if holes.empty?
+
+      width, height = render.fetch("size_mm").map { |value| Float(value) / 2.54 }
+      offset = (render["body_offset_mm"] || [0, 0]).map { |value| Float(value) / 2.54 }
+      rotate = attrs[:rotate] || 0
+      offset_x, offset_y = Geometry.transform(offset, rotate: rotate, mirror: attrs[:mirror] == true)
+      width, height = height, width if [90, 270].include?(rotate)
+      center_x = (holes.map(&:x).min + holes.map(&:x).max) / 2.0 + offset_x
+      center_y = (holes.map(&:y).min + holes.map(&:y).max) / 2.0 + offset_y
+      [center_x - width / 2, center_y - height / 2, width, height]
+    end
   end
-  Wire = Struct.new(:id, :from, :to, :color, :route, :layer, :electrical, :dashed, :location, keyword_init: true)
-  Supply = Struct.new(:name, :voltage, :plus, :minus, :location, keyword_init: true)
-  Label = Struct.new(:name, :at, :location, keyword_init: true)
+  Wire = Struct.new(:id, :from, :to, :color, :route, :layer, :electrical, :dashed, :location, :step, keyword_init: true)
+  Supply = Struct.new(:name, :voltage, :plus, :minus, :location, :isolated, :voltage_range, :current_limit, :step, keyword_init: true)
+  Label = Struct.new(:name, :at, :location, :step, keyword_init: true)
   Net = Struct.new(:name, :members, :holes, :labels, :potential, keyword_init: true)
 
   class Document
     attr_accessor :title, :board, :supplies, :labels, :components, :wires, :expectations,
-                  :lint_disables, :part_paths, :part_definitions, :board_paths, :board_definitions
+                  :lint_disables, :part_paths, :part_definitions, :board_paths, :board_definitions, :diagnostics, :source_root, :steps, :boards
 
     def initialize
       @title = nil
       @board = { type: "full", options: {} }
       @supplies, @labels, @components, @wires = [], [], [], []
       @expectations, @lint_disables, @part_paths, @part_definitions, @board_paths, @board_definitions = [], [], [], [], [], []
+      @steps = []
+      @boards = []
+      @diagnostics = []
     end
   end
 end

data/lib/breadkit/part_library.rb

@@ -1,16 +1,77 @@
 # frozen_string_literal: true
 
+require "uri"
+
 module Breadkit
   class PartDef
     attr_reader :data
 
+    KEYS = %w[id aliases category placement pins polarity footprint footprint_mm internal switch independent_switches same_strip_ok straddle package render flags supply_range transistor_polarity attributes required_attributes provides extends override max_reverse_voltage forward_voltage on_resistance max_forward_current max_lead_span_mm datasheet_url].freeze
+    PIN_KEYS = %w[num name aliases type role label max_voltage max_current output_capable mount].freeze
+
     def initialize(data)
+      if data["pins"].is_a?(Array)
+        data = data.merge("pins" => data["pins"].map do |pin|
+          next pin unless pin.is_a?(Hash) && pin.key?("role")
+          raise ArgumentError, "part #{data['id']} pin #{pin['num']} has both type and role" if pin.key?("type")
+          pin.merge("type" => pin["role"]).reject { |key, _value| key == "role" }
+        end)
+      end
       @data = data
+      unknown = data.keys - KEYS
+      raise ArgumentError, "part #{data['id']} has unknown keys: #{unknown.join(', ')}" unless unknown.empty?
       raise ArgumentError, "part definition needs an id" unless data["id"]
       raise ArgumentError, "part #{data['id']} needs pins" unless data["pins"].is_a?(Array)
+      if data.key?("datasheet_url")
+        valid_url = begin
+          url = data["datasheet_url"]
+          parsed = URI.parse(url) if url.is_a?(String)
+          parsed.is_a?(URI::HTTPS) && !parsed.host.to_s.empty? && !parsed.userinfo
+        rescue URI::InvalidURIError
+          false
+        end
+        raise ArgumentError, "part #{id} has invalid datasheet_url" unless valid_url
+      end
+      if data.key?("attributes")
+        attributes = data["attributes"]
+        unless attributes.is_a?(Hash) && attributes.all? { |key, schema| key.is_a?(String) &&
+                 (schema == "css_color" || (schema.is_a?(Array) && !schema.empty? && schema.all? { |value| value.is_a?(String) || value.is_a?(Numeric) })) }
+          raise ArgumentError, "part #{id} has invalid attributes schema"
+        end
+      end
+      if data.key?("required_attributes")
+        required = data["required_attributes"]
+        unless required.is_a?(Array) && required.uniq.length == required.length &&
+               required.all? { |key| key.is_a?(String) && data.fetch("attributes", {}).key?(key) }
+          raise ArgumentError, "part #{id} has invalid required_attributes"
+        end
+      end
       identities = {}
       pins.each_with_index do |pin, index|
         raise ArgumentError, "part #{id} has invalid pin" unless pin.is_a?(Hash) && pin["num"]
+        unknown_pin_keys = pin.keys - PIN_KEYS
+        raise ArgumentError, "part #{id} has unknown pin keys: #{unknown_pin_keys.join(', ')}" unless unknown_pin_keys.empty?
+        role = pin["type"]
+        if role && !%w[input output gpio power ground data clock interrupt address nc passive analog reset open_drain].include?(role.to_s)
+          raise ArgumentError, "part #{id} pin #{pin['num']} has invalid type #{role}"
+        end
+        raise ArgumentError, "part #{id} pin #{pin['num']} has invalid mount" if pin.key?("mount") && pin["mount"] != "rail"
+        unless !pin.key?("label") || pin["label"].is_a?(String) || [true, false].include?(pin["label"])
+          raise ArgumentError, "part #{id} pin #{pin['num']} has invalid label"
+        end
+        if pin.key?("max_voltage")
+          voltage = pin["max_voltage"]
+          raise ArgumentError, "part #{id} pin #{pin['num']} has invalid max_voltage" unless voltage.is_a?(Numeric) && voltage.finite? && voltage.positive?
+        end
+        if pin.key?("max_current")
+          current = pin["max_current"]
+          unless current.is_a?(Numeric) && current.real? && current.finite? && current.positive?
+            raise ArgumentError, "part #{id} pin #{pin['num']} has invalid max_current"
+          end
+        end
+        if pin.key?("output_capable") && ![true, false].include?(pin["output_capable"])
+          raise ArgumentError, "part #{id} pin #{pin['num']} has invalid output_capable"
+        end
 
         ([pin["num"], pin["name"]] + Array(pin["aliases"])).compact.each do |identity|
           key = identity.to_s.downcase
@@ -25,18 +86,82 @@ module Breadkit
           raise ArgumentError, "part #{id} has invalid #{key} pin pair #{pair.inspect}" unless pair.length == 2 && pair.all? { |pin| valid_pins.include?(pin.to_s) }
         end
       end
+      if data.key?("independent_switches")
+        pairs = Array(data["switch"])
+        terminals = pairs.flatten.map { |reference| pin(reference).fetch("num").to_s }
+        unless data["independent_switches"] == true && !pairs.empty? && terminals.uniq.length == terminals.length
+          raise ArgumentError, "part #{id} has invalid independent_switches; contacts must use distinct pins"
+        end
+      end
       raise ArgumentError, "part #{id} has invalid placement" unless %w[leads dip footprint offboard].include?(placement)
+      if data.key?("max_lead_span_mm")
+        limit = data["max_lead_span_mm"]
+        unless placement == "leads" && pins.length == 2 && limit.is_a?(Numeric) && limit.real? && limit.finite? && limit.positive?
+          raise ArgumentError, "part #{id} has invalid max_lead_span_mm"
+        end
+      end
+      if data["render"]
+        render = data["render"]
+        unknown_render = render.is_a?(Hash) ? render.keys - %w[shape label size_mm body_offset_mm fill stroke text_color svg] : []
+        unless render.is_a?(Hash) && unknown_render.empty? && (!render.key?("shape") || render["shape"].is_a?(String)) &&
+               (!render.key?("label") || render["label"].is_a?(String)) &&
+               (!render.key?("svg") || render["svg"].is_a?(String)) &&
+               %w[fill stroke text_color].all? { |key| !render.key?(key) || Color.valid?(render[key]) }
+          raise ArgumentError, "part #{id} has invalid render options#{": #{unknown_render.join(', ')}" unless unknown_render.empty?}"
+        end
+        if render.key?("size_mm") && !valid_mm_pair?(render["size_mm"], positive: true)
+          raise ArgumentError, "part #{id} module rendering needs positive size_mm [width, height]"
+        end
+        if render.key?("body_offset_mm") && !valid_mm_pair?(render["body_offset_mm"], positive: false)
+          raise ArgumentError, "part #{id} module rendering needs finite body_offset_mm [x, y]"
+        end
+      end
       if data["polarity"]
-        unless data["polarity"].is_a?(Hash) && data["polarity"].values.all? { |name| identities.key?(name.to_s.downcase) }
+        unless data["polarity"].is_a?(Hash) && (data["polarity"].keys - %w[positive negative]).empty? &&
+               data["polarity"].values.all? { |name| identities.key?(name.to_s.downcase) }
           raise ArgumentError, "part #{id} has invalid polarity pin reference"
         end
       end
+      if data.key?("max_reverse_voltage")
+        limit = data["max_reverse_voltage"]
+        raise ArgumentError, "part #{id} has invalid max_reverse_voltage" unless limit.is_a?(Numeric) && limit.finite? && limit >= 0
+      end
+      %w[forward_voltage on_resistance max_forward_current].each do |key|
+        next unless data.key?(key)
+
+        value = data[key]
+        raise ArgumentError, "part #{id} has invalid #{key}" unless value.is_a?(Numeric) && value.finite? && value.positive?
+      end
+      Array(data["provides"]).each do |source|
+        unless source.is_a?(Hash) && %w[positive negative voltage].all? { |key| source.key?(key) } &&
+               (source.keys - %w[positive negative voltage when]).empty? &&
+               %w[positive negative].all? { |key| identities.key?(source[key].to_s.downcase) } &&
+               source["voltage"].is_a?(Numeric) && source["voltage"].finite? && source["voltage"].positive?
+          raise ArgumentError, "part #{id} has invalid voltage source"
+        end
+        conditions = source["when"]
+        if conditions && (!conditions.is_a?(Hash) || conditions.empty? || conditions.any? do |key, value|
+          choices = data.fetch("attributes", {})[key]
+          !choices.is_a?(Array) || !choices.include?(value)
+        end)
+          raise ArgumentError, "part #{id} has invalid voltage source condition"
+        end
+      end
       if data["footprint"]
         numbers = pins.map { |pin| pin.fetch("num").to_s }
         unless data["footprint"].is_a?(Hash) && data["footprint"].all? { |key, offset| numbers.include?(key.to_s) && offset.is_a?(Array) && offset.length == 2 && offset.all? { |value| value.is_a?(Integer) } }
           raise ArgumentError, "part #{id} has invalid footprint pin reference or offset"
         end
       end
+      if data.key?("footprint_mm")
+        offsets = data["footprint_mm"]
+        numbers = pins.map { |pin| pin.fetch("num").to_s }
+        raise ArgumentError, "part #{id} cannot set both footprint_mm and footprint" if data.key?("footprint")
+        unless placement == "footprint" && offsets.is_a?(Hash) && offsets.keys.sort == numbers.sort &&
+               offsets.values.all? { |pair| pair.is_a?(Array) && pair.length == 2 && pair.all? { |value| grid_offset_mm?(value) } }
+          raise ArgumentError, "part #{id} has invalid footprint_mm; pin offsets must align to 2.54 mm holes"
+        end
+      end
       if data.dig("render", "shape") == "module"
         size_mm = data.dig("render", "size_mm")
         raise ArgumentError, "part #{id} module rendering needs positive size_mm [width, height]" unless valid_mm_pair?(size_mm, positive: true)
@@ -59,6 +184,16 @@ module Breadkit
       data.fetch("placement", "leads")
     end
 
+    def max_lead_span_mm
+      data["max_lead_span_mm"]&.to_f
+    end
+
+    def footprint
+      return data["footprint"] if data.key?("footprint")
+
+      data["footprint_mm"]&.transform_values { |pair| pair.map { |value| (value / 2.54).round } }
+    end
+
     def pin(value)
       key = value.to_s.downcase
       pins.find do |pin|
@@ -68,6 +203,11 @@ module Breadkit
 
     private
 
+    def grid_offset_mm?(value)
+      value.is_a?(Numeric) && value.real? && value.finite? &&
+        ((value / 2.54) - (value / 2.54).round).abs < 1e-6
+    end
+
     def valid_mm_pair?(values, positive:)
       values.is_a?(Array) && values.length == 2 && values.all? do |value|
         number = Float(value)
@@ -79,13 +219,26 @@ module Breadkit
   end
 
   class PartLibrary
+    attr_reader :warnings
+
     def initialize(extra_paths: [], extra_definitions: [])
-      paths = Dir.glob(File.expand_path("../../data/parts/*.yml", __dir__))
-      paths.concat(extra_paths.flat_map { |path| Dir.glob(path) })
+      builtin_paths = Dir.glob(File.expand_path("../../data/parts/*.yml", __dir__))
+      paths = builtin_paths + extra_paths.flat_map { |path| Dir.glob(path) }
       definitions = paths.uniq.map { |path| YAML.safe_load(File.read(path, encoding: "UTF-8"), aliases: false) }
       definitions.concat(extra_definitions)
       @parts = {}
+      @warnings = []
       definitions.each do |data|
+        if data["extends"]
+          parent = @parts[data["extends"].to_s.downcase]
+          raise ArgumentError, "unknown parent part #{data['extends']}" unless parent
+          data = parent.data.merge("aliases" => []).merge(data)
+        end
+        existing = @parts[data["id"].to_s.downcase]
+        if existing && (data["override"] || data["extends"])
+          @parts.delete_if { |_key, item| item == existing }
+          @warnings << "part #{data['id']} overrides #{existing.id}"
+        end
         part = PartDef.new(data)
         ([part.id] + Array(data["aliases"])).each do |name|
           key = name.to_s.downcase

data/lib/breadkit/part_lock.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "digest"
+require "pathname"
+
+module Breadkit
+  # Pins local part and board definition files used by a circuit.
+  class PartLock
+    FORMAT = 1
+    SUFFIXES = %w[.bk.rb .bk.yml .bk.yaml .bk.toml].freeze
+
+    def self.write(path)
+      circuit_path = File.expand_path(path)
+      raise ArgumentError, "lock supports .bk.rb, .bk.yml, .bk.yaml, and .bk.toml circuits" unless circuit_file?(circuit_path)
+
+      document = if circuit_path.end_with?(".bk.rb")
+        DSL.load_file(circuit_path)
+      else
+        StructuredInput.load_file(circuit_path)
+      end
+      file = lock_path(circuit_path)
+      data = File.file?(file) ? read(file) : { "version" => FORMAT, "circuits" => {} }
+      data.fetch("circuits")[File.basename(circuit_path)] = entry(document, circuit_path)
+      data["circuits"] = data.fetch("circuits").sort.to_h
+      File.write(file, "#{JSON.pretty_generate(data)}\n")
+      file
+    end
+
+    def self.verify(document, path)
+      circuit_path = File.expand_path(path)
+      return unless circuit_file?(circuit_path)
+
+      file = lock_path(circuit_path)
+      return unless File.file?(file)
+
+      expected = read(file).fetch("circuits")[File.basename(circuit_path)]
+      raise DSLError, "breadkit.lock has no entry for #{File.basename(circuit_path)}; run breadkit lock FILE" unless expected
+      raise DSLError, "breadkit.lock version mismatch for #{File.basename(circuit_path)}; run breadkit lock FILE" unless expected.fetch("breadkit") == VERSION
+
+      current = entry(document, circuit_path)
+      %w[parts boards].each do |kind|
+        saved, actual = expected.fetch(kind), current.fetch(kind)
+        saved_paths, actual_paths = saved.map { |item| item.fetch("path") }, actual.map { |item| item.fetch("path") }
+        raise DSLError, "breadkit.lock definition set changed for #{kind}; run breadkit lock FILE" unless saved_paths == actual_paths
+
+        saved.zip(actual).each do |before, after|
+          next if before.fetch("sha256") == after.fetch("sha256")
+
+          raise DSLError, "breadkit.lock checksum mismatch for #{after.fetch('path')}; run breadkit lock FILE"
+        end
+      end
+    end
+
+    def self.lock_path(path)
+      File.join(File.dirname(File.expand_path(path)), "breadkit.lock")
+    end
+
+    def self.circuit_file?(path)
+      SUFFIXES.any? { |suffix| path.end_with?(suffix) }
+    end
+    private_class_method :circuit_file?
+
+    def self.entry(document, path)
+      base = Pathname.new(File.dirname(path))
+      { "breadkit" => VERSION, "parts" => records(document.part_paths, base),
+        "boards" => records(document.board_paths, base) }
+    end
+    private_class_method :entry
+
+    def self.records(paths, base)
+      paths.uniq.map do |path|
+        absolute = Pathname.new(File.expand_path(path))
+        { "path" => absolute.relative_path_from(base).to_s.tr("\\", "/"), "sha256" => Digest::SHA256.file(absolute).hexdigest }
+      rescue ArgumentError
+        raise DSLError, "local definitions must share a filesystem with the circuit"
+      end.sort_by { |item| item.fetch("path") }
+    end
+    private_class_method :records
+
+    def self.read(path)
+      raise DSLError, "invalid breadkit.lock: file exceeds 1 MiB" if File.size(path) > 1024 * 1024
+
+      data = JSON.parse(File.read(path, encoding: "UTF-8"))
+      unless data.is_a?(Hash) && data.keys.sort == %w[circuits version] && data["version"] == FORMAT && data["circuits"].is_a?(Hash)
+        raise DSLError, "invalid breadkit.lock: unsupported format"
+      end
+      data.fetch("circuits").each_value do |item|
+        unless item.is_a?(Hash) && item.keys.sort == %w[boards breadkit parts] && item["breadkit"].is_a?(String) &&
+               %w[parts boards].all? { |key| valid_records?(item[key]) }
+          raise DSLError, "invalid breadkit.lock: malformed circuit entry"
+        end
+      end
+      data
+    rescue JSON::ParserError => e
+      raise DSLError, "invalid breadkit.lock: #{e.message}"
+    end
+    private_class_method :read
+
+    def self.valid_records?(items)
+      items.is_a?(Array) && items.all? do |item|
+        item.is_a?(Hash) && item.keys.sort == %w[path sha256] && item["path"].is_a?(String) &&
+          !item["path"].empty? && item["sha256"].is_a?(String) && item["sha256"].match?(/\A[0-9a-f]{64}\z/)
+      end
+    end
+    private_class_method :valid_records?
+  end
+end

data/lib/breadkit/patterns.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Breadkit
+  module Patterns
+    module_function
+
+    def call(circuit)
+      return [] if circuit.diagnostics.any? { |item| item.severity == "error" }
+
+      voltage_divider(circuit) + ne555_astable(circuit)
+    end
+
+    def voltage_divider(circuit)
+      return [] if circuit.diagnostics.any? { |item| item.severity == "error" }
+      return [] unless circuit.supplies.length == 1 && circuit.components.length == 2
+
+      supply = circuit.supplies.first
+      return [] if supply.voltage_range || !supply.voltage.to_f.positive?
+
+      resistors = circuit.components.values
+      return [] unless resistors.all? { |component| component.part.id == "resistor" &&
+                                         component.pins.length == 2 && Value.parse(component.value).positive? }
+
+      ends = resistors.map do |component|
+        [1, 2].map { |pin| circuit.net_of("#{component.ref}.#{pin}")&.name }
+      end
+      return [] if ends.flatten.any?(&:nil?) || ends.any? { |pair| pair.uniq.length != 2 }
+
+      plus = circuit.net_of(supply.plus)&.name
+      minus = circuit.net_of(supply.minus)&.name
+      shared = ends[0] & ends[1]
+      return [] unless plus && minus && plus != minus && shared.length == 1
+
+      midpoint = shared.first
+      return [] if [plus, minus].include?(midpoint)
+
+      top, bottom = resistors.zip(ends).partition { |_component, pair| pair.include?(plus) }
+      return [] unless top.length == 1 && bottom.length == 1 && bottom.first[1].include?(minus)
+
+      result = circuit.dc_analysis
+      return [] unless result.success? && result.voltages.key?(midpoint) && result.voltages.key?(minus)
+
+      voltage = result.voltages.fetch(midpoint) - result.voltages.fetch(minus)
+      [{ "kind" => "voltage_divider", "supply" => supply.name,
+         "top_resistor" => top.first[0].ref, "bottom_resistor" => bottom.first[0].ref,
+         "midpoint_net" => midpoint, "midpoint_voltage_v" => voltage,
+         "reference" => "#{supply.name}.-",
+         "explanation" => "Two resistors form an unloaded voltage divider. The nominal midpoint voltage is relative to the supply negative terminal." }]
+    rescue ArgumentError, TypeError
+      []
+    end
+
+    def ne555_astable(circuit)
+      return [] unless circuit.supplies.length == 1 && circuit.components.length == 8
+
+      parts = circuit.components.values.group_by { |component| component.part.id }
+      return [] unless %w[ne555 resistor capacitor electrolytic led].all? { |id| parts.key?(id) }
+      return [] unless %w[ne555 resistor capacitor electrolytic led].map { |id| parts.fetch(id).length } == [1, 3, 2, 1, 1]
+
+      timer = parts.fetch("ne555").first
+      supply = circuit.supplies.first
+      voltage = supply.voltage.to_f
+      minimum, maximum = Array(timer.part.data["supply_range"])
+      return [] unless supply.voltage_range.nil? && minimum && maximum && voltage.between?(minimum, maximum)
+
+      plus = circuit.net_of(supply.plus)&.name
+      minus = circuit.net_of(supply.minus)&.name
+      pins = (1..8).to_h { |number| [number, terminal_net(circuit, timer, number)] }
+      return [] if [plus, minus, *pins.values].any?(&:nil?)
+      return [] unless pins[1] == minus && pins[4] == plus && pins[8] == plus && pins[2] == pins[6]
+
+      discharge, timing, output, control = pins.values_at(7, 2, 3, 5)
+      return [] unless [plus, minus, discharge, timing, output, control].uniq.length == 6
+
+      led = parts.fetch("led").first
+      led_anode = terminal_net(circuit, led, "anode")
+      return [] unless terminal_net(circuit, led, "cathode") == minus && led_anode &&
+                       ![plus, minus, discharge, timing, output, control].include?(led_anode)
+
+      resistors = parts.fetch("resistor")
+      capacitors = parts.fetch("capacitor") + parts.fetch("electrolytic")
+      return [] unless (resistors + capacitors).all? { |part| Value.parse(part.value).positive? }
+
+      charge = between(circuit, resistors, plus, discharge)
+      discharge_resistor = between(circuit, resistors, discharge, timing)
+      output_resistor = between(circuit, resistors, output, led_anode)
+      control_capacitor = between(circuit, capacitors, control, minus)
+      bypass_capacitor = between(circuit, capacitors, plus, minus)
+      timing_capacitor = between(circuit, capacitors, timing, minus)
+      return [] unless [charge, discharge_resistor, output_resistor, control_capacitor,
+                        bypass_capacitor, timing_capacitor].all?
+      return [] unless control_capacitor.part.id == "capacitor" && bypass_capacitor.part.id == "capacitor" &&
+                       timing_capacitor.part.id == "electrolytic"
+      return [] unless terminal_net(circuit, timing_capacitor, 1) == timing &&
+                       terminal_net(circuit, timing_capacitor, 2) == minus
+
+      [{ "kind" => "ne555_astable_wiring", "timer" => timer.ref, "supply" => supply.name,
+         "charge_resistor" => charge.ref, "discharge_resistor" => discharge_resistor.ref,
+         "timing_capacitor" => timing_capacitor.ref, "output_resistor" => output_resistor.ref,
+         "output_led" => led.ref, "control_capacitor" => control_capacitor.ref,
+         "bypass_capacitor" => bypass_capacitor.ref,
+         "datasheet" => "https://www.ti.com/lit/ds/symlink/ne555.pdf",
+         "explanation" => "This wiring matches the NE555 astable connection with an LED output load; this is not a simulation of oscillation or timing." }]
+    rescue ArgumentError, TypeError
+      []
+    end
+
+    def terminal_net(circuit, component, pin)
+      circuit.net_of("#{component.ref}.#{pin}")&.name
+    end
+
+    def between(circuit, components, first, second)
+      components.find do |component|
+        ends = [1, 2].map { |pin| terminal_net(circuit, component, pin) }
+        ends.all? && ends.sort == [first, second].sort
+      end
+    end
+  end
+end