shoko 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5060375164152dd31808e0548f1a525246af0d4708e037eb3590423730d4d6c6
-  data.tar.gz: a71558d1f38594e40ffe44d80f4d05dcdd1d1c43a23bb003ab42f74c9ffffeec
+  metadata.gz: a52dba22d1ec1059543f62821ab8e1bf7236def9a0cb8ef2376b13434faf2f03
+  data.tar.gz: 2da5e4f6c6b7a31702f7b9c9fe1786b02895f1588415a215ab0130068eebfb33
 SHA512:
-  metadata.gz: 89e5372ed7369bb5631b4c190311303bbe8285602d5d7520060dc91f3c176c903f269a491d8b436f2c1d280717ddffd8b3498560aab076d7f7b7598ff76be0e8
-  data.tar.gz: b6ca5f48134e099a7b112c517bfa7efeb683606e3d25e66cdc27c8e6c6711615f49a7d2d7c4c75b7ef801e2d4286b3be8f3911dd00d726598093ee583c562198
+  metadata.gz: acbbf2c9f160186d0cf41a3a8ed41efeb60be2f261398f80d2e9318eb0573f9c1ef47bb6f01851c9cdec6a42f8409b99b4b789d36e9d0af36491c3000cfbaa88
+  data.tar.gz: 6756ad75a6ffcfe850b99958f30440f35800a602d910115b1e79a59bfdb0afc3d06d4558c5f8f114eac15a3281acccfd8948b10a508c22b1aee952c66c41d4c8

data/.bundle/config

@@ -1,3 +1,2 @@
 ---
 BUNDLE_PATH: "vendor/bundle"
-BUNDLE_WITHOUT: "development"

data/.rubocop.yml

@@ -1,6 +1,5 @@
 plugins:
   - rubocop-performance
-  - rubocop-rails
 
 AllCops:
   TargetRubyVersion: 3.3
@@ -36,24 +35,45 @@ Metrics/MethodLength:
   CountComments: false
   AllowedMethods:
     - 'initialize'
+    # Data schema definition - just a hash literal
+    - 'build_initial_state'
+    # Character-by-character algorithms where splitting obscures logic
+    - 'sanitize'
+    - 'wrap_cells'
+    - 'truncate_to'
   Exclude:
     - 'spec/**/*'
     - 'test/**/*'
 
 Metrics/AbcSize:
   Max: 20
+  AllowedMethods:
+    # Character-by-character algorithms
+    - 'wrap_cells'
+    - 'sanitize'
+    - 'truncate_to'
   Exclude:
     - 'spec/**/*'
     - 'test/**/*'
 
 Metrics/CyclomaticComplexity:
   Max: 8
+  AllowedMethods:
+    # Character-by-character algorithms - inherent complexity
+    - 'sanitize'
+    - 'truncate_to'
+    - 'wrap_cells'
   Exclude:
     - 'spec/**/*'
     - 'test/**/*'
 
 Metrics/PerceivedComplexity:
   Max: 9
+  AllowedMethods:
+    # Character-by-character algorithms - inherent complexity
+    - 'sanitize'
+    - 'truncate_to'
+    - 'wrap_cells'
   Exclude:
     - 'spec/**/*'
     - 'test/**/*'
@@ -71,6 +91,20 @@ Metrics/BlockLength:
     - 'spec/**/*'
     - 'test/**/*'
 
+# Naming
+Naming/PredicateMethod:
+  # Allow handler methods that return boolean for control flow
+  AllowedMethods:
+    - handle_overlay_click
+    - handle_sidebar_interaction
+    - handle_sidebar_tab_click
+    - handle_sidebar_toc_click
+    - handle_sidebar_wheel
+    - handle_sidebar_scroll_drag
+    - start_sidebar_scroll_drag
+    - cancel_via_ui
+    - dispatch_to_mode
+
 # Style
 Style/Documentation:
   Enabled: true
@@ -119,6 +153,3 @@ Lint/UselessAssignment:
 
 Lint/DuplicateMethods:
   Enabled: true
-
-Rails:
-  Enabled: false

data/Gemfile

