lex-agentic-language 0.1.0

data/spec/legion/extensions/agentic/language/frame_semantics/helpers/frame_spec.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::FrameSemantics::Helpers::Frame do
+  subject(:frame) { described_class.new(name: :commercial_transaction, domain: :commerce) }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(frame.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets name and domain' do
+      expect(frame.name).to eq(:commercial_transaction)
+      expect(frame.domain).to eq(:commerce)
+    end
+
+    it 'starts with default activation' do
+      expect(frame.activation).to eq(Legion::Extensions::Agentic::Language::FrameSemantics::Helpers::DEFAULT_ACTIVATION)
+    end
+
+    it 'starts with zero activation_count' do
+      expect(frame.activation_count).to eq(0)
+    end
+
+    it 'starts with empty slots and relations' do
+      expect(frame.slots).to be_empty
+      expect(frame.relations).to be_empty
+    end
+  end
+
+  describe '#add_slot' do
+    it 'adds a core slot by default' do
+      frame.add_slot(name: :buyer)
+      expect(frame.slots[:buyer][:type]).to eq(:core)
+      expect(frame.slots[:buyer][:required]).to be true
+      expect(frame.slots[:buyer][:filler]).to be_nil
+    end
+
+    it 'adds a peripheral slot when specified' do
+      frame.add_slot(name: :payment_method, slot_type: :peripheral, required: false)
+      expect(frame.slots[:payment_method][:type]).to eq(:peripheral)
+      expect(frame.slots[:payment_method][:required]).to be false
+    end
+
+    it 'returns self for chaining' do
+      result = frame.add_slot(name: :seller)
+      expect(result).to be(frame)
+    end
+  end
+
+  describe '#fill_slot' do
+    before { frame.add_slot(name: :buyer) }
+
+    it 'fills a slot and returns true' do
+      result = frame.fill_slot(name: :buyer, filler: 'Alice')
+      expect(result).to be true
+      expect(frame.slots[:buyer][:filler]).to eq('Alice')
+    end
+
+    it 'boosts activation when slot is filled' do
+      initial = frame.activation
+      frame.fill_slot(name: :buyer, filler: 'Alice')
+      expect(frame.activation).to be > initial
+    end
+
+    it 'returns false for unknown slot' do
+      expect(frame.fill_slot(name: :unknown, filler: 'x')).to be false
+    end
+  end
+
+  describe '#clear_slot' do
+    before do
+      frame.add_slot(name: :buyer)
+      frame.fill_slot(name: :buyer, filler: 'Alice')
+    end
+
+    it 'clears the slot filler' do
+      frame.clear_slot(name: :buyer)
+      expect(frame.slots[:buyer][:filler]).to be_nil
+    end
+
+    it 'returns true for existing slot' do
+      expect(frame.clear_slot(name: :buyer)).to be true
+    end
+
+    it 'returns false for unknown slot' do
+      expect(frame.clear_slot(name: :ghost)).to be false
+    end
+  end
+
+  describe '#core_slots' do
+    before do
+      frame.add_slot(name: :buyer, slot_type: :core)
+      frame.add_slot(name: :seller, slot_type: :core)
+      frame.add_slot(name: :note, slot_type: :peripheral)
+    end
+
+    it 'returns only core slots' do
+      expect(frame.core_slots.keys).to contain_exactly(:buyer, :seller)
+    end
+  end
+
+  describe '#filled_slots' do
+    before do
+      frame.add_slot(name: :buyer)
+      frame.add_slot(name: :seller)
+      frame.fill_slot(name: :buyer, filler: 'Alice')
+    end
+
+    it 'returns only filled slots' do
+      expect(frame.filled_slots.keys).to eq([:buyer])
+    end
+  end
+
+  describe '#completion_ratio' do
+    it 'returns 0.0 with no slots' do
+      expect(frame.completion_ratio).to eq(0.0)
+    end
+
+    it 'returns correct fraction of filled core slots' do
+      frame.add_slot(name: :buyer)
+      frame.add_slot(name: :seller)
+      frame.add_slot(name: :goods)
+      frame.fill_slot(name: :buyer, filler: 'Alice')
+      expect(frame.completion_ratio).to be_within(0.001).of(1.0 / 3.0)
+    end
+
+    it 'ignores peripheral slots in ratio' do
+      frame.add_slot(name: :buyer, slot_type: :core)
+      frame.add_slot(name: :note, slot_type: :peripheral)
+      frame.fill_slot(name: :buyer, filler: 'Alice')
+      expect(frame.completion_ratio).to eq(1.0)
+    end
+  end
+
+  describe '#complete?' do
+    it 'returns false when completion is below threshold' do
+      frame.add_slot(name: :buyer)
+      frame.add_slot(name: :seller)
+      frame.add_slot(name: :goods)
+      frame.fill_slot(name: :buyer, filler: 'Alice')
+      expect(frame.complete?).to be false
+    end
+
+    it 'returns true when all core slots are filled' do
+      frame.add_slot(name: :buyer)
+      frame.fill_slot(name: :buyer, filler: 'Alice')
+      expect(frame.complete?).to be true
+    end
+  end
+
+  describe '#activate!' do
+    it 'boosts activation and increments count' do
+      initial = frame.activation
+      frame.activate!
+      expect(frame.activation).to be > initial
+      expect(frame.activation_count).to eq(1)
+    end
+
+    it 'clamps activation at 1.0' do
+      10.times { frame.activate! }
+      expect(frame.activation).to eq(1.0)
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces activation' do
+      initial = frame.activation
+      frame.decay!
+      expect(frame.activation).to be < initial
+    end
+
+    it 'clamps activation at 0.0' do
+      100.times { frame.decay! }
+      expect(frame.activation).to eq(0.0)
+    end
+  end
+
+  describe '#activation_label' do
+    it 'returns :dominant for high activation' do
+      10.times { frame.activate! }
+      expect(frame.activation_label).to eq(:dominant)
+    end
+
+    it 'returns :inactive for very low activation' do
+      100.times { frame.decay! }
+      expect(frame.activation_label).to eq(:inactive)
+    end
+
+    it 'returns :primed for mid activation around 0.5' do
+      frame.instance_variable_set(:@activation, 0.5)
+      expect(frame.activation_label).to eq(:primed)
+    end
+  end
+
+  describe '#add_relation' do
+    it 'appends a relation entry' do
+      other_id = SecureRandom.uuid
+      frame.add_relation(relation: :inherits_from, target_frame_id: other_id)
+      expect(frame.relations.size).to eq(1)
+      expect(frame.relations.first[:relation]).to eq(:inherits_from)
+      expect(frame.relations.first[:target_frame_id]).to eq(other_id)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      h = frame.to_h
+      expect(h).to include(:id, :name, :domain, :slots, :relations,
+                           :activation, :activation_label, :activation_count,
+                           :completion_ratio, :complete, :created_at)
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/frame_semantics/runners/frame_semantics_spec.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/language/frame_semantics/helpers/client'
+
+RSpec.describe Legion::Extensions::Agentic::Language::FrameSemantics::Runners::FrameSemantics do
+  let(:client) { Legion::Extensions::Agentic::Language::FrameSemantics::Helpers::Client.new }
+
+  describe '#create_semantic_frame' do
+    it 'creates a frame and returns its id' do
+      result = client.create_semantic_frame(name: :commercial_transaction, domain: :commerce)
+      expect(result[:created]).to be true
+      expect(result[:frame_id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:name]).to eq(:commercial_transaction)
+    end
+  end
+
+  describe '#define_frame_slot' do
+    let(:frame_id) { client.create_semantic_frame(name: :motion, domain: :physics)[:frame_id] }
+
+    it 'adds a slot to a known frame' do
+      result = client.define_frame_slot(frame_id: frame_id, name: :mover)
+      expect(result[:defined]).to be true
+      expect(result[:slot_name]).to eq(:mover)
+    end
+
+    it 'returns not found for unknown frame' do
+      result = client.define_frame_slot(frame_id: 'bogus', name: :mover)
+      expect(result[:defined]).to be false
+      expect(result[:reason]).to eq(:frame_not_found)
+    end
+  end
+
+  describe '#fill_frame_slot' do
+    let(:frame_id) do
+      id = client.create_semantic_frame(name: :motion, domain: :physics)[:frame_id]
+      client.define_frame_slot(frame_id: id, name: :mover)
+      id
+    end
+
+    it 'fills an existing slot' do
+      result = client.fill_frame_slot(frame_id: frame_id, slot_name: :mover, filler: 'the car')
+      expect(result[:filled]).to be true
+      expect(result[:filler]).to eq('the car')
+    end
+
+    it 'returns error for unknown slot' do
+      result = client.fill_frame_slot(frame_id: frame_id, slot_name: :nonexistent, filler: 'x')
+      expect(result[:filled]).to be false
+    end
+  end
+
+  describe '#instantiate_semantic_frame' do
+    let(:frame_id) do
+      id = client.create_semantic_frame(name: :motion, domain: :physics)[:frame_id]
+      client.define_frame_slot(frame_id: id, name: :mover)
+      client.fill_frame_slot(frame_id: id, slot_name: :mover, filler: 'rocket')
+      id
+    end
+
+    it 'creates an instance snapshot' do
+      result = client.instantiate_semantic_frame(frame_id: frame_id, context: 'test context')
+      expect(result[:instantiated]).to be true
+      expect(result[:instance_id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:filled_count]).to eq(1)
+    end
+
+    it 'returns error for unknown frame' do
+      result = client.instantiate_semantic_frame(frame_id: 'bogus', context: 'x')
+      expect(result[:instantiated]).to be false
+    end
+  end
+
+  describe '#add_frame_relation' do
+    let(:frame_id)  { client.create_semantic_frame(name: :transfer,  domain: :commerce)[:frame_id] }
+    let(:target_id) { client.create_semantic_frame(name: :payment,   domain: :commerce)[:frame_id] }
+
+    it 'adds a valid frame relation' do
+      result = client.add_frame_relation(
+        frame_id: frame_id, relation: :has_subframe, target_frame_id: target_id
+      )
+      expect(result[:added]).to be true
+    end
+
+    it 'rejects an invalid relation' do
+      result = client.add_frame_relation(
+        frame_id: frame_id, relation: :nonsense, target_frame_id: target_id
+      )
+      expect(result[:added]).to be false
+    end
+  end
+
+  describe '#activate_semantic_frame' do
+    let(:frame_id) { client.create_semantic_frame(name: :competition, domain: :sports)[:frame_id] }
+
+    it 'activates the frame' do
+      result = client.activate_semantic_frame(frame_id: frame_id)
+      expect(result[:activated]).to be true
+    end
+
+    it 'returns error for unknown frame' do
+      result = client.activate_semantic_frame(frame_id: 'bogus')
+      expect(result[:activated]).to be false
+    end
+  end
+
+  describe '#active_frames_report' do
+    it 'returns list of active frames' do
+      id = client.create_semantic_frame(name: :competition, domain: :sports)[:frame_id]
+      4.times { client.activate_semantic_frame(frame_id: id) }
+      result = client.active_frames_report
+      expect(result).to have_key(:frames)
+      expect(result).to have_key(:count)
+    end
+  end
+
+  describe '#related_frames_report' do
+    let(:frame_id)  { client.create_semantic_frame(name: :buying, domain: :commerce)[:frame_id] }
+    let(:target_id) { client.create_semantic_frame(name: :paying, domain: :commerce)[:frame_id] }
+
+    before { client.add_frame_relation(frame_id: frame_id, relation: :has_subframe, target_frame_id: target_id) }
+
+    it 'returns related frames' do
+      result = client.related_frames_report(frame_id: frame_id)
+      expect(result[:count]).to eq(1)
+      expect(result[:frames].first[:id]).to eq(target_id)
+    end
+  end
+
+  describe '#complete_frames_report' do
+    it 'returns complete frames' do
+      id = client.create_semantic_frame(name: :simple, domain: :test)[:frame_id]
+      client.define_frame_slot(frame_id: id, name: :actor)
+      client.fill_frame_slot(frame_id: id, slot_name: :actor, filler: 'someone')
+      result = client.complete_frames_report
+      expect(result[:count]).to be >= 1
+    end
+  end
+
+  describe '#update_frame_semantics' do
+    it 'runs decay and prune, returning updated status' do
+      result = client.update_frame_semantics
+      expect(result[:updated]).to be true
+      expect(result[:stats]).to have_key(:frame_count)
+    end
+  end
+
+  describe '#frame_semantics_stats' do
+    it 'returns engine stats' do
+      client.create_semantic_frame(name: :motion, domain: :physics)
+      result = client.frame_semantics_stats
+      expect(result[:frame_count]).to be >= 1
+      expect(result).to have_key(:domains)
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/grammar/client_spec.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::Grammar::Client do
+  subject(:client) { described_class.new }
+
+  describe 'runner method availability' do
+    it 'responds to create_grammar_construction' do
+      expect(client).to respond_to(:create_grammar_construction)
+    end
+
+    it 'responds to create_grammar_construal' do
+      expect(client).to respond_to(:create_grammar_construal)
+    end
+
+    it 'responds to use_grammar_construction' do
+      expect(client).to respond_to(:use_grammar_construction)
+    end
+
+    it 'responds to construals_for_scene_report' do
+      expect(client).to respond_to(:construals_for_scene_report)
+    end
+
+    it 'responds to entrenched_constructions_report' do
+      expect(client).to respond_to(:entrenched_constructions_report)
+    end
+
+    it 'responds to constructions_by_domain_report' do
+      expect(client).to respond_to(:constructions_by_domain_report)
+    end
+
+    it 'responds to most_used_constructions' do
+      expect(client).to respond_to(:most_used_constructions)
+    end
+
+    it 'responds to update_cognitive_grammar' do
+      expect(client).to respond_to(:update_cognitive_grammar)
+    end
+
+    it 'responds to cognitive_grammar_stats' do
+      expect(client).to respond_to(:cognitive_grammar_stats)
+    end
+  end
+
+  describe 'full lifecycle' do
+    let(:construction_params) do
+      { form: 'the house', meaning: 'definite dwelling', expression_type: :nominal, domain: 'architecture' }
+    end
+
+    it 'creates a construction and retrieves stats' do
+      client.create_grammar_construction(**construction_params)
+      stats = client.cognitive_grammar_stats
+      expect(stats[:constructions_count]).to eq(1)
+    end
+
+    it 'creates a construal and retrieves it by scene' do
+      client.create_grammar_construal(
+        scene: 'house on hill', perspective: 'valley', figure: 'house', ground: 'hill'
+      )
+      result = client.construals_for_scene_report(scene: 'house on hill')
+      expect(result[:count]).to eq(1)
+      expect(result[:construals].first[:figure]).to eq('house')
+    end
+
+    it 'entrenchment: construction becomes entrenched after 5 uses from default activation' do
+      created = client.create_grammar_construction(**construction_params)
+      expect(client.entrenched_constructions_report[:count]).to eq(0)
+
+      5.times { client.use_grammar_construction(construction_id: created[:id]) }
+
+      report = client.entrenched_constructions_report
+      expect(report[:count]).to eq(1)
+      expect(report[:constructions].first[:form]).to eq('the house')
+    end
+
+    it 'domain report scopes to correct domain' do
+      client.create_grammar_construction(**construction_params)
+      client.create_grammar_construction(form: 'fast', meaning: 'speed', expression_type: :relational, domain: 'motion')
+
+      result = client.constructions_by_domain_report(domain: 'architecture')
+      expect(result[:count]).to eq(1)
+      expect(result[:constructions].first[:domain]).to eq('architecture')
+    end
+
+    it 'most_used_constructions tracks usage correctly' do
+      c1 = client.create_grammar_construction(**construction_params)
+      c2 = client.create_grammar_construction(form: 'run', meaning: 'motion', expression_type: :relational,
+                                              domain: 'motion')
+
+      2.times { client.use_grammar_construction(construction_id: c1[:id]) }
+      5.times { client.use_grammar_construction(construction_id: c2[:id]) }
+
+      top = client.most_used_constructions(limit: 1)
+      expect(top[:constructions].first[:form]).to eq('run')
+    end
+
+    it 'update_cognitive_grammar decays activation' do
+      created = client.create_grammar_construction(**construction_params)
+      result  = client.update_cognitive_grammar
+      expect(result[:stats][:constructions_count]).to be >= 0
+      # After decay, activation should be lower than initial 0.3
+      engine = client.send(:engine)
+      const  = engine.instance_variable_get(:@constructions)[created[:id]]
+      expect(const.activation).to be < 0.3
+    end
+
+    it 'construal figure/ground prominence model' do
+      client.create_grammar_construal(
+        scene:       'cup on table',
+        perspective: 'human-scale',
+        figure:      'cup',
+        ground:      'table',
+        specificity: :intermediate,
+        scope:       :local
+      )
+      report = client.construals_for_scene_report(scene: 'cup on table')
+      construal_h = report[:construals].first
+      expect(construal_h[:figure]).to eq('cup')
+      expect(construal_h[:ground]).to eq('table')
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/grammar/cognitive_grammar_spec.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::Grammar do
+  it 'has a version' do
+    expect(Legion::Extensions::Agentic::Language::Grammar::VERSION).to eq('0.1.0')
+  end
+
+  it 'defines CONSTRUAL_OPERATIONS' do
+    expect(Legion::Extensions::Agentic::Language::Grammar::Helpers::Constants::CONSTRUAL_OPERATIONS).to be_frozen
+    expect(Legion::Extensions::Agentic::Language::Grammar::Helpers::Constants::CONSTRUAL_OPERATIONS).to include(:perspective, :prominence, :specificity, :scope,
+                                                                                                                :dynamicity)
+  end
+
+  it 'defines EXPRESSION_TYPES' do
+    expect(Legion::Extensions::Agentic::Language::Grammar::Helpers::Constants::EXPRESSION_TYPES).to include(:nominal,
+                                                                                                            :relational, :clausal)
+  end
+end

data/spec/legion/extensions/agentic/language/grammar/helpers/constants_spec.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::Grammar::Helpers::Constants do
+  subject(:mod) { described_class }
+
+  it 'freezes CONSTRUAL_OPERATIONS' do
+    expect(mod::CONSTRUAL_OPERATIONS).to be_frozen
+    expect(mod::CONSTRUAL_OPERATIONS).to eq(%i[perspective prominence specificity scope dynamicity])
+  end
+
+  it 'freezes PROMINENCE_TYPES' do
+    expect(mod::PROMINENCE_TYPES).to be_frozen
+    expect(mod::PROMINENCE_TYPES).to eq(%i[figure ground])
+  end
+
+  it 'freezes SPECIFICITY_LEVELS' do
+    expect(mod::SPECIFICITY_LEVELS).to eq(%i[schematic intermediate detailed])
+  end
+
+  it 'freezes SCOPE_LEVELS' do
+    expect(mod::SCOPE_LEVELS).to eq(%i[immediate local global])
+  end
+
+  it 'freezes EXPRESSION_TYPES' do
+    expect(mod::EXPRESSION_TYPES).to eq(%i[nominal relational clausal])
+  end
+
+  describe 'ACTIVATION_LABELS' do
+    it 'maps 0.9 to :entrenched' do
+      label = mod::ACTIVATION_LABELS.find { |range, _| range.cover?(0.9) }&.last
+      expect(label).to eq(:entrenched)
+    end
+
+    it 'maps 0.7 to :conventional' do
+      label = mod::ACTIVATION_LABELS.find { |range, _| range.cover?(0.7) }&.last
+      expect(label).to eq(:conventional)
+    end
+
+    it 'maps 0.5 to :familiar' do
+      label = mod::ACTIVATION_LABELS.find { |range, _| range.cover?(0.5) }&.last
+      expect(label).to eq(:familiar)
+    end
+
+    it 'maps 0.3 to :novel' do
+      label = mod::ACTIVATION_LABELS.find { |range, _| range.cover?(0.3) }&.last
+      expect(label).to eq(:novel)
+    end
+
+    it 'maps 0.1 to :ad_hoc' do
+      label = mod::ACTIVATION_LABELS.find { |range, _| range.cover?(0.1) }&.last
+      expect(label).to eq(:ad_hoc)
+    end
+  end
+
+  it 'sets numeric limits' do
+    expect(mod::MAX_CONSTRUCTIONS).to eq(200)
+    expect(mod::MAX_CONSTRUALS).to eq(500)
+    expect(mod::MAX_HISTORY).to eq(500)
+  end
+
+  it 'sets activation constants' do
+    expect(mod::DEFAULT_ACTIVATION).to eq(0.3)
+    expect(mod::ACTIVATION_BOOST).to eq(0.1)
+    expect(mod::ACTIVATION_DECAY).to eq(0.02)
+    expect(mod::ENTRENCHMENT_THRESHOLD).to eq(0.8)
+  end
+end

data/spec/legion/extensions/agentic/language/grammar/helpers/construal_spec.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::Grammar::Helpers::Construal do
+  subject(:construal) do
+    described_class.new(
+      scene:       'cat on mat',
+      perspective: 'observer',
+      figure:      'cat',
+      ground:      'mat'
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(construal.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores scene, perspective, figure, ground' do
+      expect(construal.scene).to eq('cat on mat')
+      expect(construal.perspective).to eq('observer')
+      expect(construal.figure).to eq('cat')
+      expect(construal.ground).to eq('mat')
+    end
+
+    it 'defaults specificity to :intermediate' do
+      expect(construal.specificity).to eq(:intermediate)
+    end
+
+    it 'defaults scope to :local' do
+      expect(construal.scope).to eq(:local)
+    end
+
+    it 'defaults dynamicity to 0.5' do
+      expect(construal.dynamicity).to eq(0.5)
+    end
+
+    it 'defaults construction_id to nil' do
+      expect(construal.construction_id).to be_nil
+    end
+
+    it 'sets created_at' do
+      expect(construal.created_at).to be_a(Time)
+    end
+
+    it 'accepts optional construction_id' do
+      c = described_class.new(
+        scene: 's', perspective: 'p', figure: 'f', ground: 'g',
+        construction_id: 'abc-123'
+      )
+      expect(c.construction_id).to eq('abc-123')
+    end
+
+    it 'clamps dynamicity to 0..1' do
+      c = described_class.new(scene: 's', perspective: 'p', figure: 'f', ground: 'g', dynamicity: 1.5)
+      expect(c.dynamicity).to eq(1.0)
+    end
+
+    it 'symbolizes specificity' do
+      c = described_class.new(scene: 's', perspective: 'p', figure: 'f', ground: 'g', specificity: 'detailed')
+      expect(c.specificity).to eq(:detailed)
+    end
+
+    it 'symbolizes scope' do
+      c = described_class.new(scene: 's', perspective: 'p', figure: 'f', ground: 'g', scope: 'global')
+      expect(c.scope).to eq(:global)
+    end
+  end
+
+  describe '#prominent_element' do
+    it 'returns the figure' do
+      expect(construal.prominent_element).to eq('cat')
+    end
+  end
+
+  describe '#background_element' do
+    it 'returns the ground' do
+      expect(construal.background_element).to eq('mat')
+    end
+  end
+
+  describe '#detailed?' do
+    it 'returns false for default :intermediate specificity' do
+      expect(construal.detailed?).to be false
+    end
+
+    it 'returns true when specificity is :detailed' do
+      c = described_class.new(scene: 's', perspective: 'p', figure: 'f', ground: 'g', specificity: :detailed)
+      expect(c.detailed?).to be true
+    end
+
+    it 'returns false for :schematic' do
+      c = described_class.new(scene: 's', perspective: 'p', figure: 'f', ground: 'g', specificity: :schematic)
+      expect(c.detailed?).to be false
+    end
+  end
+
+  describe '#global_scope?' do
+    it 'returns false for default :local scope' do
+      expect(construal.global_scope?).to be false
+    end
+
+    it 'returns true when scope is :global' do
+      c = described_class.new(scene: 's', perspective: 'p', figure: 'f', ground: 'g', scope: :global)
+      expect(c.global_scope?).to be true
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all expected keys' do
+      h = construal.to_h
+      expect(h).to include(:id, :scene, :perspective, :figure, :ground, :specificity, :scope, :dynamicity,
+                           :construction_id, :created_at)
+    end
+
+    it 'reflects assigned values' do
+      h = construal.to_h
+      expect(h[:scene]).to eq('cat on mat')
+      expect(h[:figure]).to eq('cat')
+      expect(h[:ground]).to eq('mat')
+      expect(h[:specificity]).to eq(:intermediate)
+      expect(h[:scope]).to eq(:local)
+    end
+  end
+end