lex-cognitive-tessellation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e7f6f52f6c2c0a13ef9974ca5dd9d9868fe076e7c1a2ba6a3e23eae1e6c7c610
+  data.tar.gz: b70c6b251e6443bc7c13976cbe691709342baf8f373cf396f8f3bec227d58a74
+SHA512:
+  metadata.gz: 593ba1d137e5c15f6d87284963efff612b2118b08d53b339cf6308f43c07178df2a8e49a98ad73f96de6235664aded53b0b72bd90a528409f139160c7f26041f
+  data.tar.gz: e3cde566be075711228beb30745ab180184125624ad6f3f79997d5af5e8a6332433163fa741116fab81ca265b5c6cb0debe565c7d062e31c42b98f46c028f989

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,2 @@
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,37 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+
+Style/Documentation:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Layout/HashAlignment:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*
+
+Style/OneClassPerFile:
+  Exclude:
+    - spec/spec_helper.rb

data/CLAUDE.md

@@ -0,0 +1,127 @@
+# lex-cognitive-tessellation
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Gem**: `lex-cognitive-tessellation`
+- **Version**: 0.1.0
+- **Namespace**: `Legion::Extensions::CognitiveTessellation`
+
+## Purpose
+
+Models knowledge coverage as a tessellation — a pattern of tiles fitting together without gaps or excessive overlap. Each tile represents a unit of cognitive content (knowledge, skill, pattern, belief, etc.) in a domain. Tiles expand or shrink in coverage, connect to adjacent tiles, and auto-organize into per-domain mosaics. The model surfaces gaps (under-covered tiles), seamless fits (well-integrated tiles), and overall coherence.
+
+## Gem Info
+
+- **Gemspec**: `lex-cognitive-tessellation.gemspec`
+- **Require**: `lex-cognitive-tessellation`
+- **Ruby**: >= 3.4
+- **License**: MIT
+- **Homepage**: https://github.com/LegionIO/lex-cognitive-tessellation
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_tessellation/
+  version.rb
+  helpers/
+    constants.rb              # Shapes, domains, tile types, coverage/fit/density label tables
+    tile.rb                   # Tile class — one cognitive knowledge unit
+    mosaic.rb                 # Mosaic class — per-domain tile collection
+    tessellation_engine.rb    # TessellationEngine — registry and aggregate metrics
+  runners/
+    cognitive_tessellation.rb  # Runner module — public API
+  client.rb
+```
+
+## Key Constants
+
+| Constant | Value | Meaning |
+|---|---|---|
+| `MAX_TILES` | 500 | Hard cap; lowest effective-coverage tiles pruned when exceeded |
+| `MAX_MOSAICS` | 50 | Max per-domain mosaics (not enforced in engine) |
+| `FULL_COVERAGE_THRESHOLD` | 0.95 | Coverage >= this = `full_coverage?` true |
+| `GAP_THRESHOLD` | 0.3 | Fit score < this = `gapped?` true |
+| `OVERLAP_THRESHOLD` | 0.7 | Fit + many adjacents triggers `overlapping?` |
+| `FIT_TOLERANCE` | 0.05 | Reference tolerance (defined, not used) |
+| `COVERAGE_GROWTH` | 0.08 | Coverage increase per `expand!` |
+| `COVERAGE_DECAY` | 0.02 | Coverage decrease per `shrink!` |
+| `OVERLAP_PENALTY` | 0.05 | Per-adjacent penalty when `overlapping?` |
+
+`TILE_SHAPES`: `[:triangular, :square, :hexagonal, :pentagonal, :irregular, :fractal, :amorphous, :crystalline]`
+
+`DOMAINS`: `[:cognitive, :emotional, :procedural, :semantic, :episodic, :social, :creative, :analytical]`
+
+`TILE_TYPES`: `[:knowledge, :skill, :pattern, :belief, :heuristic, :schema, :model, :framework]`
+
+Coverage labels: `0.9+` = `:complete`, `0.7..0.9` = `:substantial`, `0.5..0.7` = `:partial`, `0.3..0.5` = `:sparse`, `<0.3` = `:fragmented`
+
+Fit labels: `0.8+` = `:seamless`, `0.6..0.8` = `:snug`, `0.4..0.6` = `:loose`, `0.2..0.4` = `:gapped`, `<0.2` = `:disjointed`
+
+## Key Classes
+
+### `Helpers::Tile`
+
+One cognitive knowledge unit.
+
+- `expand!(amount)` — increases coverage by amount (default `COVERAGE_GROWTH`)
+- `shrink!(amount)` — decreases coverage by amount (default `COVERAGE_DECAY`)
+- `adjust_fit!(new_fit)` — sets fit score
+- `connect!(other_id)` — adds to `adjacent_ids` (no duplicates)
+- `full_coverage?` — coverage >= 0.95; `gapped?` — fit_score < 0.3; `seamless?` — fit_score >= 0.8
+- `overlapping?` — fit_score > 0.7 AND adjacent_ids.size > 3
+- `isolated?` — no adjacent tiles; `well_connected?` — 3+ adjacent tiles
+- `effective_coverage` — coverage minus overlap penalties
+
+### `Helpers::Mosaic`
+
+A per-domain collection of tiles.
+
+- `add_tile(tile)` — appends and auto-connects to last 2 tiles in same domain via `compute_fit`
+- `total_coverage` — mean effective_coverage across tiles
+- `coherence` — ratio of well-connected tiles (adjacency >= 3)
+- `uniformity` — `1 - sqrt(variance_of_coverages)`; high = tiles are evenly covered
+- `complete?` — total_coverage >= `FULL_COVERAGE_THRESHOLD`
+- `auto_connect` computes fit: `0.5 + shape_match(0.2 if same) + type_match(0.1 if same) + rand(0..0.2)`
+
+### `Helpers::TessellationEngine`
+
+Registry for all tiles and mosaics.
+
+- `create_tile(tile_type:, shape:, domain:, coverage:, fit_score:)` — auto-creates mosaic for domain; prunes lowest-coverage if over `MAX_TILES`
+- `expand_tile(tile_id:, amount:)` — delegates to tile
+- `shrink_all!` — shrinks every tile by `COVERAGE_DECAY`
+- `connect_tiles(tile_a_id:, tile_b_id:)` — bidirectional adjacency
+- `gapped_tiles` / `seamless_tiles` / `isolated_tiles` / `full_coverage_tiles` — filtered tile lists
+- `overall_coverage` / `overall_fit` / `overall_coherence` — aggregate scores
+- `gap_density` — ratio of gapped tiles
+- `tessellation_report` — full report with all counts and labels
+
+## Runners
+
+Module: `Legion::Extensions::CognitiveTessellation::Runners::CognitiveTessellation`
+
+| Runner | Key Args | Returns |
+|---|---|---|
+| `create_tile` | `tile_type:`, `shape:`, `domain:`, `coverage:`, `fit_score:` | `{ success:, tile: }` |
+| `expand_tile` | `tile_id:`, `amount:` | `{ success:, tile: }` or `{ success: false, error: }` |
+| `connect_tiles` | `tile_a_id:`, `tile_b_id:` | `{ success:, connected:, tile_a:, tile_b: }` or error |
+| `shrink_all` | — | `{ success: true }` |
+| `list_gaps` | — | `{ success:, count:, tiles: }` |
+| `tessellation_status` | — | `{ success:, total_tiles:, overall_coverage:, gap_density:, mosaics:, ... }` |
+
+Note: the runner uses `@default_engine` directly (not `engine || @default_engine` for all runners — `create_tile` uses the pattern but some others don't initialize it lazily).
+
+## Integration Points
+
+- No actors defined; `shrink_all` should be called periodically as a decay tick
+- `list_gaps` identifies knowledge domains needing expansion — can drive learning prioritization
+- Mosaics are auto-created per domain when the first tile for a domain is created
+- All state is in-memory per `TessellationEngine` instance
+
+## Development Notes
+
+- The runner accesses `@default_engine` directly without the `||=` pattern in some methods — the engine must be initialized before those runners are called (via `create_tile` or another `||=` path)
+- `compute_fit` in Mosaic includes `rand * 0.2` — fit scores have a random component introduced at tile connection time
+- `overlapping?` requires BOTH high fit score AND more than 3 adjacents — fit score alone is not sufficient
+- `auto_connect` connects new tiles to the last 2 tiles in the same domain only; tiles added to the same-domain mosaic but not via the engine are not connected
+- `prune_tiles` removes the lowest-effective-coverage tiles when over `MAX_TILES`

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75'
+gem 'rubocop-rspec'
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/Gemfile.lock

@@ -0,0 +1,78 @@
+PATH
+  remote: .
+  specs:
+    lex-cognitive-tessellation (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.0.1)
+    diff-lcs (1.6.2)
+    json (2.19.1)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  lex-cognitive-tessellation!
+  rspec (~> 3.13)
+  rubocop (~> 1.75)
+  rubocop-rspec
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,56 @@
+# lex-cognitive-tessellation
+
+A LegionIO cognitive architecture extension that models knowledge coverage as a tessellation. Tiles represent cognitive units (knowledge, skills, patterns, beliefs) that fit together across domains, growing through expansion and fading through decay.
+
+## What It Does
+
+Tracks **tiles** of eight types (`knowledge`, `skill`, `pattern`, `belief`, `heuristic`, `schema`, `model`, `framework`) across eight domains (`cognitive`, `emotional`, `procedural`, `semantic`, `episodic`, `social`, `creative`, `analytical`).
+
+Each tile has coverage (how much of its domain it explains) and a fit score (how well it integrates with neighbors). Tiles auto-organize into per-domain mosaics when created. The system surfaces gaps, isolated tiles, and coherence across the knowledge landscape.
+
+## Usage
+
+```ruby
+require 'lex-cognitive-tessellation'
+
+client = Legion::Extensions::CognitiveTessellation::Client.new
+
+# Create a knowledge tile
+t1 = client.create_tile(tile_type: :knowledge, shape: :hexagonal, domain: :semantic, coverage: 0.4)
+# => { success: true, tile: { id: "uuid...", coverage: 0.4, fit_score: 0.5, gapped: false, seamless: false, ... } }
+
+t2 = client.create_tile(tile_type: :schema, shape: :hexagonal, domain: :semantic, coverage: 0.6)
+t3 = client.create_tile(tile_type: :knowledge, shape: :square, domain: :procedural, coverage: 0.2)
+
+# Expand a tile's coverage
+client.expand_tile(tile_id: t1[:tile][:id], amount: 0.1)
+# => { success: true, tile: { coverage: 0.5, ... } }
+
+# Explicitly connect two tiles
+client.connect_tiles(tile_a_id: t1[:tile][:id], tile_b_id: t2[:tile][:id])
+# => { success: true, connected: true, tile_a: "uuid...", tile_b: "uuid..." }
+
+# Find tiles with poor fit (gaps)
+client.list_gaps
+# => { success: true, count: 0, tiles: [] }
+
+# Decay all tiles (periodic maintenance)
+client.shrink_all
+# => { success: true }
+
+# Full tessellation report
+client.tessellation_status
+# => { success: true, total_tiles: 3, overall_coverage: 0.35, coverage_label: :sparse, gap_density: 0.0, mosaics: [...], ... }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-tessellation.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_tessellation/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-tessellation'
+  spec.version       = Legion::Extensions::CognitiveTessellation::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+  spec.summary       = 'Cognitive pattern tiling and coverage analysis for LegionIO agents'
+  spec.description   = 'Models how cognitive patterns tile together to cover conceptual space ' \
+                       'detecting gaps, overlaps, and coherence in knowledge mosaics'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-tessellation'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata = {
+    'homepage_uri'          => spec.homepage,
+    'source_code_uri'       => spec.homepage,
+    'documentation_uri'     => "#{spec.homepage}/blob/master/README.md",
+    'changelog_uri'         => "#{spec.homepage}/blob/master/CHANGELOG.md",
+    'bug_tracker_uri'       => "#{spec.homepage}/issues",
+    'rubygems_mfa_required' => 'true'
+  }
+
+  spec.files = Dir.chdir(__dir__) { `git ls-files -z`.split("\x0") }
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveTessellation
+      class Client
+        include Runners::CognitiveTessellation
+
+        def initialize
+          @default_engine = Helpers::TessellationEngine.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveTessellation
+      module Helpers
+        module Constants
+          MAX_TILES = 500
+          MAX_MOSAICS = 50
+
+          DEFAULT_COVERAGE = 0.0
+          FULL_COVERAGE_THRESHOLD = 0.95
+          GAP_THRESHOLD = 0.3
+          OVERLAP_THRESHOLD = 0.7
+          FIT_TOLERANCE = 0.05
+
+          COVERAGE_GROWTH = 0.08
+          COVERAGE_DECAY = 0.02
+          OVERLAP_PENALTY = 0.05
+
+          TILE_SHAPES = %i[
+            triangular square hexagonal pentagonal
+            irregular fractal amorphous crystalline
+          ].freeze
+
+          DOMAINS = %i[
+            cognitive emotional procedural semantic
+            episodic social creative analytical
+          ].freeze
+
+          TILE_TYPES = %i[
+            knowledge skill pattern belief
+            heuristic schema model framework
+          ].freeze
+
+          COVERAGE_LABELS = {
+            (0.9..)     => :complete,
+            (0.7...0.9) => :substantial,
+            (0.5...0.7) => :partial,
+            (0.3...0.5) => :sparse,
+            (..0.3)     => :fragmented
+          }.freeze
+
+          FIT_LABELS = {
+            (0.8..)     => :seamless,
+            (0.6...0.8) => :snug,
+            (0.4...0.6) => :loose,
+            (0.2...0.4) => :gapped,
+            (..0.2)     => :disjointed
+          }.freeze
+
+          DENSITY_LABELS = {
+            (0.8..)     => :saturated,
+            (0.6...0.8) => :dense,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :thin,
+            (..0.2)     => :vacant
+          }.freeze
+
+          def self.label_for(labels, value)
+            labels.each { |range, label| return label if range.cover?(value) }
+            :unknown
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_tessellation/helpers/mosaic.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveTessellation
+      module Helpers
+        class Mosaic
+          include Constants
+
+          attr_reader :id, :domain, :tiles, :created_at
+
+          def initialize(domain:)
+            @id         = SecureRandom.uuid
+            @domain     = domain.to_sym
+            @tiles      = []
+            @created_at = Time.now.utc
+          end
+
+          def add_tile(tile)
+            @tiles << tile
+            auto_connect(tile)
+            tile
+          end
+
+          def total_coverage
+            return 0.0 if @tiles.empty?
+
+            raw = @tiles.sum(&:effective_coverage) / @tiles.size
+            raw.clamp(0.0, 1.0).round(10)
+          end
+
+          def average_fit
+            return 0.0 if @tiles.empty?
+
+            (@tiles.sum(&:fit_score) / @tiles.size).round(10)
+          end
+
+          def gap_count = @tiles.count(&:gapped?)
+          def seamless_count = @tiles.count(&:seamless?)
+          def isolated_count = @tiles.count(&:isolated?)
+          def complete? = total_coverage >= FULL_COVERAGE_THRESHOLD
+
+          def coherence
+            return 0.0 if @tiles.empty?
+
+            connected = @tiles.count(&:well_connected?)
+            (connected.to_f / @tiles.size).round(10)
+          end
+
+          def uniformity
+            return 1.0 if @tiles.size <= 1
+
+            coverages = @tiles.map(&:coverage)
+            mean = coverages.sum / coverages.size
+            variance = coverages.sum { |c| (c - mean)**2 } / coverages.size
+            (1.0 - Math.sqrt(variance)).clamp(0.0, 1.0).round(10)
+          end
+
+          def to_h
+            {
+              id:             @id,
+              domain:         @domain,
+              tile_count:     @tiles.size,
+              total_coverage: total_coverage,
+              average_fit:    average_fit,
+              coherence:      coherence,
+              uniformity:     uniformity,
+              gaps:           gap_count,
+              seamless:       seamless_count,
+              complete:       complete?
+            }
+          end
+
+          private
+
+          def auto_connect(new_tile)
+            same_domain = @tiles.select { |t| t.domain == new_tile.domain && t.id != new_tile.id }
+            same_domain.last(2).each do |neighbor|
+              new_tile.connect!(neighbor.id)
+              neighbor.connect!(new_tile.id)
+              compute_fit(new_tile, neighbor)
+            end
+          end
+
+          def compute_fit(tile_a, tile_b)
+            shape_match = tile_a.shape == tile_b.shape ? 0.2 : 0.0
+            type_match  = tile_a.tile_type == tile_b.tile_type ? 0.1 : 0.0
+            base_fit    = 0.5 + shape_match + type_match + (rand * 0.2)
+            tile_a.adjust_fit!(base_fit)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_tessellation/helpers/tessellation_engine.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveTessellation
+      module Helpers
+        class TessellationEngine
+          include Constants
+
+          def initialize
+            @tiles   = {}
+            @mosaics = {}
+          end
+
+          def create_tile(tile_type:, shape:, domain:, coverage: nil, fit_score: nil)
+            tile = Tile.new(tile_type: tile_type, shape: shape, domain: domain,
+                            coverage: coverage, fit_score: fit_score)
+            @tiles[tile.id] = tile
+            mosaic = find_or_create_mosaic(domain: domain)
+            mosaic.add_tile(tile)
+            prune_tiles
+            tile
+          end
+
+          def expand_tile(tile_id:, amount: COVERAGE_GROWTH)
+            tile = @tiles[tile_id]
+            return nil unless tile
+
+            tile.expand!(amount)
+            tile
+          end
+
+          def shrink_all!
+            @tiles.each_value { |t| t.shrink!(COVERAGE_DECAY) }
+          end
+
+          def connect_tiles(tile_a_id:, tile_b_id:)
+            a = @tiles[tile_a_id]
+            b = @tiles[tile_b_id]
+            return nil unless a && b
+
+            a.connect!(b.id)
+            b.connect!(a.id)
+            { connected: true, tile_a: a.id, tile_b: b.id }
+          end
+
+          def tiles_by_domain(domain:) = @tiles.values.select { |t| t.domain == domain.to_sym }
+          def tiles_by_type(tile_type:) = @tiles.values.select { |t| t.tile_type == tile_type.to_sym }
+          def tiles_by_shape(shape:) = @tiles.values.select { |t| t.shape == shape.to_sym }
+          def gapped_tiles = @tiles.values.select(&:gapped?)
+          def seamless_tiles = @tiles.values.select(&:seamless?)
+          def isolated_tiles = @tiles.values.select(&:isolated?)
+          def full_coverage_tiles = @tiles.values.select(&:full_coverage?)
+
+          def overall_coverage
+            return 0.0 if @mosaics.empty?
+
+            (@mosaics.values.sum(&:total_coverage) / @mosaics.size).round(10)
+          end
+
+          def overall_fit
+            return 0.0 if @tiles.empty?
+
+            (@tiles.values.sum(&:fit_score) / @tiles.size).round(10)
+          end
+
+          def overall_coherence
+            return 0.0 if @mosaics.empty?
+
+            (@mosaics.values.sum(&:coherence) / @mosaics.size).round(10)
+          end
+
+          def domain_coverage
+            @mosaics.transform_values(&:total_coverage)
+          end
+
+          def gap_density
+            return 0.0 if @tiles.empty?
+
+            (gapped_tiles.size.to_f / @tiles.size).round(10)
+          end
+
+          def most_covered(limit: 5)
+            @tiles.values.sort_by { |t| -t.effective_coverage }.first(limit)
+          end
+
+          def least_covered(limit: 5)
+            @tiles.values.sort_by(&:effective_coverage).first(limit)
+          end
+
+          def tessellation_report
+            {
+              total_tiles:       @tiles.size,
+              total_mosaics:     @mosaics.size,
+              overall_coverage:  overall_coverage,
+              coverage_label:    Constants.label_for(COVERAGE_LABELS, overall_coverage),
+              overall_fit:       overall_fit,
+              fit_label:         Constants.label_for(FIT_LABELS, overall_fit),
+              overall_coherence: overall_coherence,
+              gap_density:       gap_density,
+              gapped_count:      gapped_tiles.size,
+              seamless_count:    seamless_tiles.size,
+              isolated_count:    isolated_tiles.size,
+              domain_coverage:   domain_coverage,
+              mosaics:           @mosaics.values.map(&:to_h)
+            }
+          end
+
+          def to_h
+            {
+              total_tiles:   @tiles.size,
+              total_mosaics: @mosaics.size,
+              coverage:      overall_coverage,
+              fit:           overall_fit,
+              coherence:     overall_coherence
+            }
+          end
+
+          private
+
+          def find_or_create_mosaic(domain:)
+            key = domain.to_sym
+            @mosaics[key] ||= Mosaic.new(domain: key)
+          end
+
+          def prune_tiles
+            return if @tiles.size <= MAX_TILES
+
+            sorted = @tiles.values.sort_by(&:effective_coverage)
+            to_remove = sorted.first(@tiles.size - MAX_TILES)
+            to_remove.each { |t| @tiles.delete(t.id) }
+          end
+        end
+      end
+    end
+  end
+end