lutaml-store 0.2.0 → 0.2.1

data/TODO.impl/0-lutaml-store-self-quality.md

@@ -1,112 +0,0 @@
-# TODO.impl/0-lutaml-store-self-quality.md
-
-# lutaml-store Internal Quality Fixes (prerequisite for migrations)
-
-## Completed
-
-All anti-patterns eliminated from `lib/`:
-
-| Anti-pattern | Remaining in lib/ |
-|---|---|
-| `instance_variable_get/set` | 0 (only a comment reference) |
-| `respond_to?` | 0 (only a comment reference) |
-| `send` on private methods | 0 |
-
-### Changes made
-
-1. **Created `ModelSerializer`** — unified serialization/deserialization into one class, eliminating `respond_to?` chains and duplicated code across `DatabaseStore`, `CompositeModelHandler`, `Serializer`.
-2. **Added `Store#emit_event`** public method — eliminated `instance_variable_get(:@events)`.
-3. **Fixed `AttributeUpdater`** — uses proper constructors instead of `instance_variable_set/get`.
-4. **Fixed `CacheStore`** — uses proper factory methods.
-5. **Removed `respond_to?` from adapters** — calls methods directly on `Adapter::Base` interface.
-6. **Removed `CacheInspector`** — unused code.
-7. **Added custom serializer support** — `ModelRegistration` accepts `serializer:` option for models with non-standard serialization (e.g., glossarist's `key_value` DSL).
-
-## Anti-pattern audit (current state)
-
-### 1. `instance_variable_get` / `instance_variable_set` — breaks encapsulation
-
-| File | Line | Usage |
-|---|---|---|
-| `database_store.rb` | 375 | `@store.instance_variable_get(:@events)&.emit(event, data)` |
-| `model_store.rb` | 230 | Same pattern — reaching into `@store`'s internals |
-| `attribute_updater.rb` | 228 | `model.instance_variable_set(var, upgraded_model.instance_variable_get(var))` — polymorphic upgrade hack |
-| `cache_store.rb` | 45 | `entry.instance_variable_set(:@created_at, ...)` — bypassing constructor |
-
-**Fix:** Expose proper public APIs on the objects being accessed:
-- `Store` should expose `emit_event(event, data)` as a public method.
-- `AttributeUpdater#try_polymorphic_upgrade` must use proper constructors or
-  `Lutaml::Model::Serializable`'s own API — never copy instance variables.
-- `CacheStore` should use factory methods or proper attribute setters.
-
-### 2. `respond_to?` — poor typing / duck-typing smell
-
-**24 occurrences across the codebase.** The worst offenders:
-
-| File | Pattern | Fix |
-|---|---|---|
-| `composite_model_handler.rb` L102-133 | `respond_to?(:to_hash)`, `respond_to?(:from_hash)` | All models are `Lutaml::Model::Serializable` — use `is_a?` checks against a serialization protocol, or better, use `to_hash` directly via the type system |
-| `database_store.rb` L288-327 | Same serialization dispatch via `respond_to?` | Extract a `SerializationAdapter` that knows how to (de)serialize `Lutaml::Model::Serializable` |
-| `attribute_updater.rb` L87-129 | `respond_to?(setter_method)` | Use the model's attribute metadata from `Lutaml::Model::Serializable.attributes` |
-| `serializer.rb` | 14 occurrences | Full rewrite needed — see below |
-| `http_cache.rb` L112-142 | `@adapter.respond_to?(:clear)` | All adapters inherit from `Adapter::Base` which defines `#clear` — just call it |
-
-**Fix strategy:**
-- Create a `Serializable` protocol module (`Lutaml::Store::Serializable`) that
-  formalizes the serialization contract (`to_store_hash`, `from_store_hash`).
-- Replace all `respond_to?` with type-based dispatch or method calls on known base classes.
-- For attribute validation, use `model.class.attributes` (from Lutaml::Model).
-
-### 3. Duplicated serialization logic
-
-`DatabaseStore#serialize_model`, `DatabaseStore#deserialize_model`,
-`CompositeModelHandler#serialize_model`, `CompositeModelHandler#deserialize_model`
-all contain identical `respond_to?` chains for `(to_hash|to_h|to_s)` and
-`(from_hash|from_h|new)`.
-
-**Fix:** Extract a single `Lutaml::Store::ModelSerializer` class:
-
-```ruby
-class ModelSerializer
-  def serialize(model)
-    model.to_hash.merge("_class" => model.class.name)
-  end
-
-  def deserialize(data, expected_class)
-    klass = Object.const_get(data["_class"])
-    klass.from_hash(data.except("_class", "_composite_models"))
-  end
-end
-```
-
-Since all registered models are `Lutaml::Model::Serializable`, they all have
-`to_hash` and `from_hash`. No need for duck-typing fallback chains.
-
-### 4. Event emission through encapsulation violation
-
-Both `DatabaseStore` and `ModelStore` emit events via:
-```ruby
-@store.instance_variable_get(:@events)&.emit(event, data)
-```
-
-**Fix:** Add `Store#emit_event(event, data)` as a public method. The `events`
-object is an internal implementation detail and should not be leaked.
-
-### 5. `CacheInspector` — untested, unused?
-
-Check if `cache_inspector.rb` is actually used anywhere. If not, remove it.
-
-### 6. Open/closed principle violations
-
-- `AttributeUpdater#try_polymorphic_upgrade` uses `instance_variable_set` and
-  `model.extend(registered_class)` — this is metaprogramming that breaks OCP.
-  Instead, create a new model instance of the subclass and replace the reference.
-
-## Implementation order
-
-1. **Add `Store#emit_event` public method** — eliminates `instance_variable_get(:@events)`.
-2. **Create `ModelSerializer`** — unify all serialization/deserialization into one class. Eliminates `respond_to?` chains and duplicated code.
-3. **Fix `AttributeUpdater`** — remove `try_polymorphic_upgrade`'s `instance_variable_set/get`. Use proper factory pattern.
-4. **Fix `CacheStore`** — use proper constructor/factory instead of `instance_variable_set`.
-5. **Remove `respond_to?` from adapters** — call methods directly on `Adapter::Base` interface.
-6. **Audit specs** — add specs that verify no `send`, no `instance_variable_get/set`, no `respond_to?` regressions.

data/TODO.impl/1-lutaml-hal-migration.md

@@ -1,96 +0,0 @@
-# TODO.impl/1-lutaml-hal-migration.md
-
-# Migration Plan: lutaml-hal → lutaml-store
-
-## Completed
-
-### Anti-pattern elimination (all done)
-
-All `instance_variable_set/get`, `send(:private_method)`, and `respond_to?` calls
-have been eliminated from `lib/lutaml/hal/`.
-
-| File | Changes |
-|---|---|
-| `resource.rb` | Added `embedded_data=` setter; `from_embedded` uses `public_send` instead of `instance_variable_set` |
-| `page.rb` | `instance_variable_get` → `public_send(Hal::REGISTER_ID_ATTR_NAME)` |
-| `model_register.rb` | All methods used by Link made public; `instance_variable_set` → `embedded_data=`; `instance_variable_set` for register ID → `public_send(setter)`; `send(key)` → `public_send(key)`; `respond_to?(:status)` → `faraday_response?(response) && response.status == 304` |
-| `link.rb` | Removed all `register.send(:private_method, ...)` calls (4 instances); `instance_variable_get` → `public_send`; `respond_to?(:embedded_data)` → `is_a?(Resource)` type check |
-| `global_register.rb` | Removed `respond_to?` checks from `clear_all_caches` and `cache_stats` |
-| `cache/cache_metadata.rb` | Extracted `ResponseHeaders` and `ResponseStatus` modules replacing `respond_to?` proc lambdas |
-| `cache/cache_manager.rb` | `respond_to?` → `rescue NoMethodError` for optional methods; `is_a?` type check for HttpCache; proper HttpCache API delegation (`get(:get, url)`, `set(:get, url, {}, response)`) |
-| `rate_limiter.rb` | Simplified with `is_a?` type check |
-
-### Cache architecture fixes
-
-- `http_aware?` now requires explicit opt-in (`http_aware == true`) instead of defaulting to true when HttpCache is available
-- `CacheManager` properly delegates to `HttpCache`'s method/url API (`get(:get, url)`, `set(:get, url, {}, response)`, `delete(:get, url)`)
-- Non-http-aware path uses `SimpleCacheStore` (in-memory, no serialization) instead of `CacheStore` (which JSON-serializes and can't handle `CacheEntry` objects)
-- Removed `create_basic_cache` method (no longer needed)
-
-### Spec fixes
-
-- `cache_integration_spec.rb`: Fixed `REGISTER_ID_ATTR_NAME` (requires `lutaml/hal` instead of redefining constant); added `status: 200` to mock responses; fixed cache key in legacy test; removed `instance_variable_get`/`send` usage
-- `cache_manager_spec.rb`: Updated stats tests to stub `stats` (not `cache_info`); updated `http_aware_cache?` test to use `is_a?` instead of `respond_to?`; fixed `get_from_http_cache` test signature
-- `cache_configuration_spec.rb`: Fixed `http_aware?` nil default expectation; fixed adapter_config error type
-- `cache_metadata_spec.rb`: Added `status: 200` to test doubles
-
-### Test results
-
-- **lutaml-hal**: 210 examples, 0 failures
-- **lutaml-store**: 248 examples, 1 pre-existing failure (vary header spec) + 25 pre-existing failures in HTTP cache integration specs
-- **Anti-patterns in lib code**: 0 `instance_variable_set/get`, 0 `send`, 0 `respond_to?`
-
-## Implemented in lutaml-hal#15
-
-The realized-object cache (relaton/w3c_api#11) is working and opt-in
-(`ModelRegister.new(..., cache: {...})`; no config keeps the previous
-behavior). Delivered across four commits on `rt-add-lutaml-store`:
-
-### Phase 1: Make caching work / unify through lutaml-store — done (adapted)
-
-- The cache path was crashing; fixed: require `lutaml/store` (so its autoloads
-  resolve), route `Link#realize` through the public `cache_manager` API, add
-  `Client#get_by_url_with_headers`, remove `Client`'s legacy `@cache` Hash,
-  make HTTP-aware caching explicit opt-in.
-- **Deviation:** instead of a `HalStore` wrapper, `CacheManager` uses
-  lutaml-store's `CacheStore` directly for persistent adapters and keeps
-  `SimpleCacheStore` for the in-memory adapter (so cache hits avoid
-  serialization). `SimpleCacheStore` was therefore retained, not removed.
-
-### Phase 2: Register ID / embedded data as proper attributes — done
-
-- Dropped the `Hal::REGISTER_ID_ATTR_NAME` constant and all dynamic
-  `instance_variable_get/set("@#{...}")`; `Resource`/`Link`/`LinkSet` use
-  `attr_accessor :_global_register_id`, embedded data is an `attr_accessor`.
-- Also removed the remaining `register.send(:private_method)` calls from
-  `Link` by making `ModelRegister#find_matching_model_class` public.
-
-### Phase 3: Persistence + URL keying — done (alternative to model-registry)
-
-- **URL keying:** `CacheManager` canonicalizes relative URLs to absolute before
-  keying, so a resource fetched by endpoint path and the same resource realized
-  from an absolute link href share one entry (the core repeated-realize fix).
-- **Persistence — decision:** rather than registering HAL resource classes in
-  lutaml-store's model registry, `CacheEntry` gained a JSON storage form
-  (records the model class + lutaml-model JSON). With a `filesystem`/`sqlite`
-  adapter the cache persists via `Lutaml::Store::CacheStore` and rebuilds models
-  on retrieval. This keeps the cache shape (`URL => entry`) and was chosen over
-  the model-registry approach, whose `fetch(model:, key:)` API fits poorly with
-  a heterogeneous URL→object lookup. Note: persisted entries require **named**
-  resource classes with explicit `key_value` mappings.
-
-## Still remaining
-
-### HTTP-aware response cache (deferred)
-
-Backing the HTTP-aware mode with lutaml-store's `HttpCache` (ETag / 304
-revalidation against a cached response) is left as scaffolding
-(`create_http_cache` / `*_http_cache` in `CacheManager`). It needs a realized
-model to be reconstructed from a cached response (i.e. knowing the resource
-class at read time) and is not required for the realized-object caching in #11.
-
-### Release coordination
-
-lutaml-hal#15 depends on lutaml-store via a `path:` Gemfile entry. lutaml-store
-needs a tagged release before lutaml-hal can depend on a published version and
-the PR can ship.

data/TODO.impl/2-glossarist-migration.md

@@ -1,359 +0,0 @@
-# TODO.impl/2-glossarist-migration.md
-
-# Migration Plan: glossarist-ruby → lutaml-store
-
-## Current state analysis
-
-### How glossarist stores LutaML model objects
-
-Glossarist is the most complex of the three repos. It manages glossary/terminology
-concepts with multiple versions (v1, v2, v3) and several storage mechanisms:
-
-1. **Filesystem YAML persistence** — `ConceptManager` reads/writes concept YAML
-   files from a directory structure. Concepts are stored as:
-   - `concept/{uuid}.yaml` — the managed concept
-   - `localized_concept/{uuid}.yaml` — per-language localizations
-   - Grouped files: `{uuid}.yaml` containing concept + all localizations
-
-2. **ZIP package (GCR format)** — `GcrPackage` reads/writes concepts from ZIP
-   archives containing `metadata.yaml`, `concepts/*.yaml`, optional compiled
-   formats (TBX, JSON-LD, Turtle), and dataset assets.
-
-3. **In-memory collections** — `ManagedConceptCollection`, `Collection`,
-   `Collections::Collection`, `Collections::TypedCollection` — all use plain
-   Arrays/Hashes to hold models in memory.
-
-### Architecture (current)
-
-```
-Glossarist module
-├── Collection (v1)
-│     ├── @index (Hash id → Concept)
-│     ├── @path (String — filesystem path)
-│     ├── load_concepts → Dir.glob → Concept.from_yaml
-│     └── save_concepts → File.write(Psych.dump)
-│
-├── ManagedConceptCollection (v2/v3)
-│     ├── @managed_concepts (Array)
-│     ├── @managed_concepts_ids (Hash id → uuid)
-│     ├── load_from_files → ConceptManager
-│     └── save_to_files → ConceptManager
-│
-├── ConceptManager
-│     ├── path, localized_concepts_path
-│     ├── load_from_files → Dir.glob → ConceptDocument.from_yamls → ManagedConcept
-│     ├── save_to_files → File.write(to_yaml)
-│     ├── save_grouped_concepts_to_files
-│     └── Versioned concept document classes (v2, v3)
-│
-├── GcrPackage
-│     ├── write → Zip::File → concept YAMLs + metadata
-│     ├── read → Zip::File → parse → ManagedConcept instances
-│     └── Compiled format generation (TBX, JSON-LD, Turtle)
-│
-├── ConceptCollector
-│     └── Static methods for scanning directories, detecting schema versions
-│
-└── Model classes (all Lutaml::Model::Serializable):
-      ├── ManagedConcept (key: identifier/uuid)
-      ├── LocalizedConcept (inherits Concept)
-      ├── ConceptData
-      ├── Designation::Base (polymorphic)
-      ├── DetailedDefinition
-      ├── ConceptSource
-      └── ... many more
-```
-
-### Key observations
-
-**Glossarist has no storage abstraction.** File I/O is scattered across:
-- `Collection#load_concepts`, `Collection#save_concept_to_file`
-- `ConceptManager#load_concept_from_file`, `ConceptManager#save_concept_to_file`
-- `GcrPackage#write`, `GcrPackage#read`
-- `ConceptCollector` (static methods doing Dir.glob)
-
-**Every storage operation is ad-hoc:**
-- YAML serialization uses `Lutaml::Model::Serializable#to_yaml` / `.from_yaml`
-- File naming uses concept UUIDs
-- Directory layout is version-dependent
-- ZIP packaging duplicates the filesystem logic
-
-### Problems identified
-
-| Category | Issue | Location |
-|---|---|---|
-| **No storage abstraction** | File I/O is in `ConceptManager`, `Collection`, `GcrPackage`, `ConceptCollector` — no single persistence layer | Multiple |
-| **MECE violation** | `ManagedConceptCollection` manages an Array + a separate id→uuid Hash — this is a database, but hand-rolled | `managed_concept_collection.rb` |
-| **DRY violation** | YAML file I/O patterns repeated in `Collection`, `ConceptManager`, `GcrPackage` | Multiple |
-| **Schema version branching** | Version detection (v1/v2/v3) is sprinkled through `ConceptCollector`, `ConceptManager`, `SchemaMigration` | Multiple |
-| **Lazy loading missing** | `Collection` has a TODO: "Add support for lazy concept loading" — all concepts loaded eagerly into memory | `collection.rb:4` |
-| **OCP violation** | Adding a new storage backend (e.g., database) requires modifying `ConceptManager`, `Collection`, and `GcrPackage` | Multiple |
-
-## Migration strategy
-
-### Phase 1: Define a `ConceptStore` interface backed by lutaml-store
-
-The core insight: Glossarist's concept management is a CRUD store with:
-- **Model:** `ManagedConcept` (key: `uuid`)
-- **Composite models:** `LocalizedConcept` instances per language
-- **Backends:** Filesystem YAML, ZIP archive, and (future) SQLite
-
-```ruby
-module Glossarist
-  class ConceptStore
-    def initialize(adapter:, schema_version: "3")
-      @store = Lutaml::Store.new(
-        adapter: adapter,
-        models: [
-          {
-            model: Glossarist::ManagedConcept,
-            key: :uuid,
-            polymorphic_class_key: nil
-          },
-          {
-            model: Glossarist::LocalizedConcept,
-            key: :uuid
-          }
-        ]
-      )
-      @schema_version = schema_version
-    end
-
-    # CRUD operations
-    def save(managed_concept) = @store.save(managed_concept)
-    def fetch(uuid) = @store.fetch(model: ManagedConcept, uuid: uuid)
-    def fetch_by_id(id) = where(model: ManagedConcept, identifier: id).first
-    def update(uuid, **attrs) = @store.update(model: ManagedConcept, uuid: uuid, attributes: attrs)
-    def delete(uuid) = @store.destroy(model: ManagedConcept, uuid: uuid)
-
-    # Query
-    def all = @store.all(model: ManagedConcept)
-    def where(model:, **conditions) = @store.where(model: model, **conditions)
-    def count = @store.count(model: ManagedConcept)
-
-    # Composite model access
-    def fetch_localized(managed_concept_uuid, lang)
-      concept = fetch(managed_concept_uuid)
-      concept&.localization(lang)
-    end
-  end
-end
-```
-
-### Phase 2: Implement filesystem adapter for Glossarist
-
-Glossarist's filesystem layout is specific:
-
-```
-concepts/
-  concept/
-    {uuid}.yaml
-  localized_concept/
-    {uuid}.yaml
-```
-
-This maps to lutaml-store's FileSystem adapter with custom path resolution:
-
-```ruby
-store = Glossarist::ConceptStore.new(
-  adapter: {
-    type: :filesystem,
-    path: "/path/to/concepts",
-    extension: "yaml",
-    # Custom naming: use uuid as filename, organize by model type
-    naming_strategy: :uuid,
-    directory_layout: {
-      ManagedConcept => "concept",
-      LocalizedConcept => "localized_concept"
-    }
-  }
-)
-```
-
-This requires extending lutaml-store's FileSystem adapter to support:
-- **Custom directory layout** (model type → subdirectory)
-- **Custom key-to-filename mapping** (UUID-based naming)
-- **YAML serialization** (already supported by lutaml-model)
-
-Alternatively, add a `Glossarist::Adapters::YamlFilesystem` adapter that
-implements `Lutaml::Store::Adapter::Base`.
-
-### Phase 3: Implement ZIP archive adapter
-
-GCR packages are ZIP archives. Create a `Glossarist::Adapters::ZipArchive`
-adapter:
-
-```ruby
-class ZipArchive < Lutaml::Store::Adapter::Base
-  def initialize(config)
-    @zip_path = config[:path]
-    # ...
-  end
-
-  def save(key, data, metadata = {})
-    Zip::File.open(@zip_path, create: true) do |zf|
-      zf.get_output_stream(key_to_entry_name(key)) do |f|
-        f.write(data.to_yaml)
-      end
-    end
-  end
-
-  def load(key)
-    Zip::File.open(@zip_path) do |zf|
-      entry = zf.find_entry(key_to_entry_name(key))
-      entry&.get_input_stream&.read
-    end
-  end
-  # ... implement remaining Adapter::Base methods
-end
-```
-
-This makes `GcrPackage` a thin wrapper around `ConceptStore` with a ZIP adapter.
-
-### Phase 4: Migrate `ManagedConceptCollection`
-
-Replace the hand-rolled Array + Hash index with `ConceptStore`:
-
-```ruby
-class ManagedConceptCollection
-  def initialize(store:)
-    @store = store  # Glossarist::ConceptStore
-  end
-
-  def fetch(uuid) = @store.fetch(uuid)
-  def store(concept) = @store.save(concept)
-  def each(&block) = @store.all.each(&block)
-
-  # Remove: @managed_concepts array, @managed_concepts_ids hash
-  # Remove: load_from_files, save_to_files (delegate to store)
-end
-```
-
-### Phase 5: Migrate `Collection` (v1)
-
-The v1 `Collection` follows the same pattern but simpler:
-
-```ruby
-class Collection
-  def initialize(store:)
-    @store = store
-  end
-
-  def fetch(id) = @store.fetch_by_id(id)
-  def store(concept) = @store.save(concept)
-  # Remove: @index, @path, load_concepts, save_concepts
-end
-```
-
-### Phase 6: Migrate `GcrPackage`
-
-`GcrPackage` becomes a factory that creates a `ConceptStore` with a ZIP adapter:
-
-```ruby
-class GcrPackage
-  def self.load(zip_path)
-    store = ConceptStore.new(adapter: { type: :zip, path: zip_path })
-    metadata = load_metadata(zip_path)
-    concepts = store.all
-    new(zip_path, metadata, concepts)
-  end
-
-  def self.create(concepts:, metadata:, output_path:, **opts)
-    store = ConceptStore.new(adapter: { type: :zip, path: output_path })
-    store.save(concepts)
-    write_metadata(output_path, metadata)
-    # Compiled format generation stays here — it's a presentation concern
-  end
-end
-```
-
-### Phase 7: Migrate `ConceptCollector`
-
-`ConceptCollector` currently has 230 lines of directory-scanning logic.
-With lutaml-store, most of this becomes:
-
-```ruby
-def collect(dir)
-  store = ConceptStore.new(adapter: { type: :filesystem, path: dir })
-  store.all
-end
-```
-
-Version detection logic moves into the adapter layer.
-
-## Completed
-
-### Phase 1: ConceptStore with custom serializer (done)
-
-Created `Glossarist::ConceptStore` backed by `Lutaml::Store` with full CRUD.
-
-**Problem:** `ManagedConcept` uses `key_value` DSL that maps both `uuid` and
-`identifier` to the same `"id"` hash key — lossy for storage.
-
-**Solution:** Added pluggable serializer support to lutaml-store:
-- `ModelRegistration` now accepts `serializer:` option
-- `ModelSerializer` delegates to custom serializer when registered
-- Created `Glossarist::ConceptSerializer` — attribute-based serialization that
-  uses attribute names as hash keys (bypasses `key_value` mappings entirely)
-
-| File | Change |
-|---|---|
-| `lutaml-store/lib/lutaml/store/model_registration.rb` | Added `serializer` attr_reader and option |
-| `lutaml-store/lib/lutaml/store/model_serializer.rb` | Accepts `registration` param, delegates to custom serializer |
-| `lutaml-store/lib/lutaml/store/database_store.rb` | Passes registration to serialize/deserialize calls |
-| `lutaml-store/spec/lutaml/store/custom_serializer_spec.rb` | 4 specs for custom serializer feature |
-| `glossarist/lib/glossarist/concept_serializer.rb` | Attribute-based serializer for ManagedConcept |
-| `glossarist/lib/glossarist/concept_store.rb` | CRUD store backed by lutaml-store with custom serializer |
-| `glossarist/lib/glossarist.rb` | Autoloads for ConceptSerializer, ConceptStore |
-| `glossarist/Gemfile` | Fixed lutaml-store path (`../../lutaml/lutaml-store`) |
-| `glossarist/glossarist.gemspec` | Added `lutaml-store ~> 0.1.0` dependency |
-| `glossarist/spec/unit/concept_serializer_spec.rb` | 4 specs for serializer round-trip |
-| `glossarist/spec/unit/concept_store_spec.rb` | 12 specs for full CRUD |
-
-### Test results
-
-- **lutaml-store:** 19 core specs pass (database_store + custom_serializer)
-- **glossarist:** 1154 examples, 0 failures (no regressions)
-
-## Remaining (future work)
-
-| File | Purpose |
-|---|---|
-| `lib/glossarist/concept_store.rb` | Glossarist-specific store backed by `Lutaml::Store` |
-| `lib/glossarist/adapters/yaml_filesystem.rb` | Custom filesystem adapter for Glossarist's YAML layout |
-| `lib/glossarist/adapters/zip_archive.rb` | ZIP archive adapter for GCR packages |
-
-## Files to modify
-
-| File | Change |
-|---|---|
-| `managed_concept_collection.rb` | Replace Array/Hash with `ConceptStore`; remove `load_from_files`/`save_to_files` |
-| `collection.rb` | Replace `@index` with `ConceptStore`; remove `load_concepts`/`save_concepts` |
-| `gcr_package.rb` | Use `ConceptStore` with ZIP adapter; keep compiled format generation |
-| `concept_manager.rb` | Simplify to delegate to `ConceptStore`; remove raw File I/O |
-| `concept_collector.rb` | Replace directory scanning with `ConceptStore.new(...).all` |
-| `glossarist.rb` | Add autoloads for new classes |
-
-## Spec coverage needed
-
-1. **ConceptStore CRUD** — save, fetch, update, delete for ManagedConcept
-2. **Composite model storage** — LocalizedConcept stored independently
-3. **Filesystem adapter** — reads/writes Glossarist's directory layout
-4. **ZIP adapter** — round-trip through GCR packages
-5. **Schema version handling** — v1, v2, v3 concepts load correctly
-6. **Lazy loading** — concepts loaded on demand, not all at once
-7. **Migration backward compatibility** — existing YAML files still readable
-
-## Risks
-
-- **High complexity:** Glossarist has v1/v2/v3 schema migration paths. The
-  storage layer must handle all versions transparently.
-- **Medium risk:** ZIP adapter must handle streaming mode for large glossaries.
-- **Low risk:** Replacing `ManagedConceptCollection`'s Array — straightforward
-  delegation.
-
-## Dependencies
-
-- **lutaml-store must first** support custom filesystem layouts and YAML
-  serialization natively. See `0-lutaml-store-self-quality.md`.
-- **lutaml-store adapter interface** may need extension for ZIP archive support.