From 68cac2c0bb5d4723155c7a9ef024d31e3e4070ee Mon Sep 17 00:00:00 2001
From: Scott Arciszewski <scott.arciszewski@trailofbits.com>
Date: Mon, 26 Oct 2026 18:21:20 -0400
Subject: [PATCH] Prepare v0.7.1 release notes and package metadata

---
 CHANGELOG.md              | 79 +++++++++++++++++++++++++++++++++++++++
 docs/cli.md               |  3 +-
 docs/python-api.md        |  1 +
 pyproject.toml            |  2 +-
 src/trailmark/__init__.py |  2 +-
 tests/test_docs.py        |  2 +
 uv.lock                   |  2 +-
 7 files changed, 87 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 28a20d9..580392d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,84 @@
 # Changelog
 
+## 0.7.1 (2026-10-26)
+
+This release adds source-backed entrypoint evidence and explicit source selection,
+improves Python analysis performance, and expands PHP and GraphQL coverage.
+
+### Added
+
+- **Entrypoint evidence and candidates:** `EntrypointEvidence` records source
+  occurrences, target bindings, discovery rules, and unresolved facts. Inspect
+  them with `entrypoint_evidence()`, `entrypoint_candidates()`, and
+  `trailmark entrypoints --evidence` or `--candidates`. Add observations through
+  `add_entrypoint_evidence()` without promoting a candidate to an entrypoint.
+- **Explicit source selection:** `SourceRoot`, `SourcePolicy`, and `parse_roots()`
+  select named application or dependency roots with include/exclude globs and
+  canonical file deduplication across every supported frontend. `analyze` and
+  `entrypoints` accept repeatable `--source-root`, `--include`, and `--exclude`
+  options. `source_policy()` and graph JSON retain the effective selection and
+  inspected, skipped, and unparsed file decisions.
+- **Indirect reference discovery:** Python and PHP callable values and supported
+  qualified symbol/file references in GraphQL, JSON, YAML, XML, and TOML retain
+  source provenance and ambiguous or unresolved targets. New `references` edges
+  remain separate from execution paths; a reference does not establish external
+  invocation, authentication, or registrar behavior.
+- **Executable PHP bodies:** `.phtml` templates and top-level `.php` statements
+  have synthetic `<template>` and `<script>` functions that own their direct
+  calls. Anchored `include`/`require` paths can link to inspected executable
+  bodies; dynamic and include-search-path-dependent targets stay unresolved.
+  GraphQL source discovery also accepts `.graphqls` files.
+
+### Changed
+
+- Resolve Python decorator bindings through imports, aliases, enclosing scopes,
+  and literal path constants. Exclude unrelated key-based decorators and proven
+  local identity decorators while retaining uncertainty for conditional bindings
+  and unknown arguments.
+- Require exported module-level callables for ECMAScript file-route conventions.
+  Preserve export aliases, default and CommonJS source occurrences, and wrapper
+  uncertainty without assigning a framework solely from the export name.
+
+### Performance
+
+- Select decorated Python functions before building lexical scopes and scan for
+  possible replacement writes only when an identity-decorator proof needs it.
+  A fixed 143-file Python corpus analyzed about 13% faster than the initial
+  entrypoint-evidence implementation in a local alternating benchmark, with
+  identical complete graph output. Results depend on the corpus; this is not a
+  comparison against 0.7.0.
+
+### Fixed
+
+- Recover valid PHP `TRUE`/`FALSE` class constant names without moving source
+  coordinates or hiding unrelated syntax diagnostics.
+- Recover valid GraphQL string escapes rejected by the packaged grammar while
+  preserving source offsets and decoding original literal values.
+- Preserve entrypoint detection and local override behavior under named source
+  roots, and keep callable ownership and binding uncertainty in discovery
+  evidence rather than inferring execution from references.
+
+### Packaging and development
+
+- Run mutation CI across eight shards with four workers each, validating clean
+  and instrumented baselines and requiring every shard to pass. Keep the complete
+  selected fallback suite for each mutant and prioritize private-helper tests.
+- Add a repeatable full-analysis benchmark with timing and complete-graph
+  fingerprints, plus binding and reference regressions that kill 21 mutants
+  surviving the preceding full CI campaign.
+
+### Upgrading from 0.7.0
+
+- Accept `EdgeKind.REFERENCES` and the additional `source_policy` and
+  `entrypoint_evidence` export fields. Export schema version remains `1`.
+  Rebuild saved graphs to obtain discovery evidence and executable PHP bodies;
+  matched data references can also add synthetic provenance modules and change
+  node counts. Compare code changes using graphs built with the same version.
+- Multiple selected roots prefix IDs with `root_name::`. Ordinary call linking
+  stays within each root unless explicit linking evidence connects them.
+  Directory parses deduplicate canonical files and exclude file symlinks that
+  escape their root, which can change inspected file counts.
+
 ## 0.7.0 (2026-10-23)
 
 This release adds nine language frontends, Solidity storage-access graphs, and
