woods 2.0.1 → 2.1.0

data/docs/INCREMENTAL_EXTRACTION.md

@@ -30,7 +30,10 @@ Three differences are tolerated, and nothing else:
 
 The unit-file write skip ignores only Woods' top-level `extracted_at` stamp.
 A nested metadata field with the same name is application data: changing it
-rewrites the unit in both compact and pretty JSON output.
+rewrites the unit in both compact and pretty JSON output. On supporting
+Woods 2.1 writers, an already registered unit whose complete serialized bytes
+match also stays out of the touched set, Git enrichment and dependents updates.
+Derived metadata or dependency differences still use normal registration.
 
 `graph_analysis.json` used to be a fourth row, tolerating list ordering. It no
 longer is: the analyzer is order-independent and the oracle compares the file
@@ -58,22 +61,35 @@ failure a CI chain cannot afford:
 
 | Situation | Behavior |
 |---|---|
-| `CHANGED_FILES` is set | Used verbatim (comma-separated paths); git is not consulted. |
+| `CHANGED_FILES` is set | Comma-separated application-relative or contained absolute paths; normalized before filtering. Git is not consulted. |
 | The git range resolves | Current behavior: extract the changed paths, or exit 0 with `No relevant files changed` when nothing relevant changed. |
+| A changed input requires a restart | On revisions containing #588, the fresh one-shot task selects full extraction before relevance filtering, including schema-only changes. |
 | The range fails **and** a `:running` watch daemon maintains the index | Stand down with a printed reason, exit 0 — the daemon's start-up catch-up covers whatever changed. |
 | The range fails otherwise | Actionable error naming the range, **exit 1**. |
 | There is no `git` binary at all | Same two rows as above: the failure reads `git unavailable: …` and takes the daemon-coverage decision, rather than dying with an `Errno::ENOENT` backtrace. |
 
-Changed paths are normalized lexically before dispatch: trailing root slashes,
-duplicate separators and `.`/`..` segments do not create separate changes or
-bypass matching. Missing files remain representable; symlinks are not resolved.
+Changed paths are normalized lexically before the task's relevance filter:
+trailing root slashes, duplicate separators and `.`/`..` segments do not create
+separate changes or bypass matching. Paths outside `Rails.root` are excluded.
+Missing files remain representable; symlinks are not resolved. The task-boundary
+normalization and nested-application Git paths are included in Woods 2.1;
+check the installed revision before relying on them.
+
+**Included in Woods 2.1:** incremental extraction and targeted refresh refuse
+legacy flat artifacts with a manifest and generations whose manifest records a
+writer major version below 2. Run a full `woods:extract` before resuming partial
+updates. Missing writer provenance in a generation remains compatible with early
+v2 betas. Reading old indexes and rebuilding them fully remain supported; see
+[the v1 upgrade procedure](UPGRADING_TO_2.md).
 
 The range comes from `CI_COMMIT_BEFORE_SHA..CI_COMMIT_SHA` (GitLab),
-`origin/$GITHUB_BASE_REF...HEAD` (GitHub Actions), or `HEAD~1` (default). An
-unresolvable range — a GitLab zero-SHA on a new branch, an unfetched base ref,
-a shallow clone with no `HEAD~1` — reads as "nothing changed" to git, which is
-why a failed range must not be mistaken for an empty one: the sync never ran,
-and CI drift would stay unbounded. A degraded daemon covers nothing, so it
+`origin/$GITHUB_BASE_REF...HEAD` (GitHub Actions), or `HEAD~1` (default).
+Whitespace-only CI variables are ignored; a nonempty GitLab before-SHA with
+no current SHA compares against `HEAD`. Nonempty invalid revisions still fail.
+An unresolvable range — a GitLab zero-SHA on a new branch, an unfetched base ref,
+a shallow clone with no `HEAD~1` — cannot establish which files changed.
+The task must not mistake that failed diff for an empty change set.
+A degraded daemon covers nothing, so it
 does not stand the run down. `WOODS_IGNORE_WATCH=1` removes daemon coverage
 too — with it set, a failed range exits 1. A slim image with no `git` binary
 resolves to the same decision rather than a raw `Errno::ENOENT`: the failure is
@@ -82,14 +98,18 @@ and an uncovered one still gets the remediation text.
 
 Recovery choices, in the order they are worth trying:
 
