lex-cognitive-archaeology 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b06b2250b06c73483e0a73ab31f46136c644d7a44646f6f81305940aaee3de6f
+  data.tar.gz: 80352c5869543380812a6ff1215bb37564b64e7d2d2c07b9a9d03ae4a977ba68
+SHA512:
+  metadata.gz: 35086ac86f3f1b13c1da78a85822b688629d4808c90ec016075a54940d4f376e34794bb821abc745485ee59dfe33609448107bde8322ab9175d3b75eb62125c0
+  data.tar.gz: 89870d749c7ea60cab920f3615688a07d9e228ff203ede1a1171a9697231d8c7a489c9eb798342e38814fcf6f50a24e6ba622a5135420ca86c1751c201ca940d

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,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.gem
+Gemfile.lock
+.rspec_status

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,38 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 200
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/BlockLength:
+  Max: 50
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Style/Documentation:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false

data/CLAUDE.md

@@ -0,0 +1,102 @@
+# lex-cognitive-archaeology
+
+**Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Grandparent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Cognitive archaeology metaphor for recovering deeply buried cognitive artifacts — excavation sites have depth levels (surface to bedrock), and digging surfaces artifacts with type probabilities weighted by depth and epoch.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-archaeology`
+- **Version**: `0.1.0`
+- **Module**: `Legion::Extensions::CognitiveArchaeology`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_archaeology/
+  cognitive_archaeology.rb       # Main extension module
+  version.rb                     # VERSION = '0.1.0'
+  client.rb                      # Client wrapper
+  helpers/
+    constants.rb                 # Artifact types, depth levels, epoch names, rarity weights, labels
+    artifact.rb                  # Artifact value object (type, depth, preservation, integrity, epoch)
+    site.rb                      # Site value object (domain, depth levels, artifacts collected)
+    archaeology_engine.rb        # ArchaeologyEngine — manages sites, excavation, restoration
+  runners/
+    cognitive_archaeology.rb     # Runner module (extend self) with 7 public methods
+spec/
+  (spec files)
+```
+
+## Key Constants
+
+```ruby
+ARTIFACT_TYPES = %i[pattern skill knowledge memory_fragment association procedure belief schema]
+DOMAIN_TYPES   = %i[general infrastructure reasoning memory identity emotional procedural]
+EXCAVATION_DEPTH_LEVELS = %i[surface shallow mid deep bedrock]
+EPOCH_NAMES = %i[recent near_past medium_past distant_past ancient]
+
+# Weighted probability tables: deeper levels surface rarer types
+DEPTH_RARITY_WEIGHTS = {
+  surface:  { pattern: 30, skill: 20, knowledge: 25, memory_fragment: 15, association: 10, ... },
+  bedrock:  { schema: 30, procedure: 25, belief: 20, memory_fragment: 15, association: 10, ... }
+  # ... (each depth has its own probability distribution)
+}
+
+PRESERVATION_LABELS = {
+  (0.8..) => :pristine, (0.6...0.8) => :intact, (0.4...0.6) => :damaged,
+  (0.2...0.4) => :fragmented, (..0.2) => :ruins
+}
+INTEGRITY_LABELS = {
+  (0.85..) => :complete, (0.65...0.85) => :mostly_complete, (0.45...0.65) => :partial,
+  (0.25...0.45) => :fragmentary, (..0.25) => :trace_only
+}
+DENSITY_LABELS = { (0.7..) => :rich, (0.4...0.7) => :moderate, (..0.4) => :sparse }
+DEPTH_LABELS   = {
+  surface: :contemporary, shallow: :recent_history, mid: :historical,
+  deep: :ancient_history, bedrock: :primordial
+}
+```
+
+## Runners
+
+### `Runners::CognitiveArchaeology`
+
+Uses `extend self` — methods are module-level, not instance-delegating. Delegates to a per-call `engine` (parameter-injected `Helpers::ArchaeologyEngine` instance via `engine:` keyword, defaulting to a shared `@engine ||=`).
+
+- `create_site(name:, domain:, engine: @engine)` — register an excavation site with a domain; initializes depth tracking at `:surface`
+- `dig(site_id:, depth_level:, engine: @engine)` — excavate at a specific depth; surfaces artifacts with type probabilities drawn from `DEPTH_RARITY_WEIGHTS[depth_level]`; returns artifact or `:empty` if nothing found
+- `excavate(site_id:, engine: @engine)` — full excavation sweep across all depth levels; returns array of all found artifacts
+- `restore_artifact(artifact_id:, engine: @engine)` — increase preservation and integrity of a damaged artifact; returns restoration result hash
+- `list_artifacts(engine: @engine)` — all artifacts across all sites as array of hashes
+- `archaeology_status(engine: @engine)` — summary: site count, artifact count, depth distribution, average preservation
+
+## Helpers
+
+### `Helpers::ArchaeologyEngine`
+Core engine managing `@sites` and `@artifacts` hashes. `dig_at_depth` performs weighted random draw from `DEPTH_RARITY_WEIGHTS[depth_level]` to determine artifact type, then generates artifact with preservation and integrity values that decrease with depth (surface artifacts are better preserved). `excavate_site` calls `dig_at_depth` for each depth level. `restore` increases preservation and integrity values, clamped to 1.0.
+
+### `Helpers::Artifact`
+Value object: type, depth_level, preservation (0.0–1.0), integrity (0.0–1.0), epoch (one of `EPOCH_NAMES`), site_id, domain. `preservation_label` and `integrity_label` map values to human-readable labels. `recoverable?` returns true when preservation > 0.2 (ruins are not recoverable).
+
+### `Helpers::Site`
+Value object: name, domain, depths_excavated array, artifact_ids array. `excavated_at?(depth_level)` checks whether a depth has been visited. `add_artifact!` records an artifact ID.
+
+## Integration Points
+
+No actor defined. This extension models recovery of deeply buried cognitive content — ancient patterns, procedures, and schemas that are hard to access but high-value. Pairs with lex-memory (archaeology surfaces artifacts that map to memory traces by type: `:memory_fragment` artifacts correlate to `episodic` traces, `:schema` artifacts to `semantic` traces). Pairs with lex-cognitive-apprenticeship (archaeological recovery of a `:procedure` artifact can seed a new apprenticeship). Pairs with lex-dream (dream association walks can trigger archaeology to surface related ancient associations).
+
+## Development Notes
+
+- `extend self` pattern: runner is a module with module-level methods; shared `@engine` lives in the module's singleton
+- `DEPTH_RARITY_WEIGHTS` is the core mechanic: each depth level has its own weighted probability table; deeper levels have higher weights for rare types (`:schema`, `:procedure`) and lower weights for common types (`:pattern`, `:knowledge`)
+- `dig` at `:surface` is more likely to surface `:pattern` and `:knowledge`; `dig` at `:bedrock` is more likely to surface `:schema` and `:procedure`
+- Preservation values decrease with depth: surface artifacts start at high preservation; bedrock artifacts start degraded
+- `restore_artifact` is the repair pathway — callers must actively restore damaged/fragmented artifacts before using them
+- Epoch names (`:recent` to `:ancient`) are assigned based on depth level, providing temporal context for recovered artifacts