diff --git a/docs/cli.md b/docs/cli.md
index 052069a..46ac9b3 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -196,7 +196,8 @@ Prints `trailmark X.Y.Z`.
 ## Version notes
 
 `trailmark diagram` was added in 0.4.0, and `trailmark analyze --resolution` in
-0.7.0. Every other subcommand and flag has been available since 0.2.2.
+0.7.0. Entrypoint `--evidence` and `--candidates`, along with source-selection
+`--source-root`, `--include`, and `--exclude` options, were added in 0.7.1.
 
 ## Strict source analysis
 
diff --git a/docs/python-api.md b/docs/python-api.md
index 8b9907b..f783599 100644
--- a/docs/python-api.md
+++ b/docs/python-api.md
@@ -334,6 +334,7 @@ with older releases can check `trailmark.__version__` or probe with `hasattr()`.
 | 0.3.0 | `trailmark.parse` (`parse_file`, `parse_directory`, `detect_languages`, `supported_languages`) |
 | 0.4.0 | `connect_subgraphs`, `subgraph_edges`, `generic_parameters`, `type_references`, `augment_binary`, proxy nodes |
 | 0.7.0 | `state_read_by`, `state_written_by`, `readers_of`, `writers_of`, `unresolved_calls`, `call_resolution`; `replace_existing` on the finding importers; keyword-only `max_depth` on `paths_between`; directory `allow_empty`, source-file coverage in summaries and diffs, and the expanded structural diff fields above |
+| 0.7.1 | `SourceRoot`, `SourcePolicy`, `parse_roots`, directory `source_policy`; `source_policy()`, `entrypoint_evidence()`, `entrypoint_candidates()`, `add_entrypoint_evidence()`, `EntrypointEvidence`, and `EdgeKind.REFERENCES` |
 
 ## Source analysis diagnostics
 
diff --git a/pyproject.toml b/pyproject.toml
index 524492e..e00c5f4 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -22,7 +22,7 @@ reinstall-package = ["trailmark"]
 
 [project]
 name = "trailmark"
-version = "0.7.0"
+version = "0.7.1"
 description = "Parse source code into a queryable graph of functions, classes, calls, and semantic annotations"
 readme = "README.md"
 requires-python = ">=3.12"
diff --git a/src/trailmark/__init__.py b/src/trailmark/__init__.py
index 7b3890f..9191c96 100644
--- a/src/trailmark/__init__.py
+++ b/src/trailmark/__init__.py
@@ -18,4 +18,4 @@
     "SourceRoot",
     "supported_languages",
 ]
-__version__ = "0.7.0"
+__version__ = "0.7.1"
diff --git a/tests/test_docs.py b/tests/test_docs.py
index 369732c..93beb6c 100644
--- a/tests/test_docs.py
+++ b/tests/test_docs.py
@@ -147,6 +147,8 @@ def pyproject_data() -> dict[str, object]:
     # Mutation testing
     ("CONTRIBUTING.md", "tests.benchmark_analysis /path/to/corpus --language python --repeat 7"),
     ("CONTRIBUTING.md", "complete graph output with `graph_sha256`"),
+    ("docs/cli.md", "`--source-root`, `--include`, and `--exclude` options, were added in 0.7.1."),
+    ("docs/python-api.md", "| 0.7.1 | `SourceRoot`, `SourcePolicy`, `parse_roots`"),
     ("CONTRIBUTING.md", "tests.run_mutations --reviewed --workers=4"),
     ("CONTRIBUTING.md", "tests.run_mutations --workers=4"),
     ("CONTRIBUTING.md", "tests.mutation_gate"),
diff --git a/uv.lock b/uv.lock
index dc101ef..d27ccd6 100644
--- a/uv.lock
+++ b/uv.lock
@@ -415,7 +415,7 @@ wheels = [
 
 [[package]]
 name = "trailmark"
-version = "0.7.0"
+version = "0.7.1"
 source = { editable = "." }
 dependencies = [
     { name = "rustworkx" },