-1. Repair or provide the range: fetch the base ref (`fetch-depth: 2` or more),
-   or correct the CI environment variables that build it.
+1. Repair or provide the range: fetch the actual base ref and enough history
+   to find its merge base, or correct the CI environment variables that build
+   it. Depth two alone does not fetch a pull request's base branch.
 2. Set `CHANGED_FILES` explicitly from your CI platform, bypassing git range
    resolution entirely.
 3. Run a full `woods:extract` when the range cannot be repaired this run.
 
 The diff itself is rooted at the extracted application (`git -C Rails.root`),
-independently of the process working directory. An explicit `WOODS_GIT_DIR`
+independently of the process working directory. Paths are application-relative
+even when Rails lives below the repository root. Deletions and both sides of
+renames within the application remain in the change set; sibling applications
+are excluded. An explicit `WOODS_GIT_DIR`
 selects that Git directory's HEAD for both the diff and manifest provenance.
 For a linked worktree, use its worktree-specific directory within the complete
 shared layout; selecting the shared root instead reads the primary checkout's
@@ -103,6 +123,101 @@ including inlined code and callback analysis. Multiple runtime mixins sharing a
 file retain separate identities and refresh all their includers. Run a full extraction after upgrading
 to populate these previously missing source mappings.
 
+### GitHub Actions with an exact baseline
+
+The restored index must describe the first commit in the selected diff.
+A cache from an unrelated branch or older commit is not a valid baseline for
+`HEAD~1` or a pull request's merge base. The recipe below restores only the
+selected commit's exact cache key and runs full extraction on a cache miss.
+It fetches complete history and the actual pull-request base ref; see
+[checkout's history setting](https://github.com/actions/checkout#usage) and
+[cache restore's exact-hit output](https://github.com/actions/cache/blob/v4/restore/README.md#outputs).
+
+Adapt database setup, Ruby configuration, and the index path to the host app.
+This example runs from a Rails app at the repository root. For a nested app,
+set the run steps' working directory and adjust the cache path, hash paths,
+and cache namespace to identify that app. Include every extraction-affecting
+configuration input in the cache namespace; change it after a Woods upgrade
+that needs a full baseline. An unverified or incomplete prior index needs a
+full extraction even when a cache key matches.
+
+```yaml
+# .github/workflows/woods.yml
+name: Update Codebase Index
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  index:
+    runs-on: ubuntu-latest
+    env:
+      RAILS_ENV: test
+      WOODS_IGNORE_WATCH: "1"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - name: Select the baseline commit
+        id: base
+        env:
+          WOODS_BASE_REF: ${{ github.base_ref }}
+          WOODS_BEFORE_SHA: ${{ github.event.before }}
+        run: |
+          if [ -n "$WOODS_BASE_REF" ]; then
+            git fetch --no-tags origin "+refs/heads/$WOODS_BASE_REF:refs/remotes/origin/$WOODS_BASE_REF"
+            base="$(git merge-base "origin/$WOODS_BASE_REF" HEAD)"
+          elif [ -n "$WOODS_BEFORE_SHA" ] && git rev-parse --verify "$WOODS_BEFORE_SHA^{commit}" >/dev/null 2>&1; then
+            base="$WOODS_BEFORE_SHA"
+          else
+            base=""
+          fi
+          printf 'sha=%s\n' "$base" >> "$GITHUB_OUTPUT"
+      - name: Restore exactly that baseline
+        id: index-cache
+        if: steps.base.outputs.sha != ''
+        uses: actions/cache/restore@v4
+        with:
+          path: tmp/woods
+          key: woods-v2-app-${{ runner.os }}-${{ hashFiles('Gemfile.lock', 'config/initializers/woods.rb') }}-${{ steps.base.outputs.sha }}
+      - name: Prepare the application database
+        run: bin/rails db:prepare
+      - name: Update the index
+        env:
+          WOODS_EXACT_BASELINE: ${{ steps.index-cache.outputs.cache-hit }}
+          CI_COMMIT_BEFORE_SHA: ${{ steps.base.outputs.sha }}
+          CI_COMMIT_SHA: ${{ github.sha }}
+        run: |
+          if [ "$WOODS_EXACT_BASELINE" = true ]; then
+            bin/rails woods:incremental
+          else
+            bin/rails woods:extract
+          fi
+      - name: Validate the index
+        run: bin/rails woods:validate
+      - name: Save the validated current index
+        uses: actions/cache/save@v4
+        with:
+          path: tmp/woods
+          key: woods-v2-app-${{ runner.os }}-${{ hashFiles('Gemfile.lock', 'config/initializers/woods.rb') }}-${{ github.sha }}
+```
+
+There are deliberately no `restore-keys`: a partial match selects full
+extraction. A first push, an unavailable before-SHA, or an absent baseline
+cache also selects full extraction. A failed explicit PR-base fetch stops the
+job with its Git error. The validated publication is saved under the current
+checkout's SHA, never under the old baseline key.
+
+For Docker CI, run database preparation and Woods tasks through the application
+service, forward the selected CI variables into that container, and cache the
+host-visible mount of the same index. Fetching the base only on a host whose
+Git object store is absent from the container does not make that range usable
+inside the application.
+
 ## Handled source errors and retry
 
 Included in Woods `2.0.0`: when an incremental extraction or named refresh
@@ -133,6 +248,19 @@ step before it.
    path no longer produces are dropped. This is what indexes a file the index
    has never seen, and what removes definitions deleted from a surviving
    source file. Multi-file Rake tasks use wholesale reconciliation below.
+
+   **Included in Woods 2.1:** changed-path candidates are collected and checked
+   before registration or pruning. Moving an identity out of a surviving file
+   works in either changed-path order only when completed extraction proves
+   the old file no longer produces it and the new owner is unique. Failed or
+   unsupported extraction cannot release an owner. For runtime classes, a
+   complete eager load, an authoritative discovery inventory with one current
+   class, and that class's canonical source location can establish the move.
+   Jobs and serializers additionally require their complete file/runtime
+   inventory to rule out a source-only duplicate. GraphQL's mixed runtime/file
+   inventory does not grant this authority.
+   Incomplete eager loading cannot establish a surviving-file ownership move;
+   genuine simultaneous source owners still abort before publication.
 3. **Re-extract the rest of the blast radius**: units whose own file did not
    change but which depend on something that did.
 4. **Reconcile class-based types** against each extractor's
@@ -140,6 +268,16 @@ step before it.
    classes the graph still holds that the set no longer contains. Exact by
    construction: it is the same discovery code a full extraction uses, so
    there is no path-to-constant guessing.
+
+   **Included in Woods 2.1:** jobs and serializers reconcile their combined
+   file/runtime inventory whenever a Ruby source path changes. Resolved metadata
+   can depend on another file without a recorded graph edge, such as a nested,
+   class-discovered job's `queue_as Settings::QUEUE`. Runtime queue enrichment
+   applies only to class-discovered jobs; file-discovered jobs keep source-based
+   queue metadata. Non-Ruby batches refresh only hybrid families
+   already reached by the pre-change dependency graph. The application must have
+   loaded the changed runtime before extraction, through a fresh boot or reload.
+
 5. **Re-run whole-app extractors** whose trigger paths changed, replacing that
    unit type wholesale.
 6. **Prune vanished units**, so anything steps 2–5 resurrected against a
@@ -164,6 +302,14 @@ step before it.
    string literal, and an unrelated addition in the same batch do not.
    Idempotent when nothing was pruned.
 
+8. **Reconcile source references** on Woods 2.1 writers described in
+   [constant source references](EXTRACTOR_REFERENCE.md#constant-source-references).
+   Resolve cached candidates against the complete current typed unit registry,
+   update callers' forward relationships, and refresh targets' reverse
+   relationships. Unresolved candidates allow an unchanged caller to gain an edge
+   when its target becomes indexed. Parsing is reused only when the captured
+   source identity still matches.
+
 Git enrichment uses the same eligibility checks in full and incremental runs:
 existing app-owned files under `Rails.root`, excluding `vendor/`, `node_modules/`,
 and framework/gem source units. Each typed unit resolves its own file history,
@@ -317,12 +463,27 @@ discovery set.
 
 ### Runtime removals and bundle updates
 
-Jobs discovered through `ApplicationJob.descendants` supplement the job-file
-scan, but jobs are not part of `CLASS_BASED_DISCOVERY` removal reconciliation.
-If a dynamically defined or gem-owned job disappears without a tracked source
-path changing, its unit can survive subsequent incremental runs. A full
-extraction in a fresh Rails process removes it; an in-process full extraction
-can still see an old constant retained by that process (B-165).
+Hybrid runtime reconciliation (#588) is included in Woods 2.1; check the
+loaded writer revision. Jobs and serializers use the union of their directory
+scan and current runtime descendants. A Ruby-file change, or a blast radius
+containing a job or serializer, reruns both families wholesale. This costs a
+complete job and serializer scan for that batch, preserving the same file-pass
+precedence, nested identities, JSON and graph facts as full extraction. A
+serializer nested in a controller retains its own identity; the controller does
+not become a serializer unit. Runtime objects left behind by a reload cannot
+claim a name now owned by another constant.
+
+All members of those two families count as refreshed and participate in graph,
+source-reference and metadata maintenance, even when only one file changed.
+Unit-file writes retain the existing byte-equality check; this does not promise
+a single-file write cost or an unchanged manifest for such a batch.
+
+Discovery-based removal requires a complete eager load. Failed or reported-partial discovery
+refuses publication, preserving the previous generation; incomplete eager
+loading retains missing units. An empty change set does not discover arbitrary
+runtime-only additions or removals. Use `refresh(:jobs, :serializers)` after
+updating the runtime explicitly, or full extraction in a fresh process after a
+bundle change. An old constant still bound in that process remains observable.
 
 After adding, removing, or updating bundled gems, boot the updated bundle in a
 fresh process and run:
@@ -373,6 +534,13 @@ The family has three parts: `flows/flow_index.json` (entry point → relative
 document path), one document per controller action, and
 `metadata[:flow_paths]` on the controller units.
 
+On revisions containing #588 (included in Woods 2.1), switching the gate off
+withdraws the seeded `flows/` family and removes controller flow annotations on
+the next full, incremental or targeted-refresh publication. An incremental run
+with no changed files still publishes this withdrawal. The preceding generation
+is unchanged; any withdrawal failure prevents publication. `trace_flow` then
+uses its normal query-time assembly instead of an obsolete precomputed document.
+
 A full extraction computes all three in one pass. An incremental run computes
 them for its **delta**:
 
@@ -440,6 +608,11 @@ cascades to `ROUTE_CONSUMER_EXTRACTORS` for the reason given above. Like an
 incremental run, `refresh` rewrites the graph, `graph_analysis.json`, the
 affected type indexes and the manifest, so the result is durable.
 
+`refresh(:configurations)` derives `BehavioralProfile` from resolved
+`Rails.application.config`. Its nominal `config/application.rb` source path is
+not a separate configuration unit. Refresh assumes the caller already updated
+the runtime; it does not rerun Rails initialization or apply database migrations.
+
 ## What a change actually requires: reload, restart, or neither
 
 `Woods::ReloadPolicy` answers the question a resident process has to ask before
@@ -482,8 +655,31 @@ it, and belong to whoever implements the reload step:
 the batch demands, and `paths_requiring(:restart)` names the offending paths in
 the restart message a supervisor sees. See `docs/WATCH_DAEMON.md`.
 
+The one-shot `woods:incremental` task also uses the shared `InputRules` decision
+before relevance filtering on revisions containing #588. Run it in a fresh
+Rails process with migrations already applied: `db/schema.rb`,
+`db/structure.sql`, and other restart inputs select full extraction, including
+when mixed with ordinary model edits. A migration source file alone retains
+its existing file-extraction classification; Woods does not apply migrations.
+
+The direct `Extractor#extract_changed` API and optional embedded
+`pipeline_extract` incremental mode cannot establish a fresh boot. They refuse
+restart-sensitive batches before creating a payload and instruct the caller to
+run `woods:extract` in a fresh Rails process. With the MCP Tasks extension this
+is a failed task, and the prior generation stays active. Calling a full
+extraction on an already stale embedded runtime does not refresh that runtime.
+
 ## Running the differential harness
 
+The real ActiveJob/AMS and fresh schema-task probes have a separate optional
+bundle and run in their own processes (also in the Rails 7.2 CI row):
+
+```bash
+BUNDLE_GEMFILE=gemfiles/serializers.gemfile bundle install
+WOODS_RUN_BOOTED_APP=1 BUNDLE_GEMFILE=gemfiles/serializers.gemfile \
+  bin/rspec spec/integration/incremental_runtime_spec.rb
+```
+
 `spec/integration/incremental_equivalence_spec.rb` is the oracle. It boots the
 `spec/dummy` app against a tmpdir copy, applies randomized
 create/modify/delete/rename sequences, and compares the maintained index to a
@@ -579,6 +775,15 @@ edit does not establish that a day of commits is below the crossover.
   same type+identifier are not representable; full extraction fails closed
   with both source paths instead of publishing a glob-order tie-break (resolved
   B-063). Same-file re-derivation remains a legitimate deduplication case.
+  **Included in Woods 2.1:** incremental extraction and targeted refresh enforce
+  the same collision refusal (#561), preserving the prior published generation.
+  Distinct unit types in separate extractor directories remain independent.
+  A retained source can move when the old file is confirmed absent and the new
+  file exists; two conflicting sources produced within one run always refuse.
+  Complete wholesale replacement can relocate an owner, such as framework
+  source after a gem upgrade. Partial runtime discovery cannot grant that authority.
+  Correct the producer or declarations, then retry the complete failed batch.
+  A watcher retains failed paths and reports degraded status until corrected.
 - **Class-based units are never swept**: see [Deletion](#deletion) above for
   why (the `SchemaMigration`/`InternalMetadata` convention-path case).
   Deleting a class-based unit therefore requires either the caller naming the
@@ -598,3 +803,40 @@ edit does not establish that a day of commits is below the crossover.
   contract, and multi-worktree operation, all landed alongside this work
   (B-064, resolved). `docs/WATCH_DAEMON.md` covers them, including the parts
   that remain unmeasured.
+
+## Source-reference baseline and upgrades
+
+**Included in Woods 2.1.** Older indexes remain readable.
+Writers with the [source-reference expansion](EXTRACTOR_REFERENCE.md#constant-source-references)
+require one full `bin/rails woods:extract` before incremental extraction or
+targeted refresh can update an older index without its reference cache. Follow
+with `bin/rails woods:validate` using the application's normal task launcher.
+
+`source_references.json` is internal writer state in the published payload.
+Preserve it with the complete payload when copying an index. Missing/incompatible
+cache state or unverified retained source stops publication with a full-extraction
+diagnostic. Reconstruct it by running a full extraction; do not manufacture a
+cache or delete it to bypass the check. The preceding generation remains active.
+The watcher preserves failed batches but does not automatically repair this
+baseline: establish the full baseline before resuming incremental maintenance.
+
+This also tightens scoped refreshes: if a retained reference-bearing Ruby unit's
+source changed outside the selected batch, the writer refuses to combine its old
+runtime facts with references resolved from the new source. For example,
+`woods:refresh[events]` cannot adopt an edited service unit. The prior generation
+stays active and can report `drifted`; use a full extraction to establish a
+consistent baseline. Omitted non-reference inputs, such as a view changed before
+capture, retain the existing per-consumer freshness behavior.
+
+A source change during reference analysis or final verification also prevents
+publication. Correct source errors and retry the complete batch against a stable
+tree. Reference-only edge updates do not refresh a retained unit's runtime
+metadata, extraction timestamp or Git history.
+
+Whole-extractor failure reporting (#584) is included in Woods 2.1; verify the
+writer revision before relying on it. If a selected whole-app extractor cannot
+be initialized or raises before replacing any units, incremental extraction and
+targeted refresh fail without advancing the published generation, even when
+other extractors succeeded. Correct the logged cause and retry the complete
+changed-file batch or refresh selection. The existing refusal after a
+replacement has begun writing remains in place.

data/docs/INDEX_LAYOUT.md

@@ -63,10 +63,15 @@ gates below deliberately fail more strictly.
 
 ### Payload artifacts
 
+Read JSON artifacts as UTF-8 regardless of the reader process's locale. Unit
+identifiers, source code, paths, and metadata can contain non-ASCII characters.
+Reject invalid UTF-8 rather than replacing bytes in published source evidence.
+
 | Artifact | Presence and meaning |
 |---|---|
 | `manifest.json` | Required for a complete structural publication. Counts by extractor directory, totals, extraction timestamp and provenance. Optional fields vary by writer/version; see [writer provenance](PUBLISHED_INDEX.md#manifest-writer-provenance). |
 | `source_inputs.json` | Versioned source-input identities and per-consumer provenance for this exact generation; old indexes may omit it. See [source freshness](SOURCE_FRESHNESS.md). |
+| `source_references.json` | Internal, versioned candidate and edge-ownership cache for this generation. Included in Woods 2.1. Older indexes remain readable without it; supporting incremental writers may require a [full baseline rebuild](INCREMENTAL_EXTRACTION.md#source-reference-baseline-and-upgrades). Preserve it when copying payloads. Not a public query schema. |
 | `dependency_graph.json` | Required for a complete structural publication. Typed graph data; an empty graph is valid. |
 | `<type>/_index.json` and unit JSON | Present for extracted families. `_index.json` is an array of unit summaries; an empty array is valid. Disabled/unavailable families may be absent. Do not infer completeness from a fixed count of directories. |
 | `graph_analysis.json` | Derived graph analysis when produced. Treat absence as unavailable analysis, not an empty or corrupt unit index. |

data/docs/INTERNALS.md

@@ -388,6 +388,15 @@ All Console Server queries run inside a **rolled-back transaction** (`SafeContex
 
 Large units are split into semantic chunks before embedding. The `SemanticChunker` is type-aware, it doesn't split on arbitrary token counts.
 
+**Included in Woods 2.1:** class-like method chunks retain their full
+method name, including `self.`, `?`, `!`, setters and operators. For example,
+`Callable#method_call` and `Callable#method_self.call` contain the instance and
+class implementations separately, in source order. Plain instance-method chunk
+identities stay the same; formerly truncated class or punctuation-bearing names
+change to their distinct identities. Rebuild embeddings for affected units to
+replace old collapsed chunks. This remains a line-based chunker, rather than a
+complete Ruby parser.
+
 ### Model chunking
 
 Models are split into purpose-specific sections:

data/docs/MCP_HTTP_TRANSPORT.md

@@ -86,32 +86,37 @@ Clients must send `Authorization: Bearer $WOODS_MCP_HTTP_TOKEN` on every request
 
 ### Browser origins (DNS rebinding defense)
 
-**Unreleased diagnostic correction:** invalid origin encodings also refuse before
+**Included in Woods 2.1:** invalid origin encodings also refuse before
 binding HTTP. `woods-mcp-http` exits 2 with one bounded `ConfigurationError`
 message naming the invalid entry; re-enter that origin using an ASCII hostname
 (or its Punycode form). No allowlist keeps the existing defaults. Explicit entries
 are literal origins, not wildcard patterns.
-Retain the actual request Host through a reverse proxy; forwarded headers do not
-replace it. When authentication is configured, requests without Host still pass
-through bearer authentication.
 
-In the 2.0.1 maintenance patch, preflight and SDK dispatch share an immutable
-normalized policy. A configured list replaces the default browser origins;
-include loopback explicitly if needed. Cross-origin ports must match an entry,
-while omitted default HTTP(S) ports match their explicit 80/443 forms. A portless
-entry permits same-authority traffic rather than every cross-port browser origin.
-Console defaults remain HTTP loopback; Index HTTP defaults include HTTP and HTTPS
-loopback. When no list is set, these defaults are unchanged. Invalid entries fail
-at boot, naming the offending entry. Restart after changing the configuration.
-
-A second middleware, `Woods::MCP::OriginGuard`, rejects requests whose `Origin` header is outside an allow-list. Requests without an `Origin` header still pass through Host validation and configured bearer authentication.
+A second middleware, `Woods::MCP::OriginGuard`, rejects requests whose `Origin` header is outside an allow-list. Requests without an `Origin` header still validate `Host`; bearer authentication remains required when configured.
 
 | Scenario          | `WOODS_MCP_HTTP_ALLOWED_ORIGINS`      | Origins accepted                                                |
 |--------------------|-----------------------------------------|-------------------------------------------------------------------|
-| default            | unset                                    | HTTP(S) loopback, matching request authority; explicit entries for cross-port origins              |
+| default            | unset                                    | loopback HTTP(S) origins matching the request Host authority              |
 | explicit list      | `https://app.example.com`                | exactly `https://app.example.com`, loopback no longer allowed  |
 | multiple origins   | `https://a.example,https://b.example`    | each listed origin                                                |
 
+**Included in Woods 2.1:** preflight and SDK dispatch share one immutable policy.
+Explicit cross-origin entries match the complete origin; default HTTP(S) ports
+(`:80` and `:443`) are equivalent to their omitted form.
+A portless entry additionally permits same-authority requests on other ports;
+it does not grant arbitrary cross-port CORS. For example, a browser at
+`http://localhost:3000` calling an endpoint on port 9292 must list the browser's
+actual origin. A custom list replaces default browser-origin rules. Configure
+non-loopback endpoint authorities too, and retain the request's real Host through
+any reverse proxy. IPv6 origins use brackets, e.g. `http://[::1]:3000`.
+
+Both the preflight and SDK transport use this default-port equivalence. A genuinely
+absent Origin is allowed after Host validation; blank or malformed headers are
+rejected. Invalid configured origin URLs refuse once at boot with a bounded diagnostic
+naming the offending entry; this is stricter than 2.0.0 startup behavior.
+Restart after changing origins: the middleware and transport capture the same
+policy. SDK DNS-rebinding checks remain enabled.
+
 `OPTIONS` preflights are answered with the matching `Access-Control-Allow-*` headers; successful responses carry `Access-Control-Allow-Origin` and `Vary: Origin`. `Access-Control-Expose-Headers: Mcp-Session-Id` appears only in legacy session mode (`WOODS_MCP_HTTP_STATELESS=0`).
 
 ### Origin configuration compatibility

data/docs/MCP_SERVERS.md

@@ -147,7 +147,10 @@ than pinning a newer version solely to obtain guidance.
 
 ### Structural and semantic readiness
 
-`ready` describes the published structural index. A reachable embedding provider
+`ready` describes the published structural index, not corpus size or extraction
+coverage. An intentionally empty application can have a valid, ready zero-unit
+index; inspect `structure` counts and extraction diagnostics when zero is
+unexpected. A reachable embedding provider
 and bootstrap state `hydrated` do not establish that semantic stores contain
 data. Supporting readers also report `retriever.corpus`: locally known vector
 and metadata entry counts, counts by type, and whether those stores are empty,
@@ -209,6 +212,31 @@ error and continues serving the previous aligned generation; it never swaps in a
 partial or empty replacement. Grant write access for live reloads, or restart the MCP
 process after publishing a new embedded index.
 
+**Included in Woods 2.1:** the `:local` preset combines snapshot vectors with
+SQLite metadata, which cannot be refreshed together atomically in the running
+server. Its `reload` returns a degraded error and retains the previous aligned
+state even when the directory is writable. Restart `woods-mcp` after
+`woods:embed` to load the new vectors. See the [backend matrix](BACKEND_MATRIX.md#persistence-story).
+
+### Resource identity and damaged generation markers
+
+**Included in Woods 2.1 (#593):** unit resource identifiers may contain
+slashes, such as `views/posts/show.html.erb` or `GET /posts/:id`. Encode the
+whole identifier as one URI segment (`%2F` for `/`) in
+`codebase://unit/{identifier}`. Raw multi-segment paths, dot traversal segments,
+double encoding and backslashes remain invalid. Type resource names cannot
+contain slashes.
+
+A held-open server returns `corrupt_artifact` for a malformed published
+generation marker or an unavailable/outside-root payload pointer. Repeated
+calls retain that error rather than presenting the cached generation as current.
+An already pinned request can finish against its known generation. New requests
+resume after a valid marker is restored; a leftover flat root manifest is not
+substituted for a missing or invalid named payload. Run
+`woods:validate` and restore a known-good publication or complete a fresh
+extraction; do not point the marker at an arbitrary payload directory.
+Legacy flat indexes without a generation marker remain supported.
+
 ### Graph-analysis pages
 
 Included in Woods `2.0.0`: `graph_analysis` enforces its advertised default
@@ -238,6 +266,7 @@ generation. This contract is included in Woods `2.0.0`.
 | `exhausted` | `complete` | `false` | Exact count |
 | `result_limit` | `partial` | `true` | `null` (unknown) |
 | `scan_budget` or `regex_timeout` | `partial` | `null` (unknown) | `null` (unknown) |
+| `unreadable_or_corrupt_source` (included in Woods 2.1) | `partial` | `null` (unknown) | `null` (unknown) |
 
 `matched_lower_bound` counts distinct observed `(type, identifier)` matches,
 including at most one lookahead match beyond `limit`. A result-limit response
@@ -245,10 +274,19 @@ therefore establishes another match; an exactly full page can instead be
 complete if the requested domain is exhausted. Deep lookahead shares
 `WOODS_SEARCH_MAX_SCAN` with the initial scan and retains round-robin scanning
 across types. Search does not count the entire omitted tail or offer pagination.
-The existing `types` filter and result labels name directory families:
-`rails_source` includes both Rails and gem source units. Deep reads accept those
-two stored types only in that shared directory; `lookup` and lexical retrieval
-retain the unit's actual `rails_source` or `gem_source` type.
+**Included in Woods 2.1 (#593):** `search.types` accepts concrete unit types
+such as `graphql_mutation` and `gem_source`, plus the directory-family aliases
+`graphql` (all four GraphQL types) and `rails_source` (Rails and gem sources).
+Aliases expand the same way with or without a package/source-path scope.
+Results always carry the actual stored type, so their `(type, identifier)` can
+be passed to `lookup`; an unknown type returns `invalid_params` instead of an
+apparently complete empty result. This corrects the older unscoped family
+labels. Retrieval tools continue to use their own documented concrete-type
+filters; search aliases do not change those contracts.
+
+**Included in Woods 2.1:** typed `lookup` also accepts the `graphql` family
+alias. The returned unit keeps its concrete type, such as `graphql_mutation`;
+prefer that concrete type for follow-up identity checks.
 
 All partial responses retain `partial: true` and include a narrowing `hint`.
 JSON exposes these fields; Markdown, plain text, and Claude formats label the
@@ -257,8 +295,17 @@ Narrow `types`, literal `exact_prefix`/`exact_suffix`, or deep `fields` before
 using discovery as exhaustive evidence. Completeness applies to this index and
 query domain, not to unindexed application code.
 
-Detected missing, unreadable, or corrupt artifacts remain `isError: true` with
-`_meta.error_code: "corrupt_artifact"`. Their `_meta.completeness` has
+**Included in Woods 2.1:** an individual unit that unscoped search needs but
+cannot decode or open is skipped. Search retains readable matches and returns
+successful partial completeness with reason `unreadable_or_corrupt_source`;
+an empty partial answer does not establish absence. Identifier-only matches can
+use published summaries without opening unit bodies, so search is not an
+artifact-integrity check. Inspect `woods_status` and run `woods:validate`.
+Explicit package/source-path scope first reads the full unit set and still
+returns an error if that preflight encounters a damaged body.
+
+Damaged index-wide artifacts, such as a manifest or type index, remain
+`isError: true` with `_meta.error_code: "corrupt_artifact"`. Their `_meta.completeness` has
 `status: "unknown"`, `reason: "unreadable_or_corrupt_source"`, and `null` for
 `has_more`, `total_matches`, and `matched_lower_bound`; no successful empty
 result is substituted. Inspect `woods_status` and run `woods:validate`.
@@ -272,6 +319,10 @@ references (including references to generic PORO and library classes) may have n
 edge. No dependents, a test-only dependent, or a completed traversal does not prove
 there are no production callers. Verify important absence claims in source.
 
+A supporting post-2.0 writer recovers additional [constant source references](EXTRACTOR_REFERENCE.md#constant-source-references)
+(included in Woods 2.1). Upgrading the reader alone cannot add relationships
+to an old index. The coverage warning still applies.
+
 Supporting servers expose the annotated, paginated traversal result in
 `structuredContent.data` for every renderer, including the default packaged
 stdio and HTTP servers. Read `data.total_is_exact`, `data.graph_coverage`, budget
@@ -388,7 +439,31 @@ Partial traversal and pagination metadata retain the budget contract above.
 
 The Ruby server builder contains 15 additional schemas for sessions, pipeline operations, retrieval feedback, temporal snapshots, and Notion sync. They register only when their required collaborators or configuration are wired.
 
-The normal packaged executable does not wire pipeline-operator or feedback-store collaborators. Do not tell users to call those tools after a standard `woods-mcp` launch. Snapshot, session, and Notion capabilities are specialized configurations; document and test the exact embedded server construction when enabling them.
+The normal packaged executable does not boot Rails or load application
+initializers. It does not wire pipeline-operator or feedback-store collaborators.
+`session_trace` needs an in-process configured store supporting `read` and
+`sessions`; enabling the Rails middleware alone does not add it to a separate
+Index process. `notion_sync` needs the API token and database IDs configured in
+that process. These require an explicitly configured custom/embedded builder;
+verify `tools/list`. For ordinary application Notion export, use
+`bin/rails woods:notion_sync`.
+
+Snapshots have a supported packaged path: an existing `woods.sqlite3` is
+auto-discovered. `WOODS_SNAPSHOTS=true` enables store construction but does **not**
+force JSON: bootstrap prefers SQLite and falls back to JSON only if SQLite is
+unavailable or fails. It does not import old JSON history into SQLite. To read
+retained JSON history after SQLite becomes available, use a custom builder with
+an explicit `Woods::Temporal::JsonSnapshotStore` passed as `snapshot_store:`, or
+keep a separate historical reader using that store. See the
+[tool wiring table](MCP_TOOL_COOKBOOK.md#conditional-tools--wiring).
+
+For an embedded builder that supplies `operator:`, `pipeline_extract` checks
+publication after both full and incremental runs. With the Tasks extension,
+a generation-marker or final source-verification failure marks the task
+`failed`; it cannot report `completed` merely because extraction returned.
+Clients without the extension still receive a background-start acknowledgement,
+which does not establish completion. This correction (#584) is included in Woods 2.1; check the loaded server revision. See the
+[publication failure recovery](TROUBLESHOOTING.md#extraction-exits-non-zero-after-could-not-publish-generation).
 
 ### HTTP transport
 
@@ -503,6 +578,10 @@ root/nested ownership, path normalization, errors, storage support, and cost.
 `"deep"` (five seconds). `index.source_freshness` describes the served generation
 as `current`, `drifted` or `unknown`; missing source/key and incomplete capture
 never count as current. No Rails initialization or provider call is needed.
+**Included in Woods 2.1:** evidence above the serialized-size limit produces
+`unavailable` with `source_manifest_too_large` while the code index remains
+usable. Follow `inspect_source_limits` and inspect the reported byte counts;
+repeating an identical full extraction cannot remove this limitation.
 See [source freshness](SOURCE_FRESHNESS.md) for scope, private-key handling and
 fresh-process extraction. Existing HEAD/dirty fields remain separate diagnostics.