woods 2.0.1 → 2.1.0

data/docs/EXTRACTOR_REFERENCE.md

@@ -32,23 +32,69 @@ Extractors discover code one of two ways:
 
 Some extractors combine both (e.g., `JobExtractor` scans directories first, then supplements with `ApplicationJob.descendants`).
 
-Discovery is not exhaustive. A standalone module under `app/models` that is
-called through singleton methods is not discovered by the model/PORO paths;
-conventional concerns and app modules included by live models have separate
-concern discovery. This gap is tracked in [#552](https://github.com/lost-in-the/woods/issues/552).
-Separately, dependency scanning does not capture every method-body constant
-reference ([#475](https://github.com/lost-in-the/woods/issues/475)). A missing unit
-or edge is not proof of unused code; cross-check the application source.
+Discovery is not exhaustive. Woods 2.0.0 does not discover callable standalone
+modules under `app/models` through its model/PORO paths. Woods 2.1
+[standalone-module support](#poroextractor) addresses that case; conventional
+concerns and app modules included by live models retain concern ownership.
+Dependency scanning also remains partial, including with the source-reference
+pass below. A missing unit or edge is not proof of unused code; cross-check the
+application source.
+
+### Constant source references
+
+**Included in Woods 2.1.** For Git/path installations,
+record the loaded gem path and exact revision; the development version alone
+does not establish that this change is installed.
+
+After discovery and deduplication, extraction adds `code_reference` relationships
+from models, controllers, services, POROs, library units and concerns to verified,
+indexed class/module targets. It parses original Ruby source and attributes reads
+to their declaring owner. Ordinary method bodies, singleton methods and callback
+blocks participate. Comments, plain strings and declaration names do not establish
+references. Rails relationships derived through runtime reflection stay intact.
+
+Resolution respects qualified names and supported lexical/runtime context.
+A pending library autoload can supply a target only when its exact registered
+constant and absolute file path match the captured library declaration. Woods
+does not execute the autoload. Pending namespaces, unverified owner scopes,
+mismatched registration paths and non-library autoload targets remain unresolved.
+Dynamic constant lookup, uncertain aliases, ambiguous typed identities and
+unsupported scopes remain unresolved. In particular, references inside
+`class << self` are recorded as candidates but currently skipped during resolution;
+ordinary `def self.method` bodies are supported. A source reference does not prove
+execution, and an absent edge does not prove there are no callers. The internal cache retains parsed candidates, their scope, and collector skip
+reasons; it does not establish complete reference coverage.
+
+Forward edges and reverse relationships publish together. Incremental extraction
+and targeted refresh reconsider cached references when targets appear, disappear
+or change resolution, including references in unchanged callers. Larger recorded
+dependency sets can increase the incremental blast radius; no separate limit is
+applied to these edges. See [source-reference baseline and upgrades](INCREMENTAL_EXTRACTION.md#source-reference-baseline-and-upgrades).
 
 ### Identifier naming (source-derived units)
 
 File-based extractors derive an identifier in three steps, first match wins:
 
-1. **Zeitwerk-governed naming.** For a file under a managed autoload path, the expected constant path is computed — from `Rails.autoloaders.main` when a Rails autoloader is up, from the same path-to-constant convention offline otherwise — and the source must declare exactly that constant: `app/services/domain/container/parser.rb` is expected to define `Domain::Container::Parser`. This is what lets a file whose namespaces are written as *classes* (`module Domain; class Container; class Parser`) name the file's own constant instead of the wrapper `Domain::Container`, which every sibling under the same wrapper would otherwise collide with.
+1. **Zeitwerk-governed naming.** For a file under a managed autoload path, the expected constant path comes from its owning Rails loader (`main` or `once`), including that loader's inflections, root namespace, collapsed directories and ignored paths. Without loader information, the offline path convention applies. The source must declare exactly the expected constant: `app/services/domain/container/parser.rb` is expected to define `Domain::Container::Parser`. This is what lets a file whose namespaces are written as *classes* (`module Domain; class Container; class Parser`) name the file's own constant instead of the wrapper `Domain::Container`, which every sibling under the same wrapper would otherwise collide with.
 2. **Position-aware nesting scan** (`SourceNesting`, the supporting utility above). The first `class` declaration qualified by the namespaces actually open at that position. Compact declarations keep their segments; a helper module nested inside the class and sibling modules that closed earlier do not contribute.
 3. **Path convention.** Camelize the path under `app/<kind>/` (details vary per extractor).
 
-Unmanaged paths (`lib/`, configured non-autoload roots) and sources that declare nothing matching the expected constant skip step 1 entirely: the source scan and path convention decide, exactly as before the governed lookup existed.
+Unmanaged paths (`lib/` unless configured for autoloading, and configured non-autoload roots) and sources that declare nothing matching the expected constant skip step 1 entirely: the source scan and path convention decide. A namespace file containing only `Acme::VERSION` does not acquire an invented `Acme::Version` declaration.
+
+An inline primary module with a body, such as `module Helpers; def self.call; end; end`, keeps its declared name even when an unmanaged directory suggests another namespace. Namespace-only wrappers containing a single nonempty module retain the nested identity; direct behavior, empty inner modules, and `ClassMethods`/`InstanceMethods` plumbing stop that descent. Empty completed modules before the primary declaration remain namespace preludes. This correction is included in Woods 2.1; run a full extraction after upgrading to replace affected path-derived identities and their source-reference edges.
+
+One-line class declarations retain the same nesting as their multiline forms:
+`module Acme; class Error < StandardError; end; end` names `Acme::Error`,
+separately from the `Acme` namespace unit. Complete-source parsing keeps
+declaration-like text inside strings and heredocs out of identifier selection.
+Conditional declarations remain source candidates; this scan does not establish
+which branch ran. Method and singleton-class bodies do not supply ordinary
+owners. Invalid source keeps the tolerant class scan, while module selection
+requires valid syntax. These corrections are also included in Woods 2.1;
+re-extract affected indexes in full to replace wrapper identities and restore
+their source-reference edges.
+
+Once-loader ownership (#579) is included in Woods 2.1; verify the loaded revision as well as the gem version. It covers declared constants under `config.autoload_lib_once` and other once-managed roots. Direct ownership across both loaders takes precedence over copied-application inference; ambiguous roots and a loader's explicit non-claim remain unmanaged. After upgrading an affected index, run one full extraction before resuming incremental maintenance to replace stale wrapper identifiers. This does not aggregate multiple unmanaged source files reopening the same namespace.
 
 ### Eager loading
 
@@ -234,6 +280,7 @@ class PageView < AnalyticsRecord; end   # metadata[:database] => "analytics"
 **Key details:**
 - Scans: `app/jobs`, `app/workers`, `app/sidekiq`
 - Extracts queue name, retry configuration, concurrency options, perform method arguments, and callbacks
+- File-discovered jobs read queue metadata from source. Runtime `queue_name` supplements only class-discovered jobs, such as nested jobs outside the job directories; a file-discovered `queue_as Settings::QUEUE` can therefore retain a `null` queue even after refresh.
 - `perform_params` uses the same syntax-aware signature parsing as service initializers and preserves its `name`, `splat` (`single`/`double`/null), and `has_default` fields. Keyword defaults do not invent additional argument names.
 - Records what triggers this job (reverse lookup via dependency graph after extraction)
 - Supports both ActiveJob and Sidekiq native workers
@@ -260,7 +307,7 @@ class PageView < AnalyticsRecord; end   # metadata[:database] => "analytics"
 **What it captures:** ActionMailer classes with their mailer actions, defaults, template paths, callbacks, and helper usage.
 
 **Key details:**
-- Discovers `ApplicationMailer.descendants` when that class exists, otherwise `ActionMailer::Base.descendants`; an app without ActionMailer contributes no mailer units.
+- **Included in Woods 2.1:** discovers all app-owned `ActionMailer::Base.descendants`, including parallel abstract bases and direct subclasses even when `ApplicationMailer` exists. An app without ActionMailer contributes no mailer units.
 - Discovery and direct extraction accept only mailers backed by an existing app-owned source file, excluding dependency mailers and fabricated convention paths.
 - Each mailer action corresponds to an email template, template paths are recorded in metadata
 - Extracts `default from:`, `layout`, and per-action subject patterns
@@ -326,6 +373,8 @@ class PageView < AnalyticsRecord; end   # metadata[:database] => "analytics"
 
 ### PhlexExtractor
 
+**Included in Woods 2.1:** discovery and direct extraction require an existing app-owned source file; dependency components are excluded.
+
 **What it captures:** Phlex component classes (`Phlex::HTML`, `Phlex::SVG` subclasses) from `app/components`. Extracts slots, initialize parameters, sub-component references, Stimulus controller names, and route helper usage.
 
 **Key details:**
@@ -336,10 +385,13 @@ class PageView < AnalyticsRecord; end   # metadata[:database] => "analytics"
 
 ### ViewComponentExtractor
 
+**Included in Woods 2.1:** discovery and direct extraction require an existing app-owned source file and runtime ancestry; dependency components are excluded.
+
 **What it captures:** ViewComponent classes from `app/components`. Extracts slots, template paths, preview class references, and collection rendering support.
 
 **Key details:**
 - Template path is inferred from the component file name (e.g., `ButtonComponent` → `button_component.html.erb`)
+- **Included in Woods 2.1:** `metadata.sidecar_template` uses an application-relative path, such as `app/components/button_component.html.erb`. Detection still checks the actual file under `Rails.root`; extracting from another checkout does not change this metadata. Re-extract existing component units to update their stored paths.
 - Preview class associations are extracted when `<ComponentName>Preview` is found in `spec/components/previews/` or `test/components/previews/`
 
 **Edge cases:**
@@ -389,7 +441,7 @@ class PageView < AnalyticsRecord; end   # metadata[:database] => "analytics"
 
 ### PoroExtractor
 
-**What it captures:** Plain Ruby objects in `app/models` that are not ActiveRecord (non-AR classes, excluding concerns).
+**What it captures:** Plain Ruby objects in `app/models` that are not ActiveRecord (non-AR classes, excluding concerns). Woods 2.1 writers also discover callable standalone modules as described below.
 
 **Key details:**
 - Scans `app/models` for files that don't define an `ActiveRecord::Base` descendant
@@ -397,6 +449,60 @@ class PageView < AnalyticsRecord; end   # metadata[:database] => "analytics"
 - Excludes concerns (those go to ConcernExtractor)
 - `parent_class` and the generated Parent annotation describe the selected unit declaration only. Nested or sibling classes cannot supply its parent. An implicit `Object` parent, a dynamic superclass expression, or unparseable source produces `nil`; explicit constant-path parents retain their source names.
 
+#### Assigned value classes
+
+**Included in Woods 2.1.** Direct assignments such as
+`Criteria = Struct.new(:value)` and `Page = Data.define(:items)` can own a PORO
+unit inside class or module namespace wrappers. Discovery uses the active
+loader's expected constant where available, then verifies the loaded class,
+core factory, ancestry and canonical assignment file. For example, a reopened
+`Products::Search` containing `Criteria = Struct.new(...)` in its child file
+produces `Products::Search::Criteria`, not another `Products::Search` unit.
+
+The same verified naming applies to [library files](#libextractor). Shadowed
+factories, aliases, arbitrary `Class.new` assignments and unloaded nested value
+classes are not promoted by this check. Existing top-level named-Struct lookup
+identities remain compatible, but an alias is not a verified reference target.
+A callable canonical module sharing the file retains its own PORO unit. Library
+extraction preserves its canonical primary module when it matches the file's
+identity or has its own methods defined there; namespace-only child-file wrappers
+do not displace the assigned child. An assigned class can be the target of a
+`code_reference` edge, but references inside its Struct/Data constructor block
+remain unsupported because the block does not establish ordinary lexical class
+nesting. Woods does not execute the constructor or its method bodies.
+
+Run a **full extraction** after upgrading the writer. It repairs older wrapper
+identities and rebuilds the source-reference cache in format 3; incremental
+extraction refuses format 1 even when source files are unchanged. Existing
+readers can continue serving the last published index until the full extraction
+succeeds. Genuine collisions between different files still refuse publication.
+
+**Standalone modules — included in Woods 2.1.** A named,
+loaded module whose canonical declaration and own methods are defined under
+`app/models` can produce a `poro` unit with `metadata.ruby_kind: "module"` and
+`parent_class: null`. This includes `def self.method`, `module_function`,
+`class << self` methods and plain instance-method mixins. Discovery uses runtime
+ownership and source locations without calling those methods.
+
+Namespace-only wrappers, aliases, unloaded constants, gem-owned modules and
+methods supplied only by another file do not establish standalone ownership.
+An app module included by a live model belongs to `ConcernExtractor`; a library
+module remains owned by `LibExtractor`. Separate callable modules sharing a
+source file retain their own identities. Ordinary class PORO identifiers stay unchanged.
+
+Incremental extraction and model/PORO/concern refreshes reconcile ownership when
+an includer changes even if the module's file does not. Incomplete eager loading
+cannot prove that a former concern became standalone or that an undiscovered
+module disappeared. Those units remain retained unless positive ownership
+evidence supersedes them; changed source for a retained unit refuses publication
+until a complete run can re-extract it.
+
+Module discovery and reference resolution are separate: a module with
+`class << self` methods can be indexed even though references inside that scope
+remain unresolved by the [constant-reference pass](#constant-source-references).
+Run a full extraction when upgrading to establish the new units and their
+reference cache; updating only the reader does not add them.
+
 ---
 
 ### SerializerExtractor
@@ -422,19 +528,35 @@ class PageView < AnalyticsRecord; end   # metadata[:database] => "analytics"
 
 **What it captures:** `SimpleDelegator` subclasses that wrap a model. Records the wrapped model class, all public methods, and the delegation chain.
 
+**Included in Woods 2.1:** after eager loading, discovery checks the
+selected class's actual delegator ancestry and source ownership. Application
+base classes and leading `::` therefore work without changing the unit identity;
+an unrelated or foreign same-named class cannot supply that proof. When the class
+is unavailable, the extractor retains its limited direct-declaration fallback
+without triggering autoloads. `delegation_type` reflects resolved SimpleDelegator
+ancestry; unknown delegation mechanisms remain `unknown`.
+
 ---
 
 ## API & authorization extractors
 
 ### GraphQLExtractor
 
-**What it captures:** graphql-ruby types, mutations, queries, and resolvers. Produces four distinct unit types from one extractor.
+**What it captures:** graphql-ruby schemas, types, mutations, queries, and resolvers. Produces four distinct unit types from one extractor.
+
+**Included in Woods 2.1:** install 2.1.0 or later for the discovery fixes below. For Git/path installs, verify the exact revision and loaded gem path; the declared development version alone does not establish availability.
 
 **Key details:**
-- Scans `app/graphql` with runtime introspection via `GraphQL::Schema.types` when available, falls back to file discovery
-- Produces unit types: `graphql_type`, `graphql_mutation`, `graphql_resolver`, `graphql_query`
+- Scans every current, named application `GraphQL::Schema` subclass and unions their runtime type inventories by canonical Ruby constant name. Distinct Ruby classes can share a schema-local GraphQL name. A type used as the query root of any schema has one `graphql_query` identity.
+- Produces unit types: `graphql_type`, `graphql_mutation`, `graphql_resolver`, `graphql_query`. Schema classes use `graphql_type` with `metadata.graphql_kind: "schema"`; their source includes configuration such as `max_complexity` for lookup and source search.
+- Scans governed declarations in `app/graphql`, including unattached resolvers. Loaded declarations qualify through GraphQL ancestry, so application superclass chains, leading `::`, and superclass whitespace do not affect discovery. Reflection reads schema/type metadata without executing field or resolver bodies.
+- File discovery also retains ordinary Ruby subclasses of the loaded `Resolvers::Base` class, including application inheritance chains. These helpers keep their historical `graphql_type` identity even when mutations call them with `new(...).call` rather than registering them as graphql-ruby resolvers. Woods verifies actual ancestry; placing an unrelated class in a `resolvers/` directory does not qualify it.
+- When graphql-ruby or a declaration is unavailable, file discovery retains its limited recognized-source-form fallback; it cannot establish arbitrary application superclass ancestry. Woods does not trigger pending declaration autoloads itself.
 - Extracts field metadata (types, descriptions, complexity, arguments), authorization patterns (Pundit, CanCan, `authorized?`), and dependencies on models/services
-- Since all GraphQL units come from one extractor, incremental re-extraction handles them via `extract_graphql_file`
+- Incremental extraction handles changed files and runtime inventory additions, and reclassifies an unchanged type when its query-root role changes. Runtime inventory absence alone does not delete units: unattached file-defined resolvers remain valid, and runtime-only removals still require a full extraction or `woods:refresh[graphql]` after the application reloads.
+- A failed schema inventory logs the schema name and stops full, incremental, or refresh publication; the prior generation remains active. Fix the introspection error and retry the complete extraction batch.
+- If application eager loading is incomplete, incremental extraction and refresh refuse a change to an existing GraphQL unit's kind rather than demoting a query root whose schema might not have loaded. Retry after a complete application boot.
+- Runtime source locations take precedence over convention-named files. Initializer-built `Class.new` schemas/types can be indexed, but this does not add method-body `code_reference` ownership for generated declarations; see [source-reference coverage](#constant-source-references).
 - `parent_class` and summary chunks describe the selected declaration's explicit constant-path superclass, preserving its written qualification. Nested or sibling declarations and literal text cannot supply a parent. Implicit Object, module interfaces, dynamic superclass expressions, unavailable source, and invalid source have no declared parent (`null` metadata; `unknown` in summaries). This is source declaration metadata, not resolved runtime ancestry.
 
 **Example output (abbreviated):**
@@ -463,14 +585,23 @@ class PageView < AnalyticsRecord; end   # metadata[:database] => "analytics"
 - Pairs policy units with their corresponding model (e.g., `UserPolicy` → `User`)
 - Extracts scope class and `resolve` method when present
 
+**Included in Woods 2.1:** a loaded policy's actual ApplicationPolicy
+ancestry, including namespaced and intermediate application bases, establishes
+Pundit inheritance. The selected constant must belong to the source being read;
+aliases and foreign same-named classes do not qualify. Without a loaded class,
+direct ApplicationPolicy declarations and the existing user/record conventions
+remain supported. Woods does not invoke pending autoloads to classify a policy.
+The generic PolicyExtractor retains its existing policy units and applies the
+same ancestry correction to `metadata.is_pundit`.
+
 ---
 
 ### PolicyExtractor
 
-**What it captures:** Domain policy classes (non-Pundit) with decision methods and eligibility rules. Covers plain Ruby objects used for authorization decisions.
+**What it captures:** Policy classes with decision methods and eligibility rules, including plain Ruby objects used for authorization decisions.
 
 **Key details:**
-- Scans `app/policies` for files not identified as Pundit policies
+- Scans `app/policies`; `metadata.is_pundit` identifies recognized Pundit-style classes
 - Extracts public predicate methods and their dependencies
 
 ---
@@ -525,7 +656,7 @@ class PageView < AnalyticsRecord; end   # metadata[:database] => "analytics"
 
 #### Package membership
 
-Every app-owned unit under a package root carries `metadata[:package]` with the package name (longest root wins; `.` when only a root package exists). Framework sources and units with no path never carry it. The graph node carries the same value as `package`. When a `package.yml` changes, an incremental run re-annotates every unit whose package changed in the same run, so `metadata[:package]` never lags behind the file that defines it.
+Every single-file app-owned unit under a package root carries `metadata[:package]` with the package name (longest root wins; `.` when only a root package exists). Framework sources and units with no path never carry it. The graph node carries the same value as `package`. When a `package.yml` changes, an incremental run re-annotates every unit whose package changed in the same run, so `metadata[:package]` never lags behind the file that defines it.
 
 ---
 
@@ -545,13 +676,22 @@ Every app-owned unit under a package root carries `metadata[:package]` with the
 **What it captures:** ActionCable channel classes with stream subscriptions, subscribed/unsubscribed hooks, broadcast patterns, and action methods.
 
 **Key details:**
-- Discovers via `ActionCable::Channel::Base.descendants`
+- Discovers via `ActionCable::Channel::Base.descendants`. **Included in Woods 2.1:** discovery and direct extraction exclude dependency-owned source files.
 - Records stream names, authentication checks in `subscribed`, and any `broadcast_to` calls
 
 ---
 
 ### ScheduledJobExtractor
 
+**Included in Woods 2.1:** unique schedule names retain `scheduled:<name>`.
+Names shared across scheduler formats become `scheduled:<format>:<name>`, with
+a deterministic suffix if that identifier is already a literal task name.
+`metadata.task_name` preserves the original name. Ambiguous names within one
+format refuse publication; the last generation stays usable. Run a full
+extraction to remove dependency-owned components/channels and reconcile these
+expanded mailer and schedule identities in an existing index.
+
+
 **What it captures:** Scheduled job definitions from cron-style config files. Supports multiple scheduling backends.
 
 **Key details:**
@@ -594,6 +734,29 @@ Every app-owned unit under a package root carries `metadata[:package]` with the
 - Risk indicators: data migrations (manual SQL or bulk updates), irreversible operations (`remove_column` without type), `execute` calls with raw SQL
 - Rails internal tables (`schema_migrations`, `active_storage_blobs`, etc.) are excluded from model dependency links
 
+**Included in Woods 2.1:** migration identity comes from the actual Ruby
+declaration, with the filename's conventional class name selecting among eligible
+declarations. Helper classes and closed sibling namespaces cannot rename a
+migration or contribute unrelated DDL metadata. Qualified declaration receivers
+use verified lexical namespace ownership, including an existing outer or root
+namespace; Woods does not prepend the syntactic nesting blindly. A namespace
+established earlier in the same source can supply structural evidence. Unknown
+receivers, pending autoloads, and unavailable lexical constant tables produce an
+explicit ownership diagnostic rather than an invented identity. Leading
+`::ActiveRecord::Migration` remains supported. A custom migration base requires
+already-loaded runtime ancestry or a same-file structural chain to
+ActiveRecord::Migration; unknown custom bases are not guessed. Historical files
+are never required or evaluated for discovery. Ambiguous declarations produce an
+explicit extraction error, and duplicate identities across files retain the
+normal collision guard. Run a full extraction after upgrading to replace any
+previously misidentified migration units.
+
+If a qualified receiver cannot be verified, define its namespace before the
+declaration in the same source, or make that namespace available through normal
+application boot. Use a leading `::` when the receiver intentionally belongs to
+the root namespace. Woods will not load a historical migration to discover its
+namespace.
+
 **Example output (abbreviated):**
 
 ```json
@@ -631,8 +794,9 @@ Every app-owned unit under a package root carries `metadata[:package]` with the
 **What it captures:** State machine DSL definitions using AASM, Statesman, or the `state_machines` gem.
 
 **Key details:**
-- Detects which library is active by checking `defined?` for each DSL constant
-- Extracts states, events, transitions, guard conditions, and callbacks
+- Detects literal DSL declarations in model source; it does not evaluate the DSL or run callbacks
+- Extracts states, events, transitions, guard conditions, and callbacks from supported source forms; it does not claim complete dynamic or inherited registry coverage
+- **Included in Woods 2.1:** directly declared `state_machines` calls in the selected model class support the default `state` attribute (`state_machine initial: :pending do`), explicit attributes, and parenthesized calls, including multiline arguments. The default produces `Model::state_machine_state`; existing named identifiers remain `Model::state_machine_<attribute>`. Each declaration uses its own block and literal initial state, keeping multiple machines separate. Nested/sibling classes, singleton scopes and deferred/receiver blocks cannot supply another model's machine. Dynamic attribute expressions are not guessed, and dynamic initial-state functions are not called.
 - Returns an array from the file method (like `ScheduledJobExtractor`), cannot be used in the incremental file-based dispatch map; incremental re-extraction re-runs it wholesale on any `.rb` change under the model directories it scans
 
 ---
@@ -645,6 +809,7 @@ Every app-owned unit under a package root carries `metadata[:package]` with the
 - Two-pass approach: first collects all `publish`/`instrument` calls, then `subscribe`/`on` calls, then merges them
 - No single-file extraction method, incremental re-extraction re-runs `EventExtractor` wholesale on any `.rb` change under `app/` (a publish or subscribe site can appear anywhere)
 - Useful for tracing event-driven flows: "what subscribes to order.created?"
+- **Included in Woods 2.1:** app-owned `metadata.publishers` and `metadata.subscribers` paths, and the same paths in generated source annotations, are relative to `Rails.root`. Their array order, counts and event identifiers stay unchanged. Explicitly scanned paths outside the application remain absolute. Re-extract event units after upgrading: removing the checkout prefix changes existing `source_hash` values once, then identical app sources produce the same annotations and hashes across checkout roots.
 
 ---
 
@@ -694,6 +859,39 @@ Every app-owned unit under a package root carries `metadata[:package]` with the
 - File-based scanning; no assumption about class hierarchy
 - `parent_class` and the generated Parent annotation describe the selected unit declaration only. Nested or sibling classes cannot supply its parent. An implicit `Object` parent, a dynamic superclass expression, or unparseable source produces `nil`; explicit constant-path parents retain their source names.
 
+**Included in Woods 2.1:** compatible reopened library classes/modules across
+files form one typed unit. Matching inferred names alone are insufficient:
+conflicting declaration kinds/parents, unresolved constructors and aliases still
+refuse ambiguous ownership. Extraction does not require or execute unmanaged
+files. The sorted first path remains the compatibility `file_path`; it is a
+primary display path, not a claim that every definition resides there.
+
+Aggregates add `metadata.source_contributors_version: 1`, `source_contributors`,
+and sorted `defined_in`. Each contributor records its own path, raw-file SHA256,
+physical line range and half-open byte range inside the published composite.
+Generated headers/separators lie outside those ranges. Per-file facts remain
+separate; sorted paths do not establish runtime override order. The unit's
+`source_hash` describes the composite. One-file units retain their prior shape.
+
+The graph maps every contributor to the typed owner. Any relevant library edit,
+deletion or dependency-triggered refresh reconciles the complete library family
+once per batch; direct file extraction also returns the aggregate. This costs
+more than re-reading only the primary file, and preserves full/incremental facts.
+A contributor read failure prevents publishing a partial aggregate. Supporting
+Woods 2.1 writers read library source explicitly as UTF-8 regardless of the
+process locale; invalid UTF-8 is logged with the physical source path and still
+prevents a partial aggregate.
+
+Git facts remain per contributor: Woods does not fabricate a summed aggregate
+commit count or churn rank. A unit-level package is emitted only when every
+contributor belongs to the same package. Retrieval package/path scopes require
+**all** contributors to match, avoiding disclosure of out-of-scope source.
+Run one full extraction after upgrading: source-reference cache format 3 must
+be rebuilt, and existing indexes do not yet contain contributor provenance.
+
+Loaded Struct/Data assignments use the [assigned value-class ownership rules](#assigned-value-classes)
+to avoid naming sibling files after their shared namespace wrapper.
+
 ---
 
 ### RailsSourceExtractor

data/docs/FAQ.md

@@ -143,7 +143,7 @@ bundle exec rake woods:incremental
 docker compose exec app bundle exec rake woods:incremental
 ```
 
-The default Git range is `HEAD~1`; CI variables, an explicit range, or
+The default Git range is `HEAD~1`; supported CI variables or
 `CHANGED_FILES` can select another batch. Incremental extraction also refreshes
 affected concern consumers and re-runs whole-app extractors when their trigger
 paths change. It can reduce work, but has no universal speedup: Rails boot, graph
@@ -449,7 +449,7 @@ Enable them in your initializer:
 config.enable_snapshots = true
 ```
 
-Snapshots prefer their own SQLite database (`woods.sqlite3` in the output directory), separate from your Rails app's database. Extraction falls back to JSON files when the `sqlite3` gem is unavailable; other SQLite open/migration failures are reported and do not capture a snapshot. `Woods::Db::Migrator` runs the internal SQLite migrations automatically during extraction and MCP boot; `bundle exec rails db:migrate` does not touch this store and no manual migration step is needed. The packaged MCP server discovers an existing `woods.sqlite3` automatically. When extraction used the JSON fallback, set `WOODS_SNAPSHOTS=true` on the server so it wires `list_snapshots`, `snapshot_diff`, `unit_history`, and `snapshot_detail`.
+Snapshots prefer their own SQLite database (`woods.sqlite3` in the output directory), separate from your Rails app's database. Extraction falls back to JSON files when the `sqlite3` gem is unavailable; other SQLite open/migration failures are reported and do not capture a snapshot. `Woods::Db::Migrator` runs the internal SQLite migrations automatically during extraction and MCP boot; `bundle exec rails db:migrate` does not touch this store and no manual migration step is needed. The packaged MCP server discovers an existing `woods.sqlite3` automatically. `WOODS_SNAPSHOTS=true` enables snapshot tools but still prefers SQLite; it does not force the JSON store or import its history. If SQLite became available after JSON capture, use an explicitly configured JSON reader for that history. See [snapshot store selection](MCP_SERVERS.md#conditional-index-capabilities).
 
 ---
 
@@ -457,7 +457,11 @@ Snapshots prefer their own SQLite database (`woods.sqlite3` in the output direct
 
 ### What does the session tracer do?
 
-The session tracer is middleware that records which Rails actions are invoked during a browser session, assembles the relevant extracted units, and makes that context available via the `session_trace` MCP tool. It is useful for giving an AI tool accurate context about what code path was active during a specific user interaction.
+The session tracer records which Rails actions run during a browser session.
+A custom/embedded Index Server configured with that store can expose the traces
+through `session_trace`. The packaged Index executable does not load Rails
+initializers, so enabling the application middleware alone does not add this tool.
+See [conditional capabilities](MCP_SERVERS.md#conditional-index-capabilities).
 
 Session tracing is disabled by default and requires an explicit `session_store`.
 Follow the [canonical configuration example](CONFIGURATION_REFERENCE.md#session-tracer-options)
@@ -469,28 +473,10 @@ for store construction and review trace retention and access controls before ena
 
 ### How do I keep the index in sync in CI?
 
-Use incremental extraction in your CI pipeline. Fetch enough git history for the incremental diff to work:
-
-```yaml
-# .github/workflows/index.yml
-jobs:
-  index:
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 2
-      - name: Update index
-        run: bundle exec rake woods:incremental
-        env:
-          GITHUB_BASE_REF: ${{ github.base_ref }}
-```
-
-For Docker-based CI:
-
-```yaml
-      - name: Update index
-        run: docker compose exec -T app bundle exec rake woods:incremental
-```
+Restore an index for the exact commit your incremental diff starts from;
+otherwise run full extraction. Fetch the actual pull-request base and its
+history before diffing. Follow the [incremental CI recipe](INCREMENTAL_EXTRACTION.md#github-actions-with-an-exact-baseline)
+for cache selection, cold starts, nested applications, and Docker.
 
 ---
 

data/docs/GETTING_STARTED.md

@@ -65,6 +65,12 @@ bin/rails woods:extract
 
 Woods boots and eager-loads the Rails application, runs its extractors, builds dependency edges, and publishes one complete generation under `tmp/woods/`. A reader stays on the previous complete generation until the new one is published.
 
+For verified source capture before Rails boots, use the installed
+`bundle exec woods-extract full` launcher; see [source freshness](SOURCE_FRESHNESS.md#establish-a-fresh-baseline)
+for custom roots and output paths. **Included in Woods 2.1:** the launcher
+prefers the application's executable `bin/rake`, falling back to
+`bundle exec rake` when it is absent or not executable.
+
 If Rails only boots with environment variables, provide the same variables here. Do not work around a boot failure inside Woods configuration. First confirm that the application can boot and eager-load with the same environment:
 
 ```bash
@@ -142,7 +148,7 @@ ollama pull nomic-embed-text
 bin/rails woods:embed
 ```
 
-For dense Ruby source, add `gem "tokenizers", "~> 0.5"` for exact WordPiece token counting. Without it, Woods falls back to character-based estimation, which can over-pack some Ollama chunks.
+Ollama input counts are estimates, not a universal exact tokenizer. Supporting builds after 2.0.0 split complete prefixed inputs and request `truncate: false`; installing a tokenizer gem alone does not select a model-matched tokenizer. See [input sizing and refusal](EMBEDDING_MODELS.md#why-num_ctx-isnt-enough).
 
 Reconnect the MCP server and check `woods_status`. For OpenAI, pgvector, Qdrant, model dimensions, and provider changes, read the [Retrieval guide](RETRIEVAL_GUIDE.md) and [Backend matrix](BACKEND_MATRIX.md).