@@ -6,6 +6,7 @@ gemspec
 
 group :development do
   gem 'reek'
+  gem 'rake'
   gem 'rubocop', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-rails', require: false
@@ -16,4 +17,5 @@ group :test do
   gem 'fakefs', require: 'fakefs/spec_helpers'
   gem 'rspec'
   gem 'simplecov', require: false
+  gem 'webmock', require: false
 end

data/README.md

@@ -15,10 +15,42 @@ Terminal ebook reader for EPUB files.
 ## How it works
 
 - `bin/start` runs the CLI and enters menu mode or opens a file directly.
+- `bootstrap` is the only runtime wiring boundary (`Bootstrap::ContainerFactory`).
 - State lives in a single store; actions update state and selectors read it.
 - Rendering is component-based and drawn through a terminal buffer with diff updates.
 - Selection/highlighting uses recorded line geometry from the render pass.
 
+## Architecture boundaries
+
+- Hexagonal layering is enforced.
+- `core` contains domain models/services and the single ports root.
+- Ports are split by direction only:
+- `Core::Ports::Inbound::*` (driving boundary into application use cases).
+- `Core::Ports::Outbound::*` (driven dependencies implemented by adapters).
+- `application` contains use-case/workflow/service orchestration only.
+- `adapters` contains all input, UI, output, runtime, monitoring, and storage implementations.
+- `bootstrap` is the only composition root and the only layer that mutates/resolves the container.
+- Reader runtime controller graph composition is bootstrap-only (`ContainerFactory::ControllerComposition::ReaderBuilder`).
+
+Canonical runtime layout:
+
+```text
+lib/shoko/
+  core/ports/{inbound,outbound}
+  application/{use_cases,services,workflows}
+  adapters/{input,ui,output,runtime,storage,monitoring}
+  bootstrap/{container_factory,dependencies}
+  shared/
+```
+
+Inbound command boundary:
+
+- `Core::Ports::Inbound::CommandBus`
+- `Core::Ports::Inbound::ReaderIntentHandler`
+- `Core::Ports::Inbound::MenuIntentHandler`
+- Implemented by `Application::UseCases::CommandBus`
+- Input symbols are dispatched through `ReaderIntentCommand`, `MenuIntentCommand`, and `SharedIntentCommand`
+
 ## Usage
 
 From source:
