lex-cognitive-chunking 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c64d452ab027646fd43adc461bf72e57c4adc49fec07d02dc3765c3ff056ac9a
+  data.tar.gz: 47e6316149c761d5c13456c84d8e39013d6b5eac586cc5fe6eec297487867aca
+SHA512:
+  metadata.gz: efcc6bf5d344b740c61ae0b138bcbbd1bcd9bdeceb839ebef63fe89b3be321ff33b9d2a11a4e45e5ddcafaa2db7890eaba5b421162cce8722a6673d10359036c
+  data.tar.gz: 319265447be25637b1961dac45b9f66e1133415c06ba42c3aca5ddb53f77dead0e5d9373f13ccc0d214e12d690b855180823dbb5fecc72c085ca2faa8fe1adc2

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+group :test do
+  gem 'rake'
+  gem 'rspec', '~> 3.13'
+  gem 'rspec_junit_formatter'
+  gem 'rubocop', '~> 1.75', require: false
+  gem 'rubocop-rspec', require: false
+  gem 'simplecov'
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Esity
+
+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,42 @@
+# lex-cognitive-chunking
+
+LEX extension for LegionIO implementing George Miller's 7+/-2 cognitive chunking principle. Groups individual information items into meaningful chunks and models working memory capacity constraints.
+
+## What It Does
+
+Raw information items are pooled and then grouped into named chunks. Chunks can be merged hierarchically (items -> concepts -> schemas) to reduce working memory footprint. A bounded working memory holds up to 7 chunks (capacity varies +/- 2); loading beyond capacity triggers an overloaded state. Recall strength decays over time; reinforcement on access keeps important chunks alive.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::CognitiveChunking::Client.new
+
+r1 = client.add_item(content: 'e4 e5', domain: :chess)
+r2 = client.add_item(content: 'Nf3 Nc6', domain: :chess)
+r3 = client.add_item(content: 'Bb5', domain: :chess)
+
+chunk = client.create_chunk(
+  label: 'Ruy Lopez opening',
+  item_ids: [r1[:item_id], r2[:item_id], r3[:item_id]]
+)
+
+client.load_to_working_memory(chunk_id: chunk[:chunk_id])
+client.working_memory_status
+# => { size: 1, capacity: 7, load: 0.14, label: :spacious, overloaded: false }
+
+client.decay_all           # call periodically for recall decay
+client.reinforce_chunk(chunk_id: chunk[:chunk_id])  # boost on access
+client.chunking_report
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-chunking.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_chunking/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-chunking'
+  spec.version       = Legion::Extensions::CognitiveChunking::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Chunking'
+  spec.description   = "George Miller's 7+/-2 principle: groups information items into hierarchical chunks to model working memory capacity"
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-chunking'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']        = spec.homepage
+  spec.metadata['source_code_uri']     = 'https://github.com/LegionIO/lex-cognitive-chunking'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-cognitive-chunking'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-cognitive-chunking'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-cognitive-chunking/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-cognitive-chunking.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/cognitive_chunking/client.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_chunking/runners/cognitive_chunking'
+
+module Legion
+  module Extensions
+    module CognitiveChunking
+      class Client
+        include Runners::CognitiveChunking
+
+        def initialize(**)
+          @chunking_engine = Helpers::ChunkingEngine.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_chunking/helpers/chunk.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveChunking
+      module Helpers
+        class Chunk
+          include Constants
+
+          attr_reader :id, :label, :item_ids, :sub_chunk_ids, :coherence, :recall_strength,
+                      :access_count, :created_at
+
+          def initialize(label:, item_ids: [])
+            @id             = ::SecureRandom.uuid
+            @label          = label
+            @item_ids       = item_ids.dup
+            @sub_chunk_ids  = []
+            @coherence      = DEFAULT_COHERENCE
+            @recall_strength = 0.8
+            @access_count   = 0
+            @created_at     = Time.now.utc
+          end
+
+          def add_item!(item_id:)
+            @item_ids << item_id unless @item_ids.include?(item_id)
+          end
+
+          def remove_item!(item_id:)
+            @item_ids.delete(item_id)
+          end
+
+          def add_sub_chunk!(chunk_id:)
+            @sub_chunk_ids << chunk_id unless @sub_chunk_ids.include?(chunk_id)
+          end
+
+          def reinforce!
+            @access_count   += 1
+            @coherence       = [(@coherence + COHERENCE_BOOST).round(10), 1.0].min
+            @recall_strength = [(@recall_strength + RECALL_BOOST).round(10), 1.0].min
+          end
+
+          def decay!
+            @recall_strength = [(@recall_strength - RECALL_DECAY).round(10), 0.0].max
+            @coherence       = [(@coherence - COHERENCE_DECAY).round(10), 0.0].max
+          end
+
+          def size
+            @item_ids.size
+          end
+
+          def hierarchical?
+            !@sub_chunk_ids.empty?
+          end
+
+          def coherence_label
+            COHERENCE_LABELS.find { |range, _| range.cover?(@coherence) }&.last || :unchunked
+          end
+
+          def recall_label
+            RECALL_LABELS.find { |range, _| range.cover?(@recall_strength) }&.last || :forgotten
+          end
+
+          def size_label
+            CHUNK_SIZE_LABELS.find { |range, _| range.cover?(size) }&.last || :micro
+          end
+
+          def to_h
+            {
+              id:              @id,
+              label:           @label,
+              item_ids:        @item_ids.dup,
+              sub_chunk_ids:   @sub_chunk_ids.dup,
+              coherence:       @coherence.round(10),
+              recall_strength: @recall_strength.round(10),
+              access_count:    @access_count,
+              created_at:      @created_at,
+              size:            size,
+              hierarchical:    hierarchical?,
+              coherence_label: coherence_label,
+              recall_label:    recall_label,
+              size_label:      size_label
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_chunking/helpers/chunking_engine.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveChunking
+      module Helpers
+        class ChunkingEngine
+          include Constants
+
+          attr_reader :items, :chunks, :working_memory
+
+          def initialize
+            @items          = {}
+            @chunks         = {}
+            @working_memory = []
+          end
+
+          def add_item(content:, domain: :general)
+            return { success: false, error: :capacity_exceeded } if @items.size >= MAX_ITEMS
+
+            item = InformationItem.new(content: content, domain: domain)
+            @items[item.id] = item
+            { success: true, item_id: item.id, item: item.to_h }
+          end
+
+          def create_chunk(label:, item_ids:)
+            return { success: false, error: :capacity_exceeded } if @chunks.size >= MAX_CHUNKS
+            return { success: false, error: :empty_item_ids } if item_ids.empty?
+
+            valid_ids = item_ids.select { |id| @items.key?(id) }
+            return { success: false, error: :no_valid_items } if valid_ids.empty?
+
+            chunk = Chunk.new(label: label, item_ids: valid_ids)
+            @chunks[chunk.id] = chunk
+            valid_ids.each { |id| @items[id]&.assign_to_chunk!(chunk_id: chunk.id) }
+
+            { success: true, chunk_id: chunk.id, chunk: chunk.to_h }
+          end
+
+          def merge_chunks(chunk_ids:, label:)
+            return { success: false, error: :capacity_exceeded } if @chunks.size >= MAX_CHUNKS
+            return { success: false, error: :insufficient_chunks } if chunk_ids.size < 2
+
+            valid_chunk_ids = chunk_ids.select { |id| @chunks.key?(id) }
+            return { success: false, error: :no_valid_chunks } if valid_chunk_ids.size < 2
+
+            merged_item_ids = valid_chunk_ids.flat_map { |id| @chunks[id].item_ids }.uniq
+            parent = Chunk.new(label: label, item_ids: merged_item_ids)
+            valid_chunk_ids.each { |id| parent.add_sub_chunk!(chunk_id: id) }
+            @chunks[parent.id] = parent
+
+            { success: true, chunk_id: parent.id, chunk: parent.to_h, merged_from: valid_chunk_ids }
+          end
+
+          def load_to_working_memory(chunk_id:)
+            return { success: false, error: :chunk_not_found } unless @chunks.key?(chunk_id)
+            return { success: false, error: :already_loaded } if @working_memory.include?(chunk_id)
+            return { success: false, error: :capacity_exceeded } if @working_memory.size >= WORKING_MEMORY_CAPACITY
+
+            @working_memory << chunk_id
+            @chunks[chunk_id].reinforce!
+            { success: true, chunk_id: chunk_id, working_memory_size: @working_memory.size }
+          end
+
+          def unload_from_working_memory(chunk_id:)
+            return { success: false, error: :not_in_working_memory } unless @working_memory.include?(chunk_id)
+
+            @working_memory.delete(chunk_id)
+            { success: true, chunk_id: chunk_id, working_memory_size: @working_memory.size }
+          end
+
+          def working_memory_load
+            return 0.0 if WORKING_MEMORY_CAPACITY.zero?
+
+            (@working_memory.size.to_f / WORKING_MEMORY_CAPACITY).round(10)
+          end
+
+          def working_memory_overloaded?
+            @working_memory.size > WORKING_MEMORY_CAPACITY
+          end
+
+          def decay_all!
+            @chunks.each_value(&:decay!)
+            { success: true, chunks_decayed: @chunks.size }
+          end
+
+          def reinforce_chunk(chunk_id:)
+            return { success: false, error: :chunk_not_found } unless @chunks.key?(chunk_id)
+
+            @chunks[chunk_id].reinforce!
+            { success: true, chunk_id: chunk_id, chunk: @chunks[chunk_id].to_h }
+          end
+
+          def strongest_chunks(limit: 10)
+            @chunks.values
+                   .sort_by { |c| -c.recall_strength }
+                   .first(limit)
+                   .map(&:to_h)
+          end
+
+          def unchunked_items
+            @items.values.reject(&:chunked?).map(&:to_h)
+          end
+
+          def chunking_efficiency
+            return 0.0 if @items.empty?
+
+            chunked_count = @items.values.count(&:chunked?)
+            (chunked_count.to_f / @items.size).round(10)
+          end
+
+          def chunking_report
+            wm_load = working_memory_load
+            capacity_label = CAPACITY_LABELS.find { |range, _| range.cover?(wm_load) }&.last || :empty
+
+            {
+              total_items:         @items.size,
+              total_chunks:        @chunks.size,
+              unchunked_items:     unchunked_items.size,
+              chunking_efficiency: chunking_efficiency,
+              working_memory:      {
+                current:   @working_memory.size,
+                capacity:  WORKING_MEMORY_CAPACITY,
+                load:      wm_load,
+                label:     capacity_label,
+                chunk_ids: @working_memory.dup
+              },
+              strongest_chunks:    strongest_chunks(limit: 5)
+            }
+          end
+
+          def to_h
+            {
+              items:          @items.transform_values(&:to_h),
+              chunks:         @chunks.transform_values(&:to_h),
+              working_memory: @working_memory.dup
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_chunking/helpers/constants.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveChunking
+      module Helpers
+        module Constants
+          MAX_ITEMS               = 500
+          MAX_CHUNKS              = 200
+          WORKING_MEMORY_CAPACITY = 7    # Miller's magic number
+          CAPACITY_VARIANCE       = 2    # +/- 2
+          DEFAULT_COHERENCE       = 0.5
+          COHERENCE_BOOST         = 0.08
+          COHERENCE_DECAY         = 0.03
+          RECALL_DECAY            = 0.02
+          RECALL_BOOST            = 0.1
+
+          CHUNK_SIZE_LABELS = {
+            (7..)   => :large,
+            (5...7) => :medium,
+            (3...5) => :small,
+            (..3)   => :micro
+          }.freeze
+
+          COHERENCE_LABELS = {
+            (0.8..)     => :tightly_chunked,
+            (0.6...0.8) => :well_chunked,
+            (0.4...0.6) => :loosely_chunked,
+            (0.2...0.4) => :weakly_chunked,
+            (..0.2)     => :unchunked
+          }.freeze
+
+          RECALL_LABELS = {
+            (0.8..)     => :instant,
+            (0.6...0.8) => :easy,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :difficult,
+            (..0.2)     => :forgotten
+          }.freeze
+
+          CAPACITY_LABELS = {
+            (0.8..)     => :overloaded,
+            (0.6...0.8) => :near_capacity,
+            (0.4...0.6) => :comfortable,
+            (0.2...0.4) => :spacious,
+            (..0.2)     => :empty
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_chunking/helpers/information_item.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveChunking
+      module Helpers
+        class InformationItem
+          attr_reader :id, :content, :domain, :chunk_id, :created_at
+
+          def initialize(content:, domain: :general)
+            @id         = ::SecureRandom.uuid
+            @content    = content
+            @domain     = domain
+            @chunked    = false
+            @chunk_id   = nil
+            @created_at = Time.now.utc
+          end
+
+          def chunked?
+            @chunked
+          end
+
+          def assign_to_chunk!(chunk_id:)
+            @chunked  = true
+            @chunk_id = chunk_id
+          end
+
+          def unchunk!
+            @chunked  = false
+            @chunk_id = nil
+          end
+
+          def to_h
+            {
+              id:         @id,
+              content:    @content,
+              domain:     @domain,
+              chunked:    @chunked,
+              chunk_id:   @chunk_id,
+              created_at: @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_chunking/runners/cognitive_chunking.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveChunking
+      module Runners
+        module CognitiveChunking
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def add_item(content:, domain: :general, engine: nil, **)
+            eng = engine || chunking_engine
+            result = eng.add_item(content: content, domain: domain)
+            Legion::Logging.debug "[cognitive_chunking] add_item: domain=#{domain} success=#{result[:success]}"
+            result
+          end
+
+          def create_chunk(label:, item_ids:, engine: nil, **)
+            eng = engine || chunking_engine
+            result = eng.create_chunk(label: label, item_ids: item_ids)
+            Legion::Logging.debug "[cognitive_chunking] create_chunk: label=#{label} items=#{item_ids.size} success=#{result[:success]}"
+            result
+          end
+
+          def merge_chunks(chunk_ids:, label:, engine: nil, **)
+            eng = engine || chunking_engine
+            result = eng.merge_chunks(chunk_ids: chunk_ids, label: label)
+            Legion::Logging.debug "[cognitive_chunking] merge_chunks: label=#{label} sources=#{chunk_ids.size} success=#{result[:success]}"
+            result
+          end
+
+          def load_to_working_memory(chunk_id:, engine: nil, **)
+            eng = engine || chunking_engine
+            result = eng.load_to_working_memory(chunk_id: chunk_id)
+            Legion::Logging.debug "[cognitive_chunking] load_wm: chunk_id=#{chunk_id} wm_size=#{result[:working_memory_size]} success=#{result[:success]}"
+            result
+          end
+
+          def unload_from_working_memory(chunk_id:, engine: nil, **)
+            eng = engine || chunking_engine
+            result = eng.unload_from_working_memory(chunk_id: chunk_id)
+            Legion::Logging.debug "[cognitive_chunking] unload_wm: chunk_id=#{chunk_id} success=#{result[:success]}"
+            result
+          end
+
+          def working_memory_status(engine: nil, **)
+            eng    = engine || chunking_engine
+            load   = eng.working_memory_load
+            label  = Helpers::Constants::CAPACITY_LABELS.find { |range, _| range.cover?(load) }&.last || :empty
+
+            Legion::Logging.debug "[cognitive_chunking] wm_status: load=#{load.round(2)} label=#{label}"
+            {
+              success:    true,
+              size:       eng.working_memory.size,
+              capacity:   Helpers::Constants::WORKING_MEMORY_CAPACITY,
+              load:       load,
+              label:      label,
+              overloaded: eng.working_memory_overloaded?
+            }
+          end
+
+          def decay_all(engine: nil, **)
+            eng    = engine || chunking_engine
+            result = eng.decay_all!
+            Legion::Logging.debug "[cognitive_chunking] decay_all: chunks_decayed=#{result[:chunks_decayed]}"
+            result
+          end
+
+          def reinforce_chunk(chunk_id:, engine: nil, **)
+            eng    = engine || chunking_engine
+            result = eng.reinforce_chunk(chunk_id: chunk_id)
+            Legion::Logging.debug "[cognitive_chunking] reinforce_chunk: chunk_id=#{chunk_id} success=#{result[:success]}"
+            result
+          end
+
+          def chunking_report(engine: nil, **)
+            eng    = engine || chunking_engine
+            report = eng.chunking_report
+            eff = report[:chunking_efficiency].round(2)
+            Legion::Logging.debug "[cognitive_chunking] report: items=#{report[:total_items]} chunks=#{report[:total_chunks]} efficiency=#{eff}"
+            { success: true, report: report }
+          end
+
+          def strongest_chunks(limit: 10, engine: nil, **)
+            eng    = engine || chunking_engine
+            chunks = eng.strongest_chunks(limit: limit)
+            Legion::Logging.debug "[cognitive_chunking] strongest_chunks: count=#{chunks.size}"
+            { success: true, chunks: chunks }
+          end
+
+          def unchunked_items(engine: nil, **)
+            eng   = engine || chunking_engine
+            items = eng.unchunked_items
+            Legion::Logging.debug "[cognitive_chunking] unchunked_items: count=#{items.size}"
+            { success: true, items: items }
+          end
+
+          private
+
+          def chunking_engine
+            @chunking_engine ||= Helpers::ChunkingEngine.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_chunking/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveChunking
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/legion/extensions/cognitive_chunking.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/cognitive_chunking/version'
+require 'legion/extensions/cognitive_chunking/helpers/constants'
+require 'legion/extensions/cognitive_chunking/helpers/information_item'
+require 'legion/extensions/cognitive_chunking/helpers/chunk'
+require 'legion/extensions/cognitive_chunking/helpers/chunking_engine'
+require 'legion/extensions/cognitive_chunking/runners/cognitive_chunking'
+
+module Legion
+  module Extensions
+    module CognitiveChunking
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/cognitive_chunking/client_spec.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_chunking/client'
+
+RSpec.describe Legion::Extensions::CognitiveChunking::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    %i[add_item create_chunk merge_chunks load_to_working_memory
+       unload_from_working_memory working_memory_status decay_all
+       reinforce_chunk chunking_report strongest_chunks unchunked_items].each do |method|
+      expect(client).to respond_to(method)
+    end
+  end
+
+  it 'maintains state across calls using internal engine' do
+    client.add_item(content: 'pawn structure')
+    client.add_item(content: 'knight outpost')
+    report = client.chunking_report
+    expect(report[:report][:total_items]).to eq(2)
+  end
+
+  it 'runs a full chunking workflow' do
+    r1 = client.add_item(content: 'e4 e5', domain: :chess)
+    r2 = client.add_item(content: 'Nf3 Nc6', domain: :chess)
+    r3 = client.add_item(content: 'Bb5', domain: :chess)
+
+    chunk = client.create_chunk(
+      label:    'Ruy Lopez opening',
+      item_ids: [r1[:item_id], r2[:item_id], r3[:item_id]]
+    )
+    expect(chunk[:success]).to be true
+
+    loaded = client.load_to_working_memory(chunk_id: chunk[:chunk_id])
+    expect(loaded[:success]).to be true
+    expect(loaded[:working_memory_size]).to eq(1)
+
+    status = client.working_memory_status
+    expect(status[:size]).to eq(1)
+    expect(status[:load]).to be > 0.0
+
+    report = client.chunking_report
+    expect(report[:report][:chunking_efficiency]).to eq(1.0)
+    expect(report[:report][:unchunked_items]).to eq(0)
+  end
+
+  it 'supports merge of two chunks into a hierarchy' do
+    ra = client.add_item(content: 'opening theory')[:item_id]
+    rb = client.add_item(content: 'endgame theory')[:item_id]
+    ca = client.create_chunk(label: 'Opening', item_ids: [ra])[:chunk_id]
+    cb = client.create_chunk(label: 'Endgame', item_ids: [rb])[:chunk_id]
+
+    merged = client.merge_chunks(chunk_ids: [ca, cb], label: 'Chess Theory')
+    expect(merged[:success]).to be true
+    expect(merged[:chunk][:hierarchical]).to be true
+  end
+
+  it 'reports unchunked items correctly' do
+    client.add_item(content: 'orphan item')
+    r2 = client.add_item(content: 'grouped item')[:item_id]
+    client.create_chunk(label: 'group', item_ids: [r2])
+
+    result = client.unchunked_items
+    expect(result[:items].size).to eq(1)
+    expect(result[:items].first[:content]).to eq('orphan item')
+  end
+end