v3.0.0: versioned allocator handoff, fail-closed runs, and a much faster matcher

Major release. Read the breaking changes before upgrading.

v2.0.0 made cloud-address attribution a first-class product. v3.0.0 finishes that path: a versioned, schema-checked handoff document for the allocation pipeline, a run that fails closed instead of publishing partial results, a matcher that is about 64 times faster, and a leaner dependency set (three runtime dependencies instead of seven).

Breaking changes

Area	Change
takeover_candidates_*.txt	NS_TAKEOVER records gain a fourth field: NS_TAKEOVER|origin|domain|nameserver. nameserver is the NS host whose address lookup failed, or - where the name has NS records but no address records. Parsers that expect exactly three fields will break.
environment_results_*.json	external_ip is now null unless --record-external-ip (or DNSRESOLVER_RECORD_EXTERNAL_IP=true) is set. The lookup called a third-party service on every start; it is now opt-in.
AWS Lambda	The Lambda entry point (lambda_handler.py), its environment manager, docs/LAMBDA.md, requirements-lambda.txt and the boto3 dependency are removed. The shared run() pipeline stays. Restorable from tag v2.0.0.
Configuration	Boolean options (verbose, extreme, evidence) in config.json now actually apply (they were silently ignored). The shipped config.json leaves all three off, so default behaviour is unchanged. Values in config.json and DNSRESOLVER_* variables are validated: a wrong type or an invalid boolean is an error that names the key, not a silent default.
Pipe file line order	The four pipe files are now written sorted by full line text, so identical input gives byte-identical files under any hash seed. Content is unchanged; do not depend on more than stability.

For the allocation pipeline

• allocator-targets-v1.json: a provider-aware JSON document of actionable cloud addresses, schema-checked (contracts/), grouped by provider, hostname, address and region with all published services, prefixes and network border groups preserved. Wildcard and uncertain results are excluded.
• dns-observations-v1.json and run-manifest-v1.json: everything excluded, with reasons, and a manifest saying whether the run was complete, incomplete or failed. Actionable output is null for an incomplete or failed run.
• Fails closed: a missing or stale AWS, GCP or Azure catalogue stops the run before any domain is processed; a required output that cannot be written is an error, not a swallowed one.
• Every attribution is preserved: overlapping prefixes, the same CIDR published by several providers, and one prefix under several services or regions all survive to the output.

New

• run-report.md: a compact Markdown view of a run, on by default (--format md; --format json skips it). The JSON documents stay canonical and are identical either way. For the golden fixture the targets section is about a quarter of the size of the JSON, which makes a run cheap to read for an agent or a human.
• Configuration from the environment: every option can come from a DNSRESOLVER_* variable. A committed .envrc.example is the template for a git-ignored .envrc (direnv). Precedence: command-line flag, environment, config.json, built-in default. New negated flags: --no-verbose, --no-extreme, --no-evidence.
• Much faster matching: prefixes are indexed by length instead of scanned one by one. On a 55,000-prefix catalogue, 10,000 hostnames take 1.3 s instead of 84.5 s, and 100,000 take 11 s. Output is identical; a property test checks the index against the original linear scan, including nested and duplicated prefixes. bench/ holds the harness and the baseline.
• Reliable DNS resolution: timeouts and nameservers reach both resolver libraries, and A and AAAA fallback results survive.

Leaner and safer to build

• Runtime dependencies: dnspython, tqdm, aiodns. requests, urllib3, aiofiles and boto3 are gone.
• Installs in CI are hash-locked (requirements.lock, requirements-dev.lock), a weekly pip-audit runs, and CI enforces a 95% coverage floor (the suite is at about 97%).
• A byte-exact end-to-end golden test now gates every change to the output files.
• Results are held as structured records and the JSON documents are built from them; the tool no longer re-parses its own output files.
• The delivered per-PR planning documents are archived; ROADMAP.md and REVIEW.md carry the current plan and findings.

Upgrading from v2.0.0

1. If you parse takeover_candidates_*.txt, accept a fourth NS_TAKEOVER field.
2. If you read external_ip from environment_results_*.json, pass --record-external-ip.
3. If you deployed the Lambda entry point, stay on v2.0.0 or run the CLI instead.
4. Optional: copy .envrc.example to .envrc and direnv allow.

Full detail is in README.md and AGENTS.md; the plan and decisions behind this release are in ROADMAP.md and REVIEW.md.