@@ -34,12 +66,27 @@ Open a file directly:
 bin/start /path/to/book.epub
 ```
 
+Import a folder of ebooks from CLI:
+
+```bash
+bin/start /path/to/books-directory
+```
+
+This scans the directory recursively (skipping hidden files/folders), shows counts by format, and lets you:
+
+- import all discovered files
+- import only one file type
+- exit without importing
+
+After import, Shoko opens menu mode by default.
+
 Options:
 
 - `-d`, `--debug` Enable debug logging.
 - `--log PATH` Write JSON logs to PATH.
 - `--log-level LEVEL` Set log level (`debug`, `info`, `warn`, `error`, `fatal`).
 - `--profile PATH` Write a concise performance profile to PATH.
+- `-v`, `--version` Show version.
 - `-h`, `--help` Show help.
 
 ## Controls (basics)
@@ -69,7 +116,6 @@ Reader:
   - `config.json`
   - `annotations.json`, `bookmarks.json`, `progress.json`, `recent.json`
   - `downloads/` (Gutendex downloads)
-  - `epub_cache.json` (scan cache)
 - Cache: `~/.cache/shoko/`
 
 ## Logging and profiling
@@ -80,3 +126,56 @@ You can also configure logging with environment variables:
 - `SHOKO_LOG_PATH=/path/to/log` Write JSON logs to a file.
 - `SHOKO_LOG_LEVEL=info` Set log level.
 - `SHOKO_PROFILE_PATH=/path/to/profile` Write a performance profile.
+
+## Testing
+
+Required guardrails lane:
+
+```bash
+bundle exec rake test:guardrails
+```
+
+Required non-fixture lane (runs 3 fixed seeds):
+
+```bash
+bundle exec rake test:required
+```
+
+Real-book fixture lane:
+
+```bash
+SHOKO_BOOK_FIXTURES=1 SHOKO_FIXTURES_DIR=/path/to/book-fixtures bundle exec rake test:fixtures
+```
+
+Full suite sanity:
+
+```bash
+bundle exec rspec
+```
+
+## Benchmarking
+
+Run the built-in snappiness benchmark:
+
+```bash
+bundle exec ruby script/bench/snappiness_benchmark.rb
+```
+
+The benchmark prints baseline vs optimized timings for:
+
+- `TextMetrics.visible_length` cache impact
+- `TextMetrics.visible_length` ASCII fast-path impact
+- `TextMetrics.truncate_to` ASCII fast-path impact
+- `TextMetrics.wrap_plain_text` cache impact
+- `TextMetrics.wrap_plain_text` result-cache impact
+- `LineAssembler.build` cache impact
+- `LineAssembler::Tokenizer.tokenize` cache impact
+- `LineAssembler.build` tokenize-cache impact
+- `LineAssembler.build` token-width-hints impact
+- `LineAssembler.build` token-pipeline combined impact
+- `WrappingService.wrap_window` prefetch-range reuse impact
+- `LineGeometryBuilder.build` repeated-line cell cache impact
+- `TerminalBuffer::Frame.write` ASCII fast-path impact
+- `LineContentComposer.compose` repeated-line cache impact
+- `ManifestShaFinder.sha` large-manifest lookup impact
+- `JsonCacheStore.manifest_rows` repeated-read cache impact

data/Rakefile

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 require 'bundler/gem_tasks'
+require 'json'
+require 'English'
+require 'fileutils'
+require 'shellwords'
 require 'rspec/core/rake_task'
 require 'rubocop/rake_task'
 
@@ -13,9 +17,84 @@ task quality: %i[spec rubocop]
 task default: :quality
 
 namespace :test do
+  module RSpecLane
+    module_function
+
+    RESULT_DIR = File.expand_path('tmp/rspec-results', __dir__)
+
+    def run!(name:, args:, env: {})
+      FileUtils.mkdir_p(RESULT_DIR)
+      output_path = File.join(RESULT_DIR, "#{name}.json")
+      command = ['bundle', 'exec', 'rspec', *args, '--format', 'json', '--out', output_path]
+
+      puts "==> #{name}: #{Shellwords.join(command)}"
+      success = system(env, *command)
+      pending = pending_count(output_path)
+
+      raise "Pending examples detected in #{name}: #{pending}" if pending.positive?
+      raise "RSpec failed in #{name} (exit #{$CHILD_STATUS.exitstatus})" unless success
+    end
+
+    def pending_count(path)
+      return 0 unless File.exist?(path)
+
+      payload = JSON.parse(File.read(path))
+      payload.dig('summary', 'pending_count').to_i
+    rescue JSON::ParserError => e
+      raise "Unable to parse RSpec JSON report at #{path}: #{e.message}"
+    end
+  end
+
+  desc 'Run architecture and wiring guardrail specs only'
+  task :guardrails do
+    FileUtils.mkdir_p(RSpecLane::RESULT_DIR)
+    fallback_report_path = File.join(RSpecLane::RESULT_DIR, 'fallback-report.json')
+    fallback_command = ['ruby', File.expand_path('script/architecture/fallback_report.rb', __dir__)]
+    puts "==> fallback-report: #{Shellwords.join(fallback_command)}"
+    fallback_payload = IO.popen(fallback_command, &:read)
+    File.write(fallback_report_path, fallback_payload)
+    raise 'Fallback report detected guardrail offenders' unless $CHILD_STATUS.success?
+
+    guardrail_targets = [
+      'spec/core/architecture',
+      'spec/adapters/input/command_bus_only_bindings_spec.rb',
+      'spec/adapters/input/command_binding_completeness_spec.rb',
+      'spec/bootstrap/dependencies/bundle_guardrails_spec.rb',
+    ]
+
+    RSpecLane.run!(
+      name: 'guardrails',
+      args: [*guardrail_targets, '--seed', '10101']
+    )
+  end
+
+  desc 'Run required non-fixture specs across fixed deterministic seeds'
+  task :required do
+    %w[10101 20202 30303].each do |seed|
+      RSpecLane.run!(
+        name: "required-seed-#{seed}",
+        args: ['--tag', '~requires_book_fixtures', '--seed', seed]
+      )
+    end
+  end
+
+  desc 'Run fixture-dependent specs only'
+  task :fixtures do
+    env = {
+      'SHOKO_BOOK_FIXTURES' => '1',
+    }
+    env['SHOKO_FIXTURES_DIR'] = ENV['SHOKO_FIXTURES_DIR'] if ENV.key?('SHOKO_FIXTURES_DIR')
+
+    RSpecLane.run!(
+      name: 'fixtures',
+      env: env,
+      args: ['--tag', 'requires_book_fixtures', '--seed', '30303']
+    )
+  end
+
   desc 'Run tests with coverage'
   task :coverage do
-    ENV['COVERAGE'] = 'true'
+    ENV['COVERAGE'] = '1'
     Rake::Task['spec'].invoke
   end
 end

data/Shoko.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'lib/shoko/shared/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'shoko'
+  spec.version = Shoko::VERSION
+  spec.authors = ['Shoko']
+  spec.email = ['ruby.computer770@passinbox.com']
+
+  spec.summary = 'Terminal EBook Reader'
+  spec.description = 'Terminal EBook Reader'
+  spec.homepage = 'https://sr.ht/~shayan/Shoko/'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 4.0.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+
+  # Specify which files should be added to the gem
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.end_with?('.gem') ||
+        (f == __FILE__) ||
+        f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|circleci)|appveyor)})
+    end.select { |f| File.file?(f) }
+  end
+  spec.bindir = 'bin'
+  spec.executables = %w[shoko start]
+  spec.require_paths = ['lib']
+
+  # Development dependencies are managed in the Gemfile
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/bin/shoko

@@ -6,14 +6,20 @@ lib_dir = File.join(app_root, 'lib')
 $LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
 
 begin
-  gemspec = Dir[File.join(app_root, '*.gemspec')].first
-  if gemspec && File.exist?(File.join(app_root, 'Gemfile'))
-    require 'bundler/setup'
-  end
+  # Only activate Bundler when explicitly running under it (e.g. bundle exec).
+  require 'bundler/setup' if ENV['BUNDLE_GEMFILE'] || ENV['BUNDLE_BIN_PATH']
 rescue LoadError
   # Running without Bundler (e.g., installed gem).
 end
 
 require 'shoko'
 
-Shoko::CLI.run
+Shoko::Adapters::Input::CLI.run(
+  ARGV,
+  app_factory: lambda do |epub_path:, log_config:|
+    Shoko::Bootstrap::ContainerFactory.build_unified_application(epub_path: epub_path, log_config: log_config)
+  end,
+  folder_import_factory: lambda do |log_config:|
+    Shoko::Bootstrap::ContainerFactory.build_cli_folder_import_context(log_config: log_config)
+  end
+)

data/bin/start

@@ -6,14 +6,20 @@ lib_dir = File.join(app_root, 'lib')
 $LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
 
 begin
-  gemspec = Dir[File.join(app_root, '*.gemspec')].first
-  if gemspec && File.exist?(File.join(app_root, 'Gemfile'))
-    require 'bundler/setup'
-  end
+  # Only activate Bundler when explicitly running under it (e.g. bundle exec).
+  require 'bundler/setup' if ENV['BUNDLE_GEMFILE'] || ENV['BUNDLE_BIN_PATH']
 rescue LoadError
   # Running without Bundler (e.g., installed gem).
 end
 
 require 'shoko'
 
-Shoko::CLI.run
+Shoko::Adapters::Input::CLI.run(
+  ARGV,
+  app_factory: lambda do |epub_path:, log_config:|
+    Shoko::Bootstrap::ContainerFactory.build_unified_application(epub_path: epub_path, log_config: log_config)
+  end,
+  folder_import_factory: lambda do |log_config:|
+    Shoko::Bootstrap::ContainerFactory.build_cli_folder_import_context(log_config: log_config)
+  end
+)

data/docs/architecture/hexagonal-adherence-checklist.md

@@ -0,0 +1,173 @@
+# Hexagonal Architecture Adherence Checklist (Zero-Fallback Cutover)
+
+Date: 2026-03-03  
+Scope: `lib/shoko/**` runtime + architecture guardrails/spec gates
+
+## Completed
+
+- [x] Removed optional DI resolution usage:
+  - zero `resolve_optional(` occurrences in `lib/shoko`.
+  - `DependencyContainer` exposes mandatory `resolve` only.
+- [x] Removed two-phase reader runtime wiring from public API:
+  - no `defer_runtime_setup`.
+  - no `attach_runtime_components!`.
+  - reader runtime graph is single-phase via constructor-time runtime factory.
+- [x] Completed inbound boundary ownership migration:
+  - adapters no longer include inbound intent handler ports.
+  - adapter-owned intent handler classes removed.
+  - application intent handlers added under `application/use_cases/intents`.
+- [x] Removed reflection-style probing/dispatch globally in runtime code:
+  - zero `respond_to?(` occurrences.
+  - zero `public_send` occurrences.
+  - zero dynamic `send(` occurrences.
+- [x] Removed collaborator-probing rescues:
+  - zero `rescue NoMethodError` collaborator probing occurrences.
+- [x] Removed known swallow/fallback runtime behaviors in strict paths:
+  - reader quit/save progress now fails fast.
+  - event bus subscriber failures are logged then re-raised.
+  - render state writer failures are logged then re-raised.
+  - document path resolver no longer masks resolver failures.
+  - kitty image line renderer no longer suppresses renderer exceptions.
+- [x] Removed known mechanical migration violations:
+  - bare `rescue =>` patterns removed (runtime code).
+  - inline `... rescue ...` expressions removed from runtime code.
+- [x] Boundary translation hardened:
+  - document load failures are translated to `Shoko::BookParseError`.
+  - dictionary catalog boundary uses typed `CatalogError < Shoko::Error`.
+  - cache import boundary propagates typed malformed-book failures (`BookParseError` / `MalformedBookInputError`) with no adapter shim fallback.
+- [x] Completed inbound handler decoupling from adapter controllers:
+  - application intent handlers now depend on typed executors (`ReaderIntentExecutor` / `MenuIntentExecutor`).
+  - adapter controller dispatch moved to adapter bridges.
+  - no `@reader_controller.` / `@menu_controller.` loopback remains in app intent handlers.
+- [x] Replaced bootstrap session contexts with launch-state ports/adapters:
+  - added `Core::Ports::Outbound::ReaderLaunchState` and `MenuLaunchState`.
+  - runtime adapters added in `adapters/runtime/session_state`.
+  - `ReaderSessionContext` / `MenuSessionContext` removed from bootstrap.
+  - application workflows and unified app now use launch-state ports.
+- [x] Enforced symbol-only input command execution contract:
+  - `Adapters::Input::Commands.execute` now rejects non-symbol commands.
+  - legacy proc/object/array execution paths removed.
+- [x] Optional dependency hard-error path introduced for sqlite execution:
+  - added `Shared::OptionalDependency.require_gem!`.
+  - added `DependencyUnavailableError` and used it in sqlite runtime load path.
+  - dictionary repository now remains wired in auto mode; missing sqlite fails explicitly on invocation.
+- [x] Fixed reader relaunch crash after closing/opening another book:
+  - reader launch state now clears background worker on reader exit (`RuntimeExecution#run_reader` ensure block), preventing reuse of stopped workers.
+- [x] Added canonical zero-fallback architecture guardrails:
+  - `spec/core/architecture/no_rescue_literal_default_spec.rb`
+  - `spec/core/architecture/no_overlapping_rescue_chains_spec.rb`
+  - `spec/core/architecture/no_stale_optional_resolution_spec.rb`
+  - `spec/core/architecture/no_standard_error_rescue_spec.rb`
+- [x] Removed duplicate/overlapping rescue chains that created unreachable branches.
+  - importer translation chains fixed (`fb2`, `kindle`, `pdf`, `rtf`).
+  - cache/string translation chain fixed (`lazy_file_string`).
+  - CLI contract coercion rescue overlaps fixed.
+  - bootstrap background worker fallback contract rescue overlap fixed.
+- [x] Removed stale optional-resolution scaffolding in reader composition.
+  - `ReaderBuilder#resolve_many` now has a single deterministic resolve path.
+- [x] Eliminated explicit `rescue StandardError` usage in `lib/shoko/**`.
+  - fail-fast boundaries now use explicit/translated rescue flows without `rescue StandardError`.
+- [x] Completed hard-cutover removal of legacy callable factories.
+  - removed DI keys/usages of `:document_service_factory` and `:background_worker_factory`.
+  - replaced with typed outbound ports `DocumentLoader` and `BackgroundWorkerBuilder`.
+- [x] Added typed progress boundary and removed adapter-to-adapter coupling in the progress path.
+  - new port `Core::Ports::Outbound::ProgressRepository`.
+  - new core value `Core::Models::ReadingProgress`.
+  - input adapter progress actions now consume typed core progress data only.
+- [x] Removed Proc-type migration fallbacks from runtime paths.
+  - zero `is_a?(Proc)` checks remain in `lib/shoko`.
+- [x] Removed implicit `NullRuntimeConfig` fallback expressions from runtime code.
+  - runtime config is now explicit at composition boundaries and test builders.
+- [x] Removed `rescue Exception` and bare string raises from `lib/shoko`.
+  - `rescue Exception`: `0`
+  - `raise '...'` / `raise "..."`: `0`
+- [x] Added permanent guardrails for zero-fallback constraints.
+  - `spec/core/architecture/no_rescue_exception_spec.rb`
+  - `spec/core/architecture/no_bare_string_raise_spec.rb`
+  - `spec/core/architecture/no_implicit_null_runtime_config_spec.rb`
+  - `spec/core/architecture/no_legacy_factory_keys_spec.rb`
+  - `spec/core/architecture/no_proc_type_fallbacks_spec.rb`
+- [x] Fixed post-cutover runtime regressions in browse/menu flow.
+  - directory scanner recursion now works (books populate in Browse).
+  - scanner roots narrowed to explicit book directories by default, with opt-in overrides via `SHOKO_BOOK_SCAN_DIRS`.
+  - metadata extraction wiring includes required `path_ops` / `file_probe`.
+  - terminal and menu styling normalize binary-encoded text safely for UTF-8 rendering.
+  - annotation editor session/controller event handling now enforces hash payloads; non-event return values (e.g. cursor timestamp floats) are ignored safely.
+- [x] Completed fatal external-input hard-break semantics across runtime boundaries.
+  - added `FatalExternalInputError` hierarchy with typed subclasses (`MalformedBookInputError`, `MalformedMetadataInputError`, `MalformedDictionaryInputError`).
+  - top boundaries now terminate with exit code `2` on fatal external input (`CLI`, menu lifecycle, reader lifecycle).
+  - fatal logs use stable event IDs (`fatal.external_input.book|metadata|dictionary`).
+- [x] Removed rescue-fallback defaults and hardened guardrails to enforce zero fallback.
+  - AST-based analyzer now detects literal defaults (`[]`, `{}`, `''`, `""`, booleans, symbols, numeric literals) and variable passthrough.
+  - added guardrails:
+    - `no_rescue_numeric_default_spec.rb`
+    - `no_swallowing_rescue_spec.rb`
+    - `no_noop_reraise_rescue_spec.rb`
+    - `no_mixed_symbol_string_key_reads_in_application_spec.rb`
+    - `no_cross_adapter_runtime_coupling_spec.rb`
+  - added deterministic report: `script/architecture/fallback_report.rb` (wired into `test:guardrails`).
+- [x] Completed typed boundary migration for key menu/runtime flows.
+  - introduced typed models used across workflow boundaries:
+    - `MenuBook`
+    - `AnnotationSelection`
+    - `PendingJumpPayload`
+    - `DictionaryCatalogEntry`
+  - removed mixed symbol/string dual-key normalization from `application/**` (`x[:k] || x['k']`).
+- [x] Removed cross-adapter runtime coupling in flagged paths.
+  - `DocumentLoaderAdapter` now depends on outbound `BookCachePipelineFactory` port.
+  - output terminal runtime config no longer depends on runtime-adapter null type directly.
+- [x] Hard-deleted legacy command/fallback APIs.
+  - removed unused bookmark command factory methods (`remove_bookmark`, `toggle_bookmark`, `jump_to_bookmark`).
+  - removed cache-import compatibility wrapper error type (`CacheImportAdapter::ImportError`).
+
+## Open Items
+
+- [ ] Persist benchmark baselines and enforce CI threshold checks.
+- [ ] Fixture lane is blocked locally by missing required books (see verification snapshot).
+- [ ] Extend optional dependency hard-error semantics to remaining optional capability execution paths (not only sqlite).
+
+## Verification Checklist
+
+- [x] `bundle exec rspec spec/core/architecture spec/bootstrap/dependencies`
+- [x] `bundle exec rake test:guardrails`
+- [x] `bundle exec rake test:required`
+- [x] `bundle exec rspec` (fixtures excluded by default tag filter)
+- [ ] `bundle exec rake test:fixtures` (blocked locally)
+
+## Verification Snapshot
+
+- `bundle exec rspec spec/core/architecture spec/bootstrap/dependencies`:
+  - 101 examples, 0 failures.
+- `bundle exec rake test:guardrails`:
+  - pass (`fallback_report` summary all zero).
+- `bundle exec rake test:required`:
+  - pass for seeds `10101`, `20202`, `30303` (973 examples/seed, 0 failures).
+- `bundle exec rspec`:
+  - 973 examples, 0 failures (with `requires_book_fixtures` excluded by default).
+- `bundle exec rake test:fixtures`:
+  - blocked by missing files:
+    - `Persuasion (Jane Austen).mobi`
+    - `Pride Prejudice (Jane Austen).azw`
+    - `Emma (Jane Austen).azw3`
+    - `Pride And Prejudice (Austen Jane).rtf`
+- Artifact sweeps (`lib/shoko`):
+  - `resolve_optional(`: `0`
+  - `rescue StandardError`: `0`
+  - `rescue Exception`: `0`
+  - bare `rescue =>`: `0`
+  - bare string raise (`raise '...'` / `raise "..."`): `0`
+  - duplicate `rescue ArgumentError, ArgumentError`: `0`
+  - duplicate/overlapping same-class rescue chains with unreachable fallback branches: `0`
+  - stale optional resolution ternary (`optional ? resolve : resolve`): `0`
+  - inline `... rescue ...` expressions: `0`
+  - `rescue NoMethodError` probing: `0`
+  - `respond_to?` / `public_send` / dynamic `send(`: `0`
+  - `fallback_report` zero-fallback summary:
+    - `fallback_literal_defaults`: `0`
+    - `numeric_rescue_defaults`: `0`
+    - `no_op_reraise_rescues`: `0`
+    - `fatal_input_swallow_rescues`: `0`
+    - `mixed_key_reads_application`: `0`
+  - legacy factory keys/usages (`document_service_factory|background_worker_factory`): `0`
+  - proc-type fallbacks (`is_a?(Proc)`): `0`
+  - implicit null runtime fallback expression (`|| ...NullRuntimeConfig.instance`): `0`

data/lib/shoko/adapters/base_adapter.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters
+    # Base class for adapters in the hexagonal architecture.
+    # Adapters connect ports to external infrastructure (UI, databases, etc.)
+    # and should NOT extend Core's BaseService.
+    #
+    # This class provides a simple dependency injection pattern via constructor kwargs
+    # without the `resolve()` semantics of BaseService.
+    class BaseAdapter
+      # @param logger [Object, nil] Optional logger for debugging
+      def initialize(logger: nil)
+        @logger = logger
+      end
+
+      protected
+
+      attr_reader :logger
+
+      def log_debug(message, **context)
+        logger&.debug(message, **context)
+      end
+
+      def log_error(message, **context)
+        logger&.error(message, **context)
+      end
+    end
+  end
+end