data/Gemfile

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

data/README.md

@@ -0,0 +1,62 @@
+# lex-cognitive-archaeology
+
+Cognitive archaeology metaphor for recovering deeply buried cognitive artifacts — excavation sites, depth-weighted artifact discovery, and restoration.
+
+## What It Does
+
+Models the retrieval of deeply buried cognitive content as archaeological excavation. Sites have five depth levels (surface to bedrock), and digging at different depths surfaces different artifact types according to weighted probability tables. Surface digs find common patterns and knowledge; bedrock digs surface rare schemas and procedures. Artifacts degrade with depth — ancient finds need restoration.
+
+## Core Concept: Depth and Rarity
+
+```
+surface  -> common types (pattern, knowledge)     -> high preservation
+shallow  -> mixed types                            -> good preservation
+mid      -> deeper history                         -> moderate preservation
+deep     -> ancient history                        -> degraded
+bedrock  -> primordial (schema, procedure, belief) -> ruins
+```
+
+## Usage
+
+```ruby
+client = Legion::Extensions::CognitiveArchaeology::Client.new
+
+# Open an excavation site
+site = client.create_site(name: :infrastructure_knowledge_base, domain: :infrastructure)
+
+# Dig at a specific depth
+artifact = client.dig(site_id: site[:site][:id], depth_level: :surface)
+# => { artifact: { type: :pattern, preservation: 0.91, integrity: 0.88, epoch: :recent, ... } }
+
+# Dig deeper for rarer artifacts
+deep_find = client.dig(site_id: site[:site][:id], depth_level: :bedrock)
+# => { artifact: { type: :schema, preservation: 0.23, integrity: 0.31, epoch: :ancient, ... } }
+
+# Restore a damaged artifact
+client.restore_artifact(artifact_id: deep_find[:artifact][:id])
+# => { artifact: { preservation: 0.45, integrity: 0.52, ... } }
+
+# Full excavation sweep across all depth levels
+client.excavate(site_id: site[:site][:id])
+# => { artifacts: [...all found artifacts across all depths...] }
+
+# Check overall dig status
+client.archaeology_status
+# => { site_count: 1, artifact_count: 6, depth_distribution: {...}, avg_preservation: 0.61 }
+```
+
+## Integration
+
+Pairs with lex-memory (artifact types map to memory trace types: `:memory_fragment` -> episodic, `:schema` -> semantic). Pairs with lex-cognitive-apprenticeship (a recovered `:procedure` artifact can seed a new apprenticeship). Pairs with lex-dream (dream association walks can trigger archaeology to surface related ancient associations).
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-archaeology.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_archaeology/version'
+
+Gem::Specification.new do |spec|
+  spec.name    = 'lex-cognitive-archaeology'
+  spec.version = Legion::Extensions::CognitiveArchaeology::VERSION
+  spec.authors = ['Esity']
+  spec.email   = ['matthewdiverson@gmail.com']
+
+  spec.summary     = 'LEX Cognitive Archaeology'
+  spec.description = 'Excavates buried cognitive artifacts from deep memory layers — ' \
+                     'uncovers forgotten patterns, dormant skills, and latent knowledge ' \
+                     'that was formed but never fully integrated'
+  spec.homepage = 'https://github.com/LegionIO/lex-cognitive-archaeology'
+  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-archaeology'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-cognitive-archaeology'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-cognitive-archaeology'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-cognitive-archaeology/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveArchaeology
+      class Client
+        include Runners::CognitiveArchaeology
+
+        def initialize(engine: nil)
+          @default_engine = engine || Helpers::ArchaeologyEngine.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_archaeology/helpers/archaeology_engine.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveArchaeology
+      module Helpers
+        class ArchaeologyEngine
+          def initialize
+            @sites     = {}
+            @artifacts = {}
+          end
+
+          def create_site(domain:)
+            validate_site_capacity!
+            site = ExcavationSite.new(domain: domain)
+            @sites[site.id] = site
+            site
+          end
+
+          def dig(site_id:)
+            site = fetch_site!(site_id)
+            dug  = site.dig_deeper!
+            { site: site.survey, dug: dug }
+          end
+
+          def excavate(site_id:)
+            site = fetch_site!(site_id)
+            validate_artifact_capacity!
+            artifact = site.excavate!
+            @artifacts[artifact.id] = artifact
+            artifact
+          end
+
+          def restore_artifact(artifact_id:, boost: 0.15)
+            artifact = fetch_artifact!(artifact_id)
+            artifact.restore!(boost: boost)
+            artifact
+          end
+
+          def decay_all!(rate: Constants::PRESERVATION_DECAY)
+            @artifacts.each_value { |a| a.decay!(rate: rate) }
+            prune_dust!
+            @artifacts.size
+          end
+
+          def artifacts_by_type(type)
+            @artifacts.values.select { |a| a.artifact_type == type.to_sym }
+          end
+
+          def artifacts_by_domain(domain)
+            @artifacts.values.select { |a| a.domain == domain.to_sym }
+          end
+
+          def artifacts_by_depth(depth_level)
+            @artifacts.values.select do |a|
+              a.depth_level == depth_level.to_sym
+            end
+          end
+
+          def best_preserved(limit: 10)
+            @artifacts.values.sort_by { |a| -a.preservation }.first(limit)
+          end
+
+          def most_fragile(limit: 10)
+            @artifacts.values
+                      .select(&:fragment?)
+                      .sort_by(&:preservation)
+                      .first(limit)
+          end
+
+          def site_report(site_id:)
+            fetch_site!(site_id).to_h
+          end
+
+          def archaeology_report
+            {
+              total_artifacts:  @artifacts.size,
+              total_sites:      @sites.size,
+              type_breakdown:   type_breakdown,
+              domain_breakdown: domain_breakdown,
+              depth_breakdown:  depth_breakdown,
+              avg_preservation: avg_preservation,
+              avg_integrity:    avg_integrity,
+              fragment_count:   @artifacts.values.count(&:fragment?),
+              ancient_count:    @artifacts.values.count(&:ancient?),
+              sites:            @sites.values.map { |s| site_summary(s) }
+            }
+          end
+
+          def all_artifacts
+            @artifacts.values
+          end
+
+          def all_sites
+            @sites.values
+          end
+
+          private
+
+          def fetch_site!(site_id)
+            @sites.fetch(site_id) do
+              raise ArgumentError, "site not found: #{site_id.inspect}"
+            end
+          end
+
+          def fetch_artifact!(artifact_id)
+            @artifacts.fetch(artifact_id) do
+              raise ArgumentError,
+                    "artifact not found: #{artifact_id.inspect}"
+            end
+          end
+
+          def validate_site_capacity!
+            return if @sites.size < Constants::MAX_SITES
+
+            raise ArgumentError,
+                  "site capacity reached (max #{Constants::MAX_SITES})"
+          end
+
+          def validate_artifact_capacity!
+            return if @artifacts.size < Constants::MAX_ARTIFACTS
+
+            raise ArgumentError,
+                  "artifact capacity reached (max #{Constants::MAX_ARTIFACTS})"
+          end
+
+          def prune_dust!
+            @artifacts.delete_if { |_, a| a.preservation <= 0.0 }
+          end
+
+          def type_breakdown
+            count_by(:artifact_type, Constants::ARTIFACT_TYPES)
+          end
+
+          def domain_breakdown
+            count_by(:domain, Constants::DOMAIN_TYPES)
+          end
+
+          def depth_breakdown
+            count_by(:depth_level, Constants::EXCAVATION_DEPTH_LEVELS)
+          end
+
+          def count_by(attr, values)
+            values.to_h do |v|
+              [v, @artifacts.values.count { |a| a.public_send(attr) == v }]
+            end
+          end
+
+          def avg_preservation
+            return 0.0 if @artifacts.empty?
+
+            (@artifacts.values.sum(&:preservation) / @artifacts.size).round(10)
+          end
+
+          def avg_integrity
+            return 0.0 if @artifacts.empty?
+
+            (@artifacts.values.sum(&:integrity) / @artifacts.size).round(10)
+          end
+
+          def site_summary(site)
+            site.survey.merge(
+              depth_progress: depth_progress(site),
+              artifact_types: site.artifacts_found
+                              .each_with_object(Hash.new(0)) do |a, h|
+                                h[a.artifact_type] += 1
+                              end
+            )
+          end
+
+          def depth_progress(site)
+            idx   = Constants::EXCAVATION_DEPTH_LEVELS.index(site.current_depth)
+            total = Constants::EXCAVATION_DEPTH_LEVELS.size - 1
+            total.zero? ? 1.0 : (idx.to_f / total).round(4)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_archaeology/helpers/artifact.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveArchaeology
+      module Helpers
+        class Artifact
+          attr_reader :id, :artifact_type, :domain, :content, :depth_level,
+                      :discovered_at, :origin_epoch, :contextual_links
+
+          attr_accessor :preservation_quality, :integrity
+
+          alias type artifact_type
+
+          def initialize(type:, domain:, content:, depth_level:,
+                         preservation: nil, integrity: nil,
+                         origin_epoch: nil, contextual_links: nil)
+            validate_type!(type)
+            validate_domain!(domain)
+            validate_depth!(depth_level)
+
+            @id               = SecureRandom.uuid
+            @artifact_type    = type.to_sym
+            @domain           = domain.to_sym
+            @content          = content.to_s
+            @depth_level      = depth_level.to_sym
+            pres = (preservation || Constants::DEFAULT_PRESERVATION).to_f
+            @preservation_quality = pres.clamp(0.0, 1.0).round(10)
+            @integrity        = (integrity || derive_integrity).clamp(0.0, 1.0).round(10)
+            @discovered_at    = Time.now.utc
+            @origin_epoch     = origin_epoch || (Time.now.utc - rand(0..31_536_000))
+            @contextual_links = Array(contextual_links).dup
+          end
+
+          def preservation
+            @preservation_quality
+          end
+
+          def preservation=(val)
+            @preservation_quality = val.to_f.clamp(0.0, 1.0).round(10)
+          end
+
+          def decay!(rate: Constants::PRESERVATION_DECAY)
+            @preservation_quality = (@preservation_quality - rate.abs).clamp(0.0, 1.0).round(10)
+            @integrity            = (@integrity - (rate.abs * 0.5)).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def restore!(boost: 0.15)
+            @preservation_quality = (@preservation_quality + boost.abs).clamp(0.0, 1.0).round(10)
+            @integrity            = (@integrity + (boost.abs * 0.5)).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def fragment?
+            @preservation_quality < 0.3
+          end
+
+          def well_preserved?
+            @preservation_quality > 0.7
+          end
+
+          def ancient?
+            (Time.now.utc - @origin_epoch) > 15_552_000
+          end
+
+          def preservation_label
+            match_label(Constants::PRESERVATION_LABELS, @preservation_quality)
+          end
+
+          def integrity_label
+            match_label(Constants::INTEGRITY_LABELS, @integrity)
+          end
+
+          def link_to(other_id)
+            @contextual_links << other_id unless @contextual_links.include?(other_id)
+          end
+
+          def to_h
+            {
+              id:                   @id,
+              type:                 @artifact_type,
+              artifact_type:        @artifact_type,
+              domain:               @domain,
+              content:              @content,
+              depth_level:          @depth_level,
+              preservation:         @preservation_quality,
+              preservation_quality: @preservation_quality,
+              preservation_label:   preservation_label,
+              integrity:            @integrity,
+              integrity_label:      integrity_label,
+              discovered_at:        @discovered_at,
+              origin_epoch:         @origin_epoch,
+              contextual_links:     @contextual_links,
+              fragment:             fragment?,
+              well_preserved:       well_preserved?,
+              ancient:              ancient?
+            }
+          end
+
+          private
+
+          def derive_integrity
+            depth_mod = Constants::DEPTH_PRESERVATION_MODIFIER.fetch(@depth_level, 0.0)
+            (0.8 + depth_mod + rand(-0.1..0.1)).clamp(0.0, 1.0)
+          end
+
+          def validate_type!(type_val)
+            return if Constants::ARTIFACT_TYPES.include?(type_val.to_sym)
+
+            raise ArgumentError,
+                  "unknown artifact type: #{type_val.inspect}; " \
+                  "must be one of #{Constants::ARTIFACT_TYPES.inspect}"
+          end
+
+          def validate_domain!(domain_val)
+            return if Constants::DOMAIN_TYPES.include?(domain_val.to_sym)
+
+            raise ArgumentError,
+                  "unknown domain: #{domain_val.inspect}; " \
+                  "must be one of #{Constants::DOMAIN_TYPES.inspect}"
+          end
+
+          def validate_depth!(depth_val)
+            return if Constants::EXCAVATION_DEPTH_LEVELS.include?(depth_val.to_sym)
+
+            raise ArgumentError,
+                  "unknown depth level: #{depth_val.inspect}; " \
+                  "must be one of #{Constants::EXCAVATION_DEPTH_LEVELS.inspect}"
+          end
+
+          def match_label(label_table, value)
+            label_table.each { |range, label| return label if range.cover?(value) }
+            label_table.last.last
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveArchaeology
+      module Helpers
+        module Constants
+          MAX_ARTIFACTS            = 500
+          MAX_SITES                = 50
+          DEFAULT_PRESERVATION     = 0.5
+          PRESERVATION_DECAY       = 0.02
+          SEDIMENT_DENSITY_DEFAULT = 0.5
+
+          ARTIFACT_TYPES = %i[
+            pattern skill knowledge memory_fragment
+            association procedure belief schema
+          ].freeze
+
+          DOMAIN_TYPES = %i[
+            cognitive emotional procedural semantic
+            episodic social creative analytical
+          ].freeze
+
+          EXCAVATION_DEPTH_LEVELS = %i[surface shallow mid deep bedrock].freeze
+
+          EPOCH_NAMES = %i[
+            genesis formation expansion consolidation
+            crisis renewal maturation current
+          ].freeze
+
+          DEPTH_PRESERVATION_MODIFIER = {
+            surface: 0.0,
+            shallow: -0.1,
+            mid:     -0.2,
+            deep:    -0.35,
+            bedrock: -0.5
+          }.freeze
+
+          DEPTH_RARITY_WEIGHTS = {
+            surface: { pattern: 3, skill: 2, knowledge: 3, memory_fragment: 5,
+                       association: 3, procedure: 2, belief: 1, schema: 1 },
+            shallow: { pattern: 3, skill: 3, knowledge: 3, memory_fragment: 4,
+                       association: 3, procedure: 3, belief: 1, schema: 1 },
+            mid:     { pattern: 2, skill: 3, knowledge: 3, memory_fragment: 3,
+                       association: 3, procedure: 3, belief: 2, schema: 2 },
+            deep:    { pattern: 1, skill: 2, knowledge: 2, memory_fragment: 2,
+                       association: 2, procedure: 3, belief: 3, schema: 3 },
+            bedrock: { pattern: 1, skill: 1, knowledge: 1, memory_fragment: 1,
+                       association: 1, procedure: 2, belief: 4, schema: 4 }
+          }.freeze
+
+          PRESERVATION_LABELS = [
+            [0.0..0.2, :dust],
+            [0.2..0.4, :fragmented],
+            [0.4..0.6, :partial],
+            [0.6..0.8, :intact],
+            [0.8..1.0, :pristine]
+          ].freeze
+
+          INTEGRITY_LABELS = [
+            [0.0..0.3, :corrupted],
+            [0.3..0.6, :degraded],
+            [0.6..0.8, :coherent],
+            [0.8..1.0, :complete]
+          ].freeze
+
+          DENSITY_LABELS = [
+            [0.0..0.2, :friable],
+            [0.2..0.4, :loose],
+            [0.4..0.6, :moderate],
+            [0.6..0.8, :dense],
+            [0.8..1.0, :compacted]
+          ].freeze
+
+          DEPTH_LABELS = {
+            surface: 'Surface Layer (recent, well-preserved)',
+            shallow: 'Shallow Layer (familiar but fading)',
+            mid:     'Mid Layer (semi-dormant knowledge)',
+            deep:    'Deep Layer (long-dormant patterns)',
+            bedrock: 'Bedrock Layer (foundational cognitive strata)'
+          }.freeze
+
+          def self.label_for(table, value)
+            table.each { |range, label| return label if range.cover?(value) }
+            table.last.last
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_archaeology/helpers/excavation_site.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveArchaeology
+      module Helpers
+        class ExcavationSite
+          include Constants
+
+          attr_reader :id, :domain, :current_depth, :artifacts_found, :created_at
+
+          alias started_at created_at
+
+          def initialize(domain:)
+            validate_domain!(domain)
+            @id              = SecureRandom.uuid
+            @domain          = domain.to_sym
+            @current_depth   = :surface
+            @artifacts_found = []
+            @created_at      = Time.now.utc
+          end
+
+          def dig_deeper!
+            idx = EXCAVATION_DEPTH_LEVELS.index(@current_depth) || 0
+            return false if idx >= EXCAVATION_DEPTH_LEVELS.size - 1
+
+            @current_depth = EXCAVATION_DEPTH_LEVELS[idx + 1]
+            true
+          end
+
+          def complete?
+            @current_depth == EXCAVATION_DEPTH_LEVELS.last
+          end
+
+          def excavate!
+            weights  = DEPTH_RARITY_WEIGHTS.fetch(@current_depth, {})
+            art_type = weighted_pick(weights)
+            artifact = Artifact.new(type: art_type, domain: @domain,
+                                    content: "#{art_type} from #{@current_depth}",
+                                    depth_level: @current_depth,
+                                    preservation: compute_base_preservation)
+            @artifacts_found << artifact
+            artifact
+          end
+
+          def survey
+            {
+              id:              @id,
+              domain:          @domain,
+              current_depth:   @current_depth,
+              depth_label:     DEPTH_LABELS.fetch(@current_depth, 'Unknown'),
+              artifacts_count: @artifacts_found.size,
+              complete:        complete?,
+              started_at:      @created_at.iso8601
+            }
+          end
+
+          def to_h
+            survey.merge(artifacts: @artifacts_found.map(&:to_h))
+          end
+
+          private
+
+          def validate_domain!(domain_val)
+            return if DOMAIN_TYPES.include?(domain_val.to_sym)
+
+            raise ArgumentError,
+                  "unknown domain: #{domain_val.inspect}; " \
+                  "must be one of #{DOMAIN_TYPES.inspect}"
+          end
+
+          def weighted_pick(weights)
+            total = weights.values.sum
+            return ARTIFACT_TYPES.sample if total.zero?
+
+            roll       = rand(total)
+            cumulative = 0
+            weights.each do |type, weight|
+              cumulative += weight
+              return type if roll < cumulative
+            end
+            weights.keys.last
+          end
+
+          def compute_base_preservation
+            mod = DEPTH_PRESERVATION_MODIFIER.fetch(@current_depth, 0.0)
+            (DEFAULT_PRESERVATION + mod).clamp(0.0, 1.0)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveArchaeology
+      module Runners
+        module CognitiveArchaeology
+          extend self
+
+          def create_site(domain:, engine: nil, **)
+            eng  = resolve_engine(engine)
+            site = eng.create_site(domain: domain)
+            { success: true, site: site.survey }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def dig(site_id:, engine: nil, **)
+            eng    = resolve_engine(engine)
+            result = eng.dig(site_id: site_id)
+            { success: true }.merge(result)
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def excavate(site_id:, engine: nil, **)
+            eng      = resolve_engine(engine)
+            artifact = eng.excavate(site_id: site_id)
+            { success: true, artifact: artifact.to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def restore_artifact(artifact_id:, boost: 0.15, engine: nil, **)
+            eng      = resolve_engine(engine)
+            artifact = eng.restore_artifact(
+              artifact_id: artifact_id, boost: boost
+            )
+            { success: true, artifact: artifact.to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def list_artifacts(engine: nil, type: nil, domain: nil,
+                             depth_level: nil, **)
+            eng     = resolve_engine(engine)
+            results = filter_results(eng.all_artifacts,
+                                     type: type, domain: domain,
+                                     depth_level: depth_level)
+            { success: true, artifacts: results.map(&:to_h),
+              count: results.size }
+          end
+
+          def archaeology_status(engine: nil, **)
+            eng = resolve_engine(engine)
+            { success: true, report: eng.archaeology_report }
+          end
+
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          private
+
+          def filter_results(artifacts, type:, domain:, depth_level:)
+            r = artifacts
+            r = r.select { |a| a.artifact_type == type.to_sym } if type
+            r = r.select { |a| a.domain == domain.to_sym } if domain
+            r = r.select { |a| a.depth_level == depth_level.to_sym } if depth_level
+            r
+          end
+
+          def resolve_engine(engine)
+            engine || default_engine
+          end
+
+          def default_engine
+            @default_engine ||= Helpers::ArchaeologyEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_archaeology.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'cognitive_archaeology/version'
+require_relative 'cognitive_archaeology/helpers/constants'
+require_relative 'cognitive_archaeology/helpers/artifact'
+require_relative 'cognitive_archaeology/helpers/excavation_site'
+require_relative 'cognitive_archaeology/helpers/archaeology_engine'
+require_relative 'cognitive_archaeology/runners/cognitive_archaeology'
+require_relative 'cognitive_archaeology/client'
+
+module Legion
+  module Extensions
+    module CognitiveArchaeology
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-archaeology
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Excavates buried cognitive artifacts from deep memory layers — uncovers
+  forgotten patterns, dormant skills, and latent knowledge that was formed but never
+  fully integrated
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CLAUDE.md
+- Gemfile
+- README.md
+- lex-cognitive-archaeology.gemspec
+- lib/legion/extensions/cognitive_archaeology.rb
+- lib/legion/extensions/cognitive_archaeology/client.rb
+- lib/legion/extensions/cognitive_archaeology/helpers/archaeology_engine.rb
+- lib/legion/extensions/cognitive_archaeology/helpers/artifact.rb
+- lib/legion/extensions/cognitive_archaeology/helpers/constants.rb
+- lib/legion/extensions/cognitive_archaeology/helpers/excavation_site.rb
+- lib/legion/extensions/cognitive_archaeology/runners/cognitive_archaeology.rb
+- lib/legion/extensions/cognitive_archaeology/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-archaeology
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-archaeology
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-archaeology
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-archaeology
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-archaeology
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-archaeology/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Cognitive Archaeology
+test_files: []