Adds Predicator.Analysis: references, calls, assignments

[johnnyt]

What

Adds Predicator.Analysis, a reading surface in the Predicator.Vocabulary mould:

• references/1 - every variable read, as %{path: [segment], position: pos | nil}.
• calls/1 - every function call, as %{name: name, arity: n, position: pos | nil}, nested calls included, the outer call first; a qualified name (ns.fn) keeps its dots.
• assignments/1 - every store target of a program, as %{path: [segment], position: pos | nil}.

A segment is a string, an integer (a literal integer index) or :dynamic (any other bracket key); the path continues past :dynamic, and a computed key's own reads are references of their own. Every occurrence is listed, in source order; a caller dedupes. The answer shape was ruled by the operator, 2026-10-12. Assignments walk the location chain (identifier, property access, bracket access) directly and never call Predicator.ContextLocation, ruled by the operator, 2026-10-13.

Each function accepts a source string, an AST (or a statement or block), a program, an instruction list or a Predicator.Compiled envelope, and answers {:ok, list}.

The instruction form rebuilds paths through a symbolic stack: load then access/bracket_access runs, a lit before a bracket_access folding to a string or integer segment and anything else :dynamic, calls from call, store targets from store, positions from the envelope's table when it has one, else nil. That reconstruction and the opcode coverage below were decided by the conductor under a standing consent, 2026-10-12 (the coverage of the retired opcodes, 2026-10-13).

ADR-0020 records the decision at proposed, with the index row, and docs/architecture.md gains a component-map entry. Changelog fragment changelog.d/px-533c.md (Added).

No ISA change, no opcode, no corpus change, and no existing function changes what it answers.

Tests

• test/predicator/analysis_test.exs - unit cases per function and per input form, the module's doctests, and the refusals.
• test/predicator/analysis_forms_test.exs - the AST and instruction forms agree on a table of expression and program sources: paths, calls and stores in every form, positions wherever the instruction form has a table (point and span). Two companion tests prove the table reaches every node kind the parser builds and every opcode the compiler emits. The one disagreement the test allows is positions from a bare instruction list, which carries none.
• test/predicator/analysis_clause_coverage_test.exs - binding: the AST clause heads against the constructors of Parser.visitable/0, and the instruction clause heads against every key of Predicator.Instructions.opcodes/0, retired and/or included, both ways. Added to gate.sabotage.test_roots in .claude/wurk.json.

Sabotage, each run against the branch and restored byte-equal before the next:

Mutation	Red
a probe constructor added to ast/0 in parser.ex	the node-kind sync test (constructor count)
the :duration clause tag renamed in analysis.ex	the node-kind sync test ("missing")
a probe opcode added to opcodes/0	the opcode sync test (opcode count)
the ["or"] clause renamed in analysis.ex	the opcode sync test ("missing")
the integer arm dropped from the literal-key fold	the path reconstruction test and the agreement tests for sources with a literal index
the bottom-first reorder dropped from popping several values	the path reconstruction test and the agreement tests for multi-segment stores and calls of two or more arguments

Full mix quality green on the committed tree: Format, Compile, Credo, Tests, Dialyzer, Docs, Doc links and Dependencies pass; Doctor is not installed (a standing project gap), Gettext and Sobelow are declared not applicable.

Provenance

Engineering choices made in this branch, each recorded in ADR-0020:

• A source string is read as a program, as Predicator.parse_program/2 reads it. Every expression is a one-statement program and = is never equality (ADR-0002), so a condition reads the same either way and a script written as a string is analysed too. A test checks that every source in the agreement table answers the same as a string, as a program and as an expression AST.
• A literal bracket key that is neither a string nor an integer (a[true], a[1.5]) is :dynamic, so it fits the ruled segment shape.
• A path's position starts where the path starts: the whole chain's span when the program carries spans, else the root variable's point. An assignment follows the compiler's store-blame rule (the assignment's span, or the root's point).
• The error arm reuses existing terms: the ParseError compile_program/1 returns, and an EvaluationError with the evaluator's "unknown_instruction" reason for an unknown opcode or a malformed operand. A list that underflows is read as far as it goes. No new reason term.
• The ADR is at proposed, as docs/adr/README.md's Status paragraph has it: "An ADR is proposed while it is drafted and accepted once the maintainer confirms it records the decision as actually made. An agent may draft; only the maintainer accepts". This repo's work extension asks for accepted or nothing; the README's lifecycle is the one this record follows, and its own Consequences say the flip is a separate reviewed change.
• No ## Notes section yet: the record carries no note to put there.

Tier: contract (a new public module). Cold review to follow; this PR stops at open.

Refs: px-533c

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines	Coverage Δ
lib/predicator/analysis.ex	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.