gebra 0.0.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. gebra/__init__.py +114 -0
  2. gebra/annotations/__init__.py +154 -0
  3. gebra/annotations/contract.py +1036 -0
  4. gebra/annotations/errors.py +93 -0
  5. gebra/annotations/inference.py +1426 -0
  6. gebra/annotations/resolve.py +676 -0
  7. gebra/annotations/sidecar.py +776 -0
  8. gebra/annotations/slots.py +105 -0
  9. gebra/audit/__init__.py +79 -0
  10. gebra/audit/export.py +332 -0
  11. gebra/audit/freshness.py +128 -0
  12. gebra/audit/models.py +258 -0
  13. gebra/cli/__init__.py +47 -0
  14. gebra/cli/__main__.py +8 -0
  15. gebra/cli/app.py +681 -0
  16. gebra/cli/common.py +148 -0
  17. gebra/cli/diff.py +556 -0
  18. gebra/cli/display.py +307 -0
  19. gebra/cli/history.py +353 -0
  20. gebra/cli/invocation.py +192 -0
  21. gebra/cli/render.py +126 -0
  22. gebra/cli/resolve.py +378 -0
  23. gebra/cli/snapshot.py +343 -0
  24. gebra/cli/verify.py +357 -0
  25. gebra/diff/__init__.py +118 -0
  26. gebra/diff/contracts.py +375 -0
  27. gebra/diff/graph.py +190 -0
  28. gebra/diff/models.py +338 -0
  29. gebra/diff/state.py +260 -0
  30. gebra/diff/topology.py +367 -0
  31. gebra/diff/workflow.py +220 -0
  32. gebra/display/__init__.py +26 -0
  33. gebra/display/mermaid.py +240 -0
  34. gebra/display/overlay.py +349 -0
  35. gebra/extraction/__init__.py +231 -0
  36. gebra/extraction/base.py +83 -0
  37. gebra/extraction/builder.py +1229 -0
  38. gebra/extraction/compat.py +392 -0
  39. gebra/extraction/compiled.py +1330 -0
  40. gebra/extraction/contracts.py +616 -0
  41. gebra/extraction/digests.py +813 -0
  42. gebra/extraction/dispatch.py +320 -0
  43. gebra/extraction/envelope.py +297 -0
  44. gebra/extraction/errors.py +127 -0
  45. gebra/extraction/inference.py +82 -0
  46. gebra/extraction/lcel.py +1192 -0
  47. gebra/extraction/routing.py +309 -0
  48. gebra/extraction/sidecar.py +104 -0
  49. gebra/extraction/state.py +693 -0
  50. gebra/extraction/stock.py +121 -0
  51. gebra/extraction/warnings.py +368 -0
  52. gebra/ir/__init__.py +181 -0
  53. gebra/ir/base.py +59 -0
  54. gebra/ir/canonical.py +791 -0
  55. gebra/ir/identity.py +590 -0
  56. gebra/ir/models.py +515 -0
  57. gebra/ir/serialization.py +617 -0
  58. gebra/lineage/__init__.py +72 -0
  59. gebra/lineage/document.py +138 -0
  60. gebra/lineage/engine.py +265 -0
  61. gebra/lineage/models.py +244 -0
  62. gebra/naming.py +84 -0
  63. gebra/py.typed +0 -0
  64. gebra/pytest_plugin.py +2279 -0
  65. gebra/report/__init__.py +164 -0
  66. gebra/report/anchors.py +300 -0
  67. gebra/report/evidence.py +373 -0
  68. gebra/report/findings.py +149 -0
  69. gebra/report/human.py +465 -0
  70. gebra/report/native.py +38 -0
  71. gebra/report/rules.py +293 -0
  72. gebra/report/sarif.py +257 -0
  73. gebra/report/suggestions.py +82 -0
  74. gebra/snapshot/__init__.py +72 -0
  75. gebra/snapshot/engine.py +524 -0
  76. gebra/snapshot/models.py +164 -0
  77. gebra/store/__init__.py +121 -0
  78. gebra/store/atomic.py +124 -0
  79. gebra/store/base.py +63 -0
  80. gebra/store/models.py +361 -0
  81. gebra/store/serialization.py +198 -0
  82. gebra/store/store.py +507 -0
  83. gebra/testing/__init__.py +122 -0
  84. gebra/testing/fixtures.py +808 -0
  85. gebra/testing/harness.py +894 -0
  86. gebra/testing/mutations.py +2172 -0
  87. gebra/testing/strategies.py +1027 -0
  88. gebra/verify/__init__.py +422 -0
  89. gebra/verify/base.py +358 -0
  90. gebra/verify/conditions.py +741 -0
  91. gebra/verify/graph.py +898 -0
  92. gebra/verify/guards.py +657 -0
  93. gebra/verify/locations.py +245 -0
  94. gebra/verify/properties/__init__.py +37 -0
  95. gebra/verify/properties/dataflow_completeness.py +673 -0
  96. gebra/verify/properties/determinism_replay.py +334 -0
  97. gebra/verify/properties/effect_safety.py +489 -0
  98. gebra/verify/properties/graph_well_formed.py +351 -0
  99. gebra/verify/properties/termination_witness.py +1023 -0
  100. gebra/verify/registry.py +477 -0
  101. gebra/verify/report.py +242 -0
  102. gebra/verify/run.py +863 -0
  103. gebra/verify/witnesses.py +430 -0
  104. gebra/versioning/__init__.py +85 -0
  105. gebra/versioning/classify.py +289 -0
  106. gebra/versioning/models.py +301 -0
  107. gebra-0.0.1.dist-info/METADATA +453 -0
  108. gebra-0.0.1.dist-info/RECORD +112 -0
  109. gebra-0.0.1.dist-info/WHEEL +4 -0
  110. gebra-0.0.1.dist-info/entry_points.txt +5 -0
  111. gebra-0.0.1.dist-info/licenses/LICENSE +201 -0
  112. gebra-0.0.1.dist-info/licenses/NOTICE +2 -0
@@ -0,0 +1,1426 @@
1
+ """Shallow contract inference — ANNOTATION-API-SPEC §4 (ratified — DEC-08).
2
+
3
+ The lowest tier of §3's precedence chain, and the only one that reads no declaration: what a
4
+ node's own source makes statically evident. DEC-08 fixed its depth in one word — **shallow**
5
+ — and §4 turns that into a closed table of five licensed patterns over two slots. Nothing
6
+ outside that table is inferred, and two slots is the whole reach:
7
+
8
+ =========== ===================================================================
9
+ ``input`` (a) a state-parameter annotation that is a ``TypedDict``/pydantic
10
+ **projection** — its declared keys; (b) a literal subscript or
11
+ attribute read of the state parameter in the node's own body.
12
+ ``output`` (a) a literal dict display returned; (b) a ``TypedDict`` return
13
+ annotation — its keys; (c) a literal ``Command(update={...})``
14
+ construction in the node body.
15
+ =========== ===================================================================
16
+
17
+ Four properties carry the module, and each is enforced rather than described.
18
+
19
+ **NEVER-SILENT-UPGRADE, structurally.** §4: inference "**never** yields ``idempotent``,
20
+ ``deterministic``, ``variant``, or ``compensation``" — those slots unlock retry, memoisation,
21
+ termination-witness and compensation reasoning that "must be opted into by an explicit
22
+ declaration" — and §1 adds ``args_schema`` ("never inferred — the §4 closed pattern table has
23
+ no pattern for it"). So the contract this module returns is built at exactly one place, from
24
+ four literal keywords (:func:`_contribution`). A fifth slot cannot be set by a code path that
25
+ does not exist, which is a stronger statement than a test, and the test is there as well.
26
+
27
+ **Nothing is evaluated.** §4: inference "consumes exactly the node callable's own AST and the
28
+ graph state schema — nothing else — in a single pass … no imports are followed and no code is
29
+ evaluated (never-invokes, decision D-018)". This module therefore never calls
30
+ :func:`typing.get_type_hints`, which §6 licenses for the *router-classification* read and
31
+ which would ``eval`` a string annotation in its module's namespace. A ``str`` annotation —
32
+ what ``from __future__ import annotations`` leaves behind — is simply not a licensed pattern
33
+ match, recorded as :attr:`Blocker.STRING_ANNOTATION`. The annotation *objects* the patterns
34
+ do read come off the function's own ``__annotations__``, where the interpreter put them at
35
+ ``def`` time; reading them evaluates nothing.
36
+
37
+ **The source is read, not fetched.** :func:`read_node_source` locates the definition itself —
38
+ ``__code__.co_filename`` and ``co_firstlineno``, the file's bytes, :func:`ast.parse` — rather
39
+ than through :func:`inspect.getsource`. The difference is WA-07: ``inspect`` routes through
40
+ :mod:`linecache`, which for a file that is not on disk calls the module's own
41
+ ``__loader__.get_source()`` — user code — and through :func:`inspect.getmodule`, which sweeps
42
+ ``sys.modules`` reading ``__file__`` attributes that a PEP-562 module ``__getattr__`` can
43
+ intercept. Neither is reachable from here.
44
+
45
+ **Conservative where it cannot see.** D-011's floor is restated by §4: a node that writes
46
+ state resolves to ``effect: [write]``, a node with no write evidence to ``pure: true``, and
47
+ both are warned. The second is "a no-evidence-found result, not a proof" — so a body this
48
+ module could not read at all takes the ``effect: [write]`` floor, never ``pure``: D-011's own
49
+ words are "``pure`` for **provably** read-only", and an unread body proves nothing.
50
+
51
+ **What this module does not do.** It does not resolve anything into an IR and it does not
52
+ rank itself against the other tiers. §3's per-slot chain (Decorator > Tool-carried > Sidecar >
53
+ Inference), its conflict warnings and the resolved-contract validation are a later card. The
54
+ one part of §3 that lives here is the sentence inference cannot be written without —
55
+ "Inference (lowest) … fills what remains": :func:`infer` is told which slots the higher tiers
56
+ already filled and contributes to none of them, because a ``contract-inferred`` warning naming
57
+ a *declared* slot would make §5's grade lookup call that slot heuristic-grade.
58
+
59
+ Nothing here imports langgraph, opens a socket, or executes anything (WA-07). It reads one
60
+ file — the one that defines the node — and parses it as an AST; no value in it is called, and
61
+ :func:`ast.parse` compiles nothing that can run. **Four residuals, stated rather than
62
+ implied**, in the voice :mod:`gebra.annotations.contract` uses for its own, because "executes
63
+ nothing" would be too strong for a surface that reads objects the caller built:
64
+
65
+ * recognizing a pydantic projection reads ``model_fields`` off the annotation class, and that
66
+ is a metaclass property. There is no way to learn a model's field names without asking the
67
+ model; a class that answers by raising is read as "no projection" rather than allowed to
68
+ abort the extraction.
69
+ * the state schema and annotation objects arrive from the caller. They are compared by
70
+ identity and their declared keys are read through unbound built-in accessors, so a hostile
71
+ ``__eq__`` or metaclass ``__getattr__`` is not consulted — but ``issubclass`` consults
72
+ pydantic's own ``__subclasscheck__``, and a metaclass-level ``__dict__`` property would be a
73
+ data descriptor that ``getattr`` runs.
74
+ * :func:`ast.parse` is given **bytes**, so the file's own PEP 263 coding cookie decides how it
75
+ is decoded — the same decision the interpreter made when it imported the module. A cookie
76
+ naming a codec that is not yet loaded reaches :func:`codecs.lookup`, which consults
77
+ registered search functions and imports an ``encodings`` submodule. Reachable only for a
78
+ file this module was pointed at but the interpreter never imported; the alternative,
79
+ decoding as UTF-8 regardless, would silently misread a legally-encoded module. The tripwire
80
+ arms it: nothing may load a module that was not already imported.
81
+ * the walk descends recursively, and a body nested past the interpreter's stack is caught and
82
+ read as "no body" (the D-011 floor) rather than raised.
83
+
84
+ **One question this module does not answer, recorded for the card that fills a slot.** §4's
85
+ keys come out of arbitrary source text, and IR-SPEC §6.3 makes ``input``/``output`` entries
86
+ identifier-role — NFC, no lone surrogates. A node reading ``state["café"]`` spelled decomposed
87
+ would make ``graph_version()`` unobtainable for the whole document once §3 resolves the slot.
88
+ Whether a heuristic-grade key may be *dropped* rather than break a digest is a spec question
89
+ (IR-SPEC §6.3 ⊗ ANNOTATION §4), not an implementation choice, so this module emits what the
90
+ source says and the question travels with the resolution card.
91
+ """
92
+
93
+ from __future__ import annotations
94
+
95
+ import ast
96
+ import types
97
+ from collections.abc import Iterable, Mapping
98
+ from dataclasses import dataclass, field
99
+ from enum import Enum
100
+ from pathlib import Path
101
+ from types import MappingProxyType
102
+ from typing import Any, Final, TypeAlias
103
+
104
+ from pydantic import BaseModel
105
+
106
+ from gebra.annotations.contract import NodeContract
107
+ from gebra.annotations.slots import ANNOTATION_SLOTS, AnnotationSlot, SlotGrade
108
+ from gebra.naming import type_identity
109
+
110
+ __all__ = [
111
+ "DEFAULT_EFFECT",
112
+ "HEURISTIC_GRADES",
113
+ "INFERENCE_SLOTS",
114
+ "MUTATING_METHODS",
115
+ "NEVER_INFERRED",
116
+ "Blocker",
117
+ "DefaultRule",
118
+ "Inference",
119
+ "InferenceFinding",
120
+ "InferredKey",
121
+ "NodeSource",
122
+ "Pattern",
123
+ "SourceCache",
124
+ "SourceRule",
125
+ "StateSchema",
126
+ "infer",
127
+ "infer_node",
128
+ "read_node_source",
129
+ ]
130
+
131
+ #: The two slots §4's pattern table licenses, plus the two the D-011 defaults fill. Nothing
132
+ #: else is reachable: :func:`_contribution` names exactly these four and there is no other
133
+ #: construction site.
134
+ INFERENCE_SLOTS: Final[tuple[AnnotationSlot, ...]] = ("input", "output", "effect", "pure")
135
+
136
+ #: The slots inference **never** yields, written out from the specs rather than derived from
137
+ #: :data:`INFERENCE_SLOTS`, so that a test can assert the two partition
138
+ #: :data:`~gebra.annotations.slots.ANNOTATION_SLOTS` instead of restating the code.
139
+ #:
140
+ #: The first four are §4's NEVER-SILENT-UPGRADE rule (DEC-08): they "unlock retry,
141
+ #: memoisation, termination-witness, and compensation reasoning (P-02, P-06–P-08) that must be
142
+ #: opted into by an explicit declaration". ``args_schema`` is §1's own sentence — "never
143
+ #: inferred — the §4 closed pattern table has no pattern for it".
144
+ NEVER_INFERRED: Final[tuple[AnnotationSlot, ...]] = (
145
+ "idempotent",
146
+ "deterministic",
147
+ "variant",
148
+ "compensation",
149
+ "args_schema",
150
+ )
151
+
152
+ #: The decision D-011 conservative floor for a node that writes state (§4). One tag, from the
153
+ #: closed D-011 vocabulary — "a conservative floor, not a claim" (§5).
154
+ DEFAULT_EFFECT: Final[tuple[str, ...]] = ("write",)
155
+
156
+ #: The two §4 grades a finding can carry. §5's third, :attr:`SlotGrade.DECLARED`, is what the
157
+ #: *absence* of a finding means, so :class:`InferenceFinding` refuses it.
158
+ HEURISTIC_GRADES: Final[tuple[SlotGrade, ...]] = (SlotGrade.INFERRED, SlotGrade.DEFAULTED)
159
+
160
+ #: Method names that mutate the object they are called on, closed over the built-in container
161
+ #: types a LangGraph state (or a value inside one) actually has: ``dict``, ``list`` and
162
+ #: ``set``. A call to one of these on an expression rooted at the state parameter is the
163
+ #: "mutation of the state parameter" half of §4's write-evidence test — the half that is not a
164
+ #: licensed output pattern. Every other method call on the state parameter is left alone:
165
+ #: ``state.get("k")`` and ``state.keys()`` read, and reading is not writing.
166
+ MUTATING_METHODS: Final[frozenset[str]] = frozenset(
167
+ {
168
+ "update",
169
+ "setdefault",
170
+ "pop",
171
+ "popitem",
172
+ "clear",
173
+ "append",
174
+ "extend",
175
+ "insert",
176
+ "remove",
177
+ "sort",
178
+ "reverse",
179
+ "add",
180
+ "discard",
181
+ "difference_update",
182
+ "intersection_update",
183
+ "symmetric_difference_update",
184
+ "__setitem__",
185
+ "__delitem__",
186
+ }
187
+ )
188
+
189
+ #: The name a literal fan-out/update construction is written under (§4 output pattern (c)).
190
+ _COMMAND: Final = "Command"
191
+
192
+ #: How large a defining module this reader will parse, in bytes. A bound rather than a policy:
193
+ #: it exists so that a ``co_filename`` naming something enormous degrades to the D-011 floor
194
+ #: instead of reading it, and it sits far above any module a person writes.
195
+ _MAX_SOURCE_BYTES: Final = 4 * 1024 * 1024
196
+
197
+ #: How many parsed modules one :class:`SourceCache` holds before it starts over.
198
+ _MAX_CACHED_MODULES: Final = 256
199
+
200
+
201
+ class Pattern(str, Enum):
202
+ """The §4 licensed pattern that put one key in a slot — the citation §4 requires.
203
+
204
+ §4: inference emits "one licensed-pattern citation per emitted key (carried by that node's
205
+ ``contract-inferred`` warning)", and INTROSPECTION §8's row names the same four spellings
206
+ ("annotation keys / literal state access / literal return / ``Command(update=...)``").
207
+ The table is closed: a key with no citation here is a key this module cannot emit.
208
+ """
209
+
210
+ STATE_ANNOTATION_KEYS = "state-annotation-keys"
211
+ """``input`` (a) — the declared keys of a projection annotation on the state parameter."""
212
+
213
+ STATE_ACCESS = "state-access"
214
+ """``input`` (b) — a literal ``state["k"]`` / ``state.k`` read in the node's own body."""
215
+
216
+ RETURN_LITERAL = "return-literal"
217
+ """``output`` (a) — a literal dict display in a ``return`` statement."""
218
+
219
+ RETURN_ANNOTATION_KEYS = "return-annotation-keys"
220
+ """``output`` (b) — the declared keys of a ``TypedDict`` return annotation."""
221
+
222
+ COMMAND_UPDATE = "command-update"
223
+ """``output`` (c) — a literal ``Command(update={...})`` construction in the body."""
224
+
225
+
226
+ class SourceRule(str, Enum):
227
+ """Whether a node's own AST could be read, and if not, why (§4's first argument).
228
+
229
+ Every member other than :attr:`READ` sends the node to the D-011 floor: §4's defaults are
230
+ what a node "outside the patterns" falls to, and a body that could not be read is outside
231
+ every pattern. The distinction is kept because it is the "why no pattern applied" field
232
+ the ``contract-defaulted`` registry row asks for.
233
+ """
234
+
235
+ READ = "read"
236
+ """The definition was located and parsed."""
237
+
238
+ NOT_A_PYTHON_FUNCTION = "not-a-python-function"
239
+ """The node is not a Python function or bound method — a callable object, a
240
+ ``functools.partial``, a built-in, a ``Runnable``. Following it inward to something that
241
+ *is* one is §6's wrapper walk, which belongs to the resolution card, not to §4."""
242
+
243
+ OPAQUE = "opaque"
244
+ """The caller declared the node opaque — §4: "opaque nodes (``RunnableLambda`` bodies …)
245
+ skip inference entirely and go straight to defaults"."""
246
+
247
+ SOURCE_UNAVAILABLE = "source-unavailable"
248
+ """No readable source file: a definition compiled from a string or a REPL, a file that is
249
+ gone, unreadable, not a regular file, or past :data:`_MAX_SOURCE_BYTES`."""
250
+
251
+ SOURCE_UNPARSABLE = "source-unparsable"
252
+ """The file exists but is not parsable Python — it changed since it was imported, or it
253
+ is a compiled artifact whose ``co_filename`` points at something else."""
254
+
255
+ DEFINITION_NOT_FOUND = "definition-not-found"
256
+ """The file parsed, but no definition in it matches the code object's name and line."""
257
+
258
+ DEFINITION_AMBIGUOUS = "definition-ambiguous"
259
+ """Several definitions match — two ``lambda``\\ s on one line, and nothing in the code
260
+ object separates them. Refused rather than guessed: the wrong body is worse than none."""
261
+
262
+
263
+ class DefaultRule(str, Enum):
264
+ """Which decision D-011 conservative default applied, and on what evidence (§4).
265
+
266
+ §4 states two, and the third is what its own wording leaves for the case where the body
267
+ could not be examined at all — see :attr:`BODY_UNAVAILABLE`.
268
+ """
269
+
270
+ WRITES_STATE = "writes-state"
271
+ """"An unannotated node that writes state resolves to ``effect: [write]``" (§4)."""
272
+
273
+ NO_WRITE_EVIDENCE = "no-write-evidence"
274
+ """"A node with **no write evidence under the closed §4 patterns** … resolves to
275
+ ``pure: true``" — "a no-evidence-found result, not a proof" (§4)."""
276
+
277
+ BODY_UNAVAILABLE = "body-unavailable"
278
+ """The body was never examined, so the floor applies: ``effect: [write]``.
279
+
280
+ §4's second bullet requires that "no licensed output pattern matches **and** no
281
+ assignment/mutation of the state parameter appears in the node body" — a test on what the
282
+ body shows. An unread body shows neither, and D-011's own words are "``pure`` for
283
+ **provably** read-only" (INTROSPECTION §5 rule 5 repeats them for the opaque case), so
284
+ reading the absence of evidence as evidence of absence is the one thing this rule is
285
+ there to prevent."""
286
+
287
+
288
+ #: The default rules whose applied value is the :data:`DEFAULT_EFFECT` floor — two of the
289
+ #: three, since the third *is* the ``pure`` case.
290
+ _EFFECT_DEFAULTS: Final[frozenset[DefaultRule]] = frozenset(
291
+ {DefaultRule.WRITES_STATE, DefaultRule.BODY_UNAVAILABLE}
292
+ )
293
+
294
+
295
+ class Blocker(str, Enum):
296
+ """Why a §4 pattern did not apply — the "why no pattern applied" field of the registry.
297
+
298
+ Closed, and deliberately specific: a node that fell to the defaults because its state
299
+ parameter is annotated with the graph's own state schema has a different repair (annotate
300
+ a projection, or declare the contract) from one whose returns are built by a helper.
301
+ """
302
+
303
+ NO_STATE_PARAMETER = "no-state-parameter"
304
+ """The callable declares no positional parameter, so §4's state parameter does not
305
+ exist and neither input pattern has a subject."""
306
+
307
+ NO_ANNOTATION = "no-annotation"
308
+ """The state parameter (or the return) carries no annotation."""
309
+
310
+ STRING_ANNOTATION = "string-annotation"
311
+ """The annotation is a string — ``from __future__ import annotations``, or an explicit
312
+ forward reference. Resolving it means evaluating it, which §4 forbids."""
313
+
314
+ STATE_SCHEMA_UNKNOWN = "state-schema-unknown"
315
+ """No graph state schema was supplied, so the §4 full-state exclusion cannot be
316
+ checked — and applying pattern (a) without it is exactly the case the exclusion is
317
+ about."""
318
+
319
+ FULL_STATE_ANNOTATION = "full-state-annotation"
320
+ """§4's full-state-annotation exclusion: the annotation *is* the graph's state schema, so
321
+ it "carries no selective read/write information"."""
322
+
323
+ NOT_A_PROJECTION = "not-a-projection"
324
+ """The annotation is neither a ``TypedDict`` nor a pydantic model, so it declares no
325
+ keys to read."""
326
+
327
+ NOT_A_TYPED_DICT = "not-a-typed-dict"
328
+ """The **return** annotation is a pydantic model. §4's table licenses a
329
+ ``TypedDict``/pydantic projection on the state parameter and a ``TypedDict`` return
330
+ annotation, and the table is closed — so this projection is one gebra may not read here."""
331
+
332
+ PROJECTION_UNREADABLE = "projection-unreadable"
333
+ """The annotation is a pydantic model that would not say what fields it declares."""
334
+
335
+ STATE_PARAMETER_REBOUND = "state-parameter-rebound"
336
+ """The body assigns to the state parameter's own name, so a later ``state["k"]`` is a
337
+ read of something else. Pattern (b) is dropped rather than attributed to the state."""
338
+
339
+ RETURN_NOT_LITERAL = "return-not-literal"
340
+ """§4's multi-return rule: a ``return`` site that is not a licensed literal. "If **any**
341
+ site is unlicensed (non-literal), output inference is abandoned wholesale"."""
342
+
343
+ COMMAND_UPDATE_NOT_LITERAL = "command-update-not-literal"
344
+ """A ``Command`` whose ``update=`` is not a literal dict display — the same abandonment
345
+ as an unlicensed return, for the same reason: a partial union would under-report."""
346
+
347
+ NO_LICENSED_PATTERN = "no-licensed-pattern"
348
+ """The body was read and nothing in the closed table matched."""
349
+
350
+ BODY_UNAVAILABLE = "body-unavailable"
351
+ """The node's own AST could not be read at all; :attr:`NodeSource.rule` says why."""
352
+
353
+ BODY_TOO_DEEP = "body-too-deep"
354
+ """The body parsed and then nested deeper than the walk could descend. Same outcome as an
355
+ unreadable body — the D-011 floor — rather than a :class:`RecursionError` out of an
356
+ extraction."""
357
+
358
+
359
+ @dataclass(frozen=True)
360
+ class StateSchema:
361
+ """The graph's own state schema — the second argument of §4's ``infer``.
362
+
363
+ Its one job here is §4's **full-state-annotation exclusion**: "when the state-parameter
364
+ (or return-type) annotation is the graph's full state schema itself, the annotation
365
+ carries no selective read/write information — the default LangGraph idiom
366
+ ``def node(state: State) -> State`` infers **nothing** from its annotations". So what the
367
+ engine needs is the identity of the objects that *are* the graph's schema, which is why
368
+ this holds objects and not keys.
369
+
370
+ It holds a *sequence* because a caller may have more than one object to name — a graph can
371
+ declare an input and an output schema beside its state schema. **Which** of them count as
372
+ "the graph's full state schema itself" is not decided here: §4 names one, this compares
373
+ against whatever it is handed, and the choice belongs to the card that reads the schemas
374
+ off a builder.
375
+
376
+ Comparison is ``is``: the exclusion asks whether the annotation is that schema, and a
377
+ schema class's own ``__eq__`` is not consulted.
378
+ """
379
+
380
+ schemas: tuple[object, ...] = ()
381
+
382
+ @classmethod
383
+ def of(cls, *schemas: object) -> StateSchema:
384
+ """The graph's schema objects, in declaration order."""
385
+ return cls(schemas=schemas)
386
+
387
+ def is_full_state(self, annotation: object) -> bool:
388
+ """Whether ``annotation`` is one of the graph's own schemas (the §4 exclusion)."""
389
+ return any(annotation is schema for schema in self.schemas)
390
+
391
+
392
+ @dataclass(frozen=True)
393
+ class InferredKey:
394
+ """One inferred state key with the §4 pattern that licensed it.
395
+
396
+ Attributes:
397
+ key: The state key, exactly as the source spells it.
398
+ pattern: The licensed pattern — §4 requires "one licensed-pattern citation per
399
+ emitted key", which is what makes an inferred slot explainable in one line.
400
+ """
401
+
402
+ key: str
403
+ pattern: Pattern
404
+
405
+
406
+ @dataclass(frozen=True)
407
+ class NodeSource:
408
+ """A node callable's own AST, or the reason there is none (§4's first argument).
409
+
410
+ Total: :func:`read_node_source` has no failure mode, because every way of not having a
411
+ body is a node that falls to the D-011 defaults rather than an extraction that stops.
412
+
413
+ Attributes:
414
+ rule: Whether the definition was read, and if not, why.
415
+ definition: The located ``def``/``async def``/``lambda`` node, or ``None``.
416
+ annotations: The callable's own ``__annotations__``, as the interpreter recorded them
417
+ at ``def`` time. Values are whatever was written — a class, a typing form, or a
418
+ ``str`` under ``from __future__ import annotations``, which §4's no-evaluation
419
+ rule leaves unresolved.
420
+ bound: Whether the callable is a bound method, whose first AST parameter is the
421
+ ``self``/``cls`` §4 says to look past.
422
+ detail: Where the reader got to — the file, the line, the code object's name — as
423
+ JSON data, so it can ride a warning's ``detail``.
424
+ """
425
+
426
+ rule: SourceRule
427
+ definition: ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda | None = None
428
+ annotations: Mapping[str, object] = field(default_factory=dict)
429
+ bound: bool = False
430
+ detail: Mapping[str, Any] = field(default_factory=dict)
431
+
432
+ @property
433
+ def read(self) -> bool:
434
+ """Whether there is a body to apply the patterns to."""
435
+ return self.definition is not None
436
+
437
+
438
+ @dataclass(frozen=True)
439
+ class InferenceFinding:
440
+ """One §4 outcome for one node, in the shape the §4 warning registry asks for.
441
+
442
+ A neutral record rather than an :class:`~gebra.extraction.warnings.ExtractionWarning`
443
+ because this package must not import :mod:`gebra.extraction` — that package reads the
444
+ substrate's classes, and the dependency between the two runs one way only.
445
+ :mod:`gebra.extraction.inference` is what turns these into ``contract-inferred`` /
446
+ ``contract-defaulted`` records; the fields here are already the fields §4 names, so that
447
+ conversion adds a code and the node id and nothing else.
448
+
449
+ Attributes:
450
+ grade: :attr:`SlotGrade.INFERRED` for a pattern match, :attr:`SlotGrade.DEFAULTED` for
451
+ a D-011 default — §5's two heuristic grades, which are also the two warning codes.
452
+ slots: The slots this finding accounts for. Never empty: both registry rows are read
453
+ through §5's (node id, slot) lookup, so a finding that named no slot would be a
454
+ warning no validator could act on.
455
+ message: A one-line human summary. Display-only, like every warning message in this
456
+ build: the facts are the fields.
457
+ detail: The rest of the row's "carries" column as JSON data.
458
+
459
+ Raises:
460
+ ValueError: if built with :attr:`SlotGrade.DECLARED` (which is the absence of a
461
+ finding, never one of them) or with no slots.
462
+ """
463
+
464
+ grade: SlotGrade
465
+ slots: tuple[AnnotationSlot, ...]
466
+ message: str
467
+ detail: Mapping[str, Any] = field(default_factory=dict)
468
+
469
+ def __post_init__(self) -> None:
470
+ if self.grade not in HEURISTIC_GRADES:
471
+ raise ValueError(
472
+ f"{self.grade.value!r} is not one of the two grades §4 produces "
473
+ f"({', '.join(grade.value for grade in HEURISTIC_GRADES)}); declared-grade is "
474
+ "what the absence of a finding means (ANNOTATION-API-SPEC §5)"
475
+ )
476
+ if not self.slots:
477
+ raise ValueError(
478
+ "an inference finding names the slot(s) it accounts for: §5's grade lookup is "
479
+ "keyed by the (node id, slot) pair"
480
+ )
481
+
482
+
483
+ @dataclass(frozen=True)
484
+ class Inference:
485
+ """What §4 contributes for one node — the tier's whole output.
486
+
487
+ Attributes:
488
+ contract: The contribution, in the same carrier the decorator (§1) and the sidecar
489
+ (§2) produce, so §3's chain compares three tiers of one type. At most the four
490
+ slots of :data:`INFERENCE_SLOTS` are set, and a slot the higher tiers already
491
+ filled is never among them.
492
+ keys: The per-key citations (§4) for whichever of ``input``/``output`` were inferred.
493
+ default: Which D-011 default applied, or ``None`` when the pair was already declared.
494
+ blockers: Why the patterns that did not match did not match, in a stable order.
495
+ source: Where the body came from, or why there was none.
496
+ findings: The ``contract-inferred`` / ``contract-defaulted`` records — one per grade
497
+ that occurred, covering every slot in :attr:`contract`.
498
+ """
499
+
500
+ contract: NodeContract
501
+ source: NodeSource
502
+ keys: Mapping[AnnotationSlot, tuple[InferredKey, ...]] = field(default_factory=dict)
503
+ default: DefaultRule | None = None
504
+ blockers: tuple[Blocker, ...] = ()
505
+ findings: tuple[InferenceFinding, ...] = ()
506
+
507
+ def inferred_slots(self) -> tuple[AnnotationSlot, ...]:
508
+ """The slots this inference filled, in :data:`ANNOTATION_SLOTS` order."""
509
+ return self.contract.declared_slots()
510
+
511
+
512
+ class SourceCache:
513
+ """Parsed defining modules for one extraction — an explicit, caller-owned cache.
514
+
515
+ §4 bounds *inference* at "O(|node-body AST|) per node"; parsing the module a node is
516
+ defined in is the I/O around that, and a graph's nodes usually share a handful of files.
517
+ A caller that infers over many nodes passes one of these; a caller that does not gets
518
+ correctness with no shared state, which is why there is no module-level default.
519
+
520
+ The key is the file's path together with its size and modification time, so a file that
521
+ changes mid-extraction is re-read rather than served stale.
522
+ """
523
+
524
+ def __init__(self) -> None:
525
+ self._modules: dict[tuple[str, int, int], tuple[ast.Module | None, SourceRule]] = {}
526
+
527
+ def get(self, key: tuple[str, int, int]) -> tuple[ast.Module | None, SourceRule] | None:
528
+ """The cached parse for ``key``, or ``None``."""
529
+ return self._modules.get(key)
530
+
531
+ def remember(
532
+ self, key: tuple[str, int, int], parsed: tuple[ast.Module | None, SourceRule]
533
+ ) -> None:
534
+ """Cache ``parsed`` under ``key``, starting over past :data:`_MAX_CACHED_MODULES`."""
535
+ if len(self._modules) >= _MAX_CACHED_MODULES:
536
+ self._modules.clear()
537
+ self._modules[key] = parsed
538
+
539
+ def __len__(self) -> int:
540
+ """How many parses are held."""
541
+ return len(self._modules)
542
+
543
+
544
+ # ── Reading the node's own source ────────────────────────────────────────────────────────
545
+
546
+
547
+ def read_node_source(node: object, *, cache: SourceCache | None = None) -> NodeSource:
548
+ """The AST of ``node``'s own definition, or the reason there is none. Never raises.
549
+
550
+ The route is deliberate, and is the WA-07 half of this module (see the module docstring):
551
+ the code object names its file and its first line, the file is read as bytes and parsed,
552
+ and the definition is located by name and line. :func:`inspect.getsource` is not used —
553
+ it can reach a module's own ``__loader__.get_source()`` through :mod:`linecache` and
554
+ sweeps ``sys.modules`` through :func:`inspect.getmodule`, and both are user code running
555
+ inside what is supposed to be a read.
556
+
557
+ Args:
558
+ node: The node callable. A plain function, an ``async def``, a ``lambda`` or a bound
559
+ method is read; anything else is :attr:`SourceRule.NOT_A_PYTHON_FUNCTION`.
560
+ cache: An optional per-extraction :class:`SourceCache`.
561
+
562
+ Returns:
563
+ A :class:`NodeSource`, whose :attr:`~NodeSource.rule` is the whole answer.
564
+ """
565
+ function, bound = _python_function(node)
566
+ if function is None:
567
+ return NodeSource(
568
+ rule=SourceRule.NOT_A_PYTHON_FUNCTION,
569
+ detail={"target": type_identity(node)},
570
+ )
571
+ code = function.__code__
572
+ where: dict[str, Any] = {
573
+ "file": code.co_filename,
574
+ "line": code.co_firstlineno,
575
+ "name": code.co_name,
576
+ }
577
+ tree, rule = _module_ast(code.co_filename, cache)
578
+ if tree is None:
579
+ return NodeSource(rule=rule, detail=where)
580
+ definition, located = _locate(tree, code)
581
+ if definition is None:
582
+ return NodeSource(rule=located, detail=where)
583
+ return NodeSource(
584
+ rule=SourceRule.READ,
585
+ definition=definition,
586
+ annotations=_declared_annotations(function),
587
+ bound=bound,
588
+ detail=where,
589
+ )
590
+
591
+
592
+ def _python_function(node: object) -> tuple[types.FunctionType | None, bool]:
593
+ """``node`` as a Python function, and whether it arrived bound.
594
+
595
+ §4: the state parameter is the first positional parameter "after ``self``/``cls`` for
596
+ bound methods and classmethods" — and a bound classmethod is a bound method too, so one
597
+ unwrap covers both. Nothing else is followed: a ``functools.partial``, a callable object
598
+ or a ``Runnable`` is a wrapper, and walking wrappers is §6's rule, applied by the
599
+ resolution card before it asks for inference.
600
+
601
+ The test is ``type(node) is``, not ``isinstance``. Neither type can be subclassed, so the
602
+ two admit exactly the same objects — except that ``isinstance`` falls back to reading
603
+ ``node.__class__``, which is a property an object can answer however it likes. Everything
604
+ below this line reads ``__code__`` and ``__annotations__`` off the result, so an object
605
+ that talks its way past this check has its own descriptors run inside a path whose whole
606
+ claim is that it runs nothing of the caller's (WA-07).
607
+ """
608
+ if type(node) is types.MethodType:
609
+ underlying = node.__func__
610
+ if type(underlying) is types.FunctionType:
611
+ return underlying, True
612
+ return None, False
613
+ if type(node) is types.FunctionType:
614
+ return node, False
615
+ return None, False
616
+
617
+
618
+ def _declared_annotations(function: types.FunctionType) -> Mapping[str, object]:
619
+ """The function's own ``__annotations__``, copied, with nothing resolved.
620
+
621
+ The interpreter evaluated these at ``def`` time; reading them evaluates nothing. Under
622
+ ``from __future__ import annotations`` they are strings, and they stay strings —
623
+ :func:`typing.get_type_hints` would ``eval`` them, which §4 forbids.
624
+
625
+ Copied through the unbound ``dict`` accessor rather than with ``dict(mapping)``: the
626
+ ``__annotations__`` descriptor accepts any ``dict`` **subclass**, and ``dict(mapping)`` on
627
+ one takes the generic path through its own ``keys``/``__getitem__`` — a subclass's code
628
+ running inside a read. The pattern is :mod:`gebra.annotations.contract`'s, for its reason.
629
+ """
630
+ return MappingProxyType(dict(dict.items(function.__annotations__)))
631
+
632
+
633
+ def _module_ast(filename: str, cache: SourceCache | None) -> tuple[ast.Module | None, SourceRule]:
634
+ """Parse the file ``filename``, through ``cache`` when one was given.
635
+
636
+ A relative ``co_filename`` is resolved against the current working directory and no
637
+ further: :mod:`linecache` searches ``sys.path`` for a matching basename, and reading a
638
+ *different* file with the same name would infer a contract from source the node does not
639
+ have. Not found is :attr:`SourceRule.SOURCE_UNAVAILABLE`, which is the D-011 floor.
640
+ """
641
+ if not filename or filename.startswith("<"):
642
+ # `<stdin>`, `<string>`, `<ipython-input-…>`: compiled from something that is not a
643
+ # file, so there is nothing to read (the same test `inspect` makes).
644
+ return None, SourceRule.SOURCE_UNAVAILABLE
645
+ try:
646
+ path = Path(filename)
647
+ if not path.is_file():
648
+ # `is_file()` and not `exists()`: a FIFO would block the read forever and a
649
+ # character device would never end it, which is the hazard the sidecar loader's
650
+ # explicit-path gate exists for as well.
651
+ return None, SourceRule.SOURCE_UNAVAILABLE
652
+ stat = path.stat()
653
+ if stat.st_size > _MAX_SOURCE_BYTES:
654
+ return None, SourceRule.SOURCE_UNAVAILABLE
655
+ key = (filename, stat.st_size, stat.st_mtime_ns)
656
+ cached = None if cache is None else cache.get(key)
657
+ if cached is not None:
658
+ return cached
659
+ source = path.read_bytes()
660
+ except (OSError, ValueError):
661
+ # `ValueError` is not a slip: a path the operating system cannot express — an embedded
662
+ # NUL — raises it rather than `OSError`.
663
+ return None, SourceRule.SOURCE_UNAVAILABLE
664
+ parsed = _parse(source, filename)
665
+ if cache is not None:
666
+ cache.remember(key, parsed)
667
+ return parsed
668
+
669
+
670
+ def _parse(source: bytes, filename: str) -> tuple[ast.Module | None, SourceRule]:
671
+ """``source`` as a module AST, or why it is not one.
672
+
673
+ Parsed from **bytes** so that the file's own PEP 263 encoding declaration decides how it
674
+ is decoded, exactly as the interpreter decided when it imported the module.
675
+ """
676
+ try:
677
+ return ast.parse(source, filename=filename), SourceRule.READ
678
+ except (SyntaxError, ValueError, RecursionError, MemoryError):
679
+ # A file that is not the Python the code object came from — edited since import,
680
+ # binary, or nested past what the parser's stack admits. All four are "no body".
681
+ return None, SourceRule.SOURCE_UNPARSABLE
682
+
683
+
684
+ #: The AST kinds a node callable can be defined by.
685
+ _Definition: TypeAlias = "ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda"
686
+
687
+
688
+ def _locate(tree: ast.Module, code: types.CodeType) -> tuple[_Definition | None, SourceRule]:
689
+ """The definition in ``tree`` that ``code`` came from, matched by name and line.
690
+
691
+ A decorated function's ``co_firstlineno`` is the line of its **first decorator**, while
692
+ the AST node's own ``lineno`` is the ``def`` — so both are candidate lines. When more than
693
+ one definition still matches (two ``lambda``\\ s on one line), the code object's declared
694
+ positional parameters break the tie; when they do not, the answer is
695
+ :attr:`SourceRule.DEFINITION_AMBIGUOUS` rather than a guess.
696
+ """
697
+ candidates = [
698
+ node
699
+ for node in ast.walk(tree)
700
+ if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda))
701
+ and _definition_name(node) == code.co_name
702
+ and code.co_firstlineno in _definition_lines(node)
703
+ ]
704
+ if len(candidates) > 1:
705
+ wanted = code.co_varnames[: code.co_argcount]
706
+ candidates = [node for node in candidates if _positional_names(node) == wanted]
707
+ if not candidates:
708
+ return None, SourceRule.DEFINITION_NOT_FOUND
709
+ if len(candidates) > 1:
710
+ return None, SourceRule.DEFINITION_AMBIGUOUS
711
+ return candidates[0], SourceRule.READ
712
+
713
+
714
+ def _definition_name(node: _Definition) -> str:
715
+ """The name a code object would carry for ``node``."""
716
+ return "<lambda>" if isinstance(node, ast.Lambda) else node.name
717
+
718
+
719
+ def _definition_lines(node: _Definition) -> frozenset[int]:
720
+ """The lines a code object's ``co_firstlineno`` may point at for ``node``."""
721
+ if isinstance(node, ast.Lambda):
722
+ return frozenset({node.lineno})
723
+ return frozenset({node.lineno, *(decorator.lineno for decorator in node.decorator_list)})
724
+
725
+
726
+ def _positional_names(node: _Definition) -> tuple[str, ...]:
727
+ """``node``'s positional parameters, in the order a code object lists them."""
728
+ arguments = node.args
729
+ return tuple(argument.arg for argument in (*arguments.posonlyargs, *arguments.args))
730
+
731
+
732
+ # ── The pattern engine ───────────────────────────────────────────────────────────────────
733
+
734
+
735
+ def infer_node(
736
+ node: object,
737
+ *,
738
+ state_schema: StateSchema | None = None,
739
+ declared: Iterable[AnnotationSlot] = (),
740
+ declared_writes: bool = False,
741
+ opaque: bool = False,
742
+ cache: SourceCache | None = None,
743
+ ) -> Inference:
744
+ """Read ``node``'s own source and apply §4 to it — :func:`read_node_source` then
745
+ :func:`infer`.
746
+
747
+ Args:
748
+ node: The node callable.
749
+ state_schema: The graph's state schema, for the §4 full-state exclusion.
750
+ declared: The slots the higher §3 tiers already filled.
751
+ declared_writes: Whether a higher tier declared a non-empty ``output`` — see
752
+ :func:`infer`.
753
+ opaque: Whether the node is one §4 sends "straight to defaults" without looking —
754
+ a ``RunnableLambda`` body. Set by the caller, which is the layer that knows what
755
+ kind of runnable the node is.
756
+ cache: An optional per-extraction :class:`SourceCache`.
757
+ """
758
+ source = NodeSource(rule=SourceRule.OPAQUE) if opaque else read_node_source(node, cache=cache)
759
+ return infer(
760
+ source,
761
+ state_schema=state_schema,
762
+ declared=declared,
763
+ declared_writes=declared_writes,
764
+ )
765
+
766
+
767
+ def infer(
768
+ source: NodeSource,
769
+ *,
770
+ state_schema: StateSchema | None = None,
771
+ declared: Iterable[AnnotationSlot] = (),
772
+ declared_writes: bool = False,
773
+ ) -> Inference:
774
+ """§4's ``infer(node_ast, state_schema)`` — the closed pattern table, one pass.
775
+
776
+ Pure and per-node: it reads the given AST and the given schema and nothing else, follows
777
+ no import, and evaluates nothing.
778
+
779
+ Args:
780
+ source: The node's own AST, from :func:`read_node_source`.
781
+ state_schema: The graph's state schema. ``None`` means it is not known, which
782
+ withdraws the two *annotation* patterns — §4's full-state exclusion cannot be
783
+ applied without it, and applying pattern (a) blind is the case it excludes.
784
+ declared: The slots §3's higher tiers already filled. Inference "fills what remains",
785
+ so a slot named here gets neither a value nor a warning: a ``contract-inferred``
786
+ record naming a declared slot would make §5's grade lookup call it
787
+ heuristic-grade.
788
+ declared_writes: Whether a higher §3 tier declared a non-empty ``output`` — i.e.
789
+ whether an author has said this node writes state. It is write evidence for the
790
+ D-011 default and nothing else: §4's two defaults are stated for "an
791
+ **unannotated** node", and a node whose author declared its writes is not one.
792
+ Without it, ``@gebra.contract(reads=[…], writes=["plan"])`` on a body whose writes
793
+ happen inside a helper would resolve to ``output: ["plan"]`` *and* ``pure: true``
794
+ — the gap-filling tier contradicting the declaration it was filling around, in the
795
+ one direction D-011's "provably read-only" rules out.
796
+
797
+ Returns:
798
+ The tier's contribution and the findings that account for every slot in it.
799
+ """
800
+ open_slots = frozenset(INFERENCE_SLOTS) - frozenset(declared)
801
+ blockers: list[Blocker] = []
802
+ keys: dict[AnnotationSlot, tuple[InferredKey, ...]] = {}
803
+ annotated_output: tuple[str, ...] = ()
804
+
805
+ walk, unread = _walk(source)
806
+ if walk is None:
807
+ blockers.append(unread)
808
+ else:
809
+ if walk.parameter is None:
810
+ blockers.append(Blocker.NO_STATE_PARAMETER)
811
+ if "input" in open_slots:
812
+ inferred = _input_keys(source, walk, state_schema, blockers)
813
+ if inferred:
814
+ keys["input"] = inferred
815
+ # Asked of the node, not of the open slots: §4's D-011 precondition is "no licensed
816
+ # output pattern **matches**", so whether the return annotation matched is a fact
817
+ # about the node — and it is still true when the multi-return rule abandons the key
818
+ # set it would have contributed, and when a higher tier already filled `output`.
819
+ annotated_output = _annotation_keys(
820
+ source.annotations.get("return", _UNANNOTATED),
821
+ state_schema,
822
+ blockers,
823
+ licensed=_TYPED_DICT_ONLY,
824
+ )
825
+ if "output" in open_slots:
826
+ inferred = _output_keys(annotated_output, walk)
827
+ if inferred:
828
+ keys["output"] = inferred
829
+ blockers.extend(blocker for blocker in walk.blockers if blocker not in blockers)
830
+ # Only when a pattern was actually tried: with both slots already declared, nothing
831
+ # was looked for, and "no licensed pattern" would be a report about work not done.
832
+ if not keys and {"input", "output"} & open_slots:
833
+ blockers.append(Blocker.NO_LICENSED_PATTERN)
834
+
835
+ default = _default_rule(
836
+ walk,
837
+ open_slots,
838
+ matched_output=bool(annotated_output) or declared_writes,
839
+ )
840
+ return Inference(
841
+ contract=_contribution(keys, default),
842
+ source=source,
843
+ keys=MappingProxyType(dict(keys)),
844
+ default=default,
845
+ blockers=tuple(blockers),
846
+ findings=_findings(keys, default, source, tuple(blockers)),
847
+ )
848
+
849
+
850
+ def _contribution(
851
+ keys: Mapping[AnnotationSlot, tuple[InferredKey, ...]], default: DefaultRule | None
852
+ ) -> NodeContract:
853
+ """The four slots §4 can fill, and the only place any of them is set.
854
+
855
+ This is the NEVER-SILENT-UPGRADE rule as code rather than as a check: the constructor
856
+ call names ``input``, ``output``, ``effect`` and ``pure`` literally, so no reachable path
857
+ sets ``idempotent``, ``deterministic``, ``variant``, ``compensation`` or ``args_schema``.
858
+
859
+ An empty key set leaves its slot **unset** rather than setting it to ``[]``. An
860
+ ``output: []`` is a positive claim ("writes nothing") that no pattern made — and IR-SPEC
861
+ §6.3 omits empty optional arrays from the canonical form, so the claim would be invisible
862
+ in ``graph_version`` while still blocking the D-011 floor at §3's chain.
863
+ """
864
+ return NodeContract(
865
+ input=tuple(inferred.key for inferred in keys.get("input", ())) or None,
866
+ output=tuple(inferred.key for inferred in keys.get("output", ())) or None,
867
+ effect=DEFAULT_EFFECT if default in _EFFECT_DEFAULTS else None,
868
+ pure=True if default is DefaultRule.NO_WRITE_EVIDENCE else None,
869
+ )
870
+
871
+
872
+ def _default_rule(
873
+ walk: _Walk | None, open_slots: frozenset[AnnotationSlot], *, matched_output: bool
874
+ ) -> DefaultRule | None:
875
+ """Which D-011 default applies (§4), or ``None``.
876
+
877
+ §4's second bullet is a two-part test over the **patterns**, not over the body alone: a
878
+ node takes the ``pure`` branch when "no licensed output pattern matches **and** no
879
+ assignment/mutation of the state parameter appears in the node body". So a matched output
880
+ pattern is evidence whichever of the three matched — including pattern (b), the return
881
+ annotation, whose keys the multi-return rule may have abandoned. A node whose own return
882
+ annotation declares what it writes is further from "provably read-only" than one this
883
+ module could not read at all. ``matched_output`` also carries :func:`infer`'s
884
+ ``declared_writes``, for the same reason one step up: an author's declared ``output`` is
885
+ the strongest write evidence there is, and §4's defaults are written for "an
886
+ **unannotated** node".
887
+
888
+ The pair is decided together. §4 speaks of "an **unannotated** node", and ``pure`` and
889
+ ``effect`` are one statement about a node made in two slots — D-011 declares them mutually
890
+ exclusive — so filling one while the other is declared would assemble exactly the
891
+ cross-surface contradiction §3's resolved-contract pass exists to repair. With either half
892
+ declared, the tier stays out.
893
+ """
894
+ if not {"pure", "effect"} <= open_slots:
895
+ return None
896
+ if walk is None:
897
+ return DefaultRule.BODY_UNAVAILABLE
898
+ if walk.write_evidence or matched_output:
899
+ return DefaultRule.WRITES_STATE
900
+ return DefaultRule.NO_WRITE_EVIDENCE
901
+
902
+
903
+ def _walk(source: NodeSource) -> tuple[_Walk | None, Blocker]:
904
+ """Walk the node's body once, or say why there is no walk to read.
905
+
906
+ Total: a body deep enough to exhaust the interpreter's stack is a body this module could
907
+ not read, which is the D-011 floor — not an exception out of an extraction. The parse
908
+ itself is guarded in :func:`_parse`; this is the second half, because
909
+ :class:`ast.NodeVisitor` descends recursively while :func:`ast.walk` does not.
910
+ """
911
+ definition = source.definition
912
+ if definition is None:
913
+ return None, Blocker.BODY_UNAVAILABLE
914
+ walk = _Walk(parameter=_state_parameter(definition, bound=source.bound))
915
+ try:
916
+ walk.run(definition)
917
+ except RecursionError:
918
+ return None, Blocker.BODY_TOO_DEEP
919
+ return walk, Blocker.BODY_UNAVAILABLE
920
+
921
+
922
+ def _state_parameter(definition: _Definition, *, bound: bool) -> str | None:
923
+ """§4's state parameter: "the **first positional parameter** of the node callable — after
924
+ ``self``/``cls`` for bound methods and classmethods"."""
925
+ positional = _positional_names(definition)
926
+ if bound:
927
+ positional = positional[1:]
928
+ return positional[0] if positional else None
929
+
930
+
931
+ def _input_keys(
932
+ source: NodeSource,
933
+ walk: _Walk,
934
+ state_schema: StateSchema | None,
935
+ blockers: list[Blocker],
936
+ ) -> tuple[InferredKey, ...]:
937
+ """§4's two ``input`` patterns, annotation first so its citation wins a shared key."""
938
+ inferred: dict[str, InferredKey] = {}
939
+ if walk.parameter is not None:
940
+ annotated = _annotation_keys(
941
+ source.annotations.get(walk.parameter, _UNANNOTATED),
942
+ state_schema,
943
+ blockers,
944
+ licensed=_TYPED_DICT_OR_PYDANTIC,
945
+ )
946
+ for key in annotated:
947
+ inferred.setdefault(key, InferredKey(key=key, pattern=Pattern.STATE_ANNOTATION_KEYS))
948
+ if walk.rebound:
949
+ blockers.append(Blocker.STATE_PARAMETER_REBOUND)
950
+ else:
951
+ for key, pattern in walk.reads.items():
952
+ inferred.setdefault(key, InferredKey(key=key, pattern=pattern))
953
+ return tuple(inferred.values())
954
+
955
+
956
+ def _output_keys(annotated: tuple[str, ...], walk: _Walk) -> tuple[InferredKey, ...]:
957
+ """§4's three ``output`` patterns under the multi-return rule.
958
+
959
+ "If **every** site matches a licensed output pattern, ``output`` is the union of their
960
+ keys; if **any** site is unlicensed (non-literal), output inference is abandoned wholesale
961
+ and the node falls to the defaults — a partial union would under-report writes." Wholesale
962
+ is read as written: the return **annotation** goes with the literals, because a node whose
963
+ writes are partly invisible is a node whose output set is not known, whichever pattern
964
+ would have supplied part of it. That the annotation still *matched* is a separate fact, and
965
+ it is the one the D-011 branch turns on (:func:`_default_rule`).
966
+ """
967
+ if walk.unlicensed_output:
968
+ return ()
969
+ inferred: dict[str, InferredKey] = {}
970
+ for key in annotated:
971
+ inferred.setdefault(key, InferredKey(key=key, pattern=Pattern.RETURN_ANNOTATION_KEYS))
972
+ for key, pattern in walk.writes.items():
973
+ inferred.setdefault(key, InferredKey(key=key, pattern=pattern))
974
+ return tuple(inferred.values())
975
+
976
+
977
+ #: What "this name has no annotation" looks like, distinct from an annotation of ``None``.
978
+ _UNANNOTATED: Final = object()
979
+
980
+
981
+ #: The projection spellings §4's ``input`` row licenses: "a ``TypedDict``/pydantic projection".
982
+ _TYPED_DICT_OR_PYDANTIC: Final = True
983
+
984
+ #: The one §4's ``output`` row licenses: "a ``TypedDict`` return-type annotation — its keys".
985
+ #: The asymmetry is the spec's, stated in its table and restated in DEC-08's decision, and the
986
+ #: table is closed — "anything not on it is not inferred". A pydantic return annotation is
987
+ #: therefore :attr:`Blocker.NOT_A_TYPED_DICT`, not a projection to read: its field names would
988
+ #: otherwise land in ``output``, inside the ``graph_version`` hash scope, claiming writes no
989
+ #: pattern licenses.
990
+ _TYPED_DICT_ONLY: Final = False
991
+
992
+
993
+ def _annotation_keys(
994
+ annotation: object,
995
+ state_schema: StateSchema | None,
996
+ blockers: list[Blocker],
997
+ *,
998
+ licensed: bool,
999
+ ) -> tuple[str, ...]:
1000
+ """The declared keys of a projection annotation (§4 patterns input (a) / output (b)).
1001
+
1002
+ Every way of not matching is recorded, because "why no pattern applied" is a field of the
1003
+ ``contract-defaulted`` row and each of these has a different repair.
1004
+
1005
+ Args:
1006
+ annotation: The annotation object, exactly as the interpreter recorded it.
1007
+ state_schema: The graph's schema, for the full-state exclusion.
1008
+ blockers: Collected reasons, appended to.
1009
+ licensed: :data:`_TYPED_DICT_OR_PYDANTIC` on the state parameter,
1010
+ :data:`_TYPED_DICT_ONLY` on the return — §4's table is asymmetric.
1011
+ """
1012
+ if annotation is _UNANNOTATED:
1013
+ blockers.append(Blocker.NO_ANNOTATION)
1014
+ return ()
1015
+ if isinstance(annotation, str):
1016
+ # `from __future__ import annotations`, or an explicit forward reference. Resolving it
1017
+ # is evaluation, which §4 rules out; `typing.get_type_hints` is never called here.
1018
+ blockers.append(Blocker.STRING_ANNOTATION)
1019
+ return ()
1020
+ if state_schema is None:
1021
+ blockers.append(Blocker.STATE_SCHEMA_UNKNOWN)
1022
+ return ()
1023
+ if state_schema.is_full_state(annotation):
1024
+ blockers.append(Blocker.FULL_STATE_ANNOTATION)
1025
+ return ()
1026
+ keys, blocker = _projection_keys(annotation, pydantic=licensed)
1027
+ if keys is None:
1028
+ blockers.append(blocker)
1029
+ return ()
1030
+ return keys
1031
+
1032
+
1033
+ def _projection_keys(
1034
+ annotation: object, *, pydantic: bool
1035
+ ) -> tuple[tuple[str, ...] | None, Blocker]:
1036
+ """``annotation``'s declared keys if it is a projection §4 licenses here, else why not.
1037
+
1038
+ A ``dataclass``, an ``Annotated[...]`` form or a bare ``dict`` is not a projection at all;
1039
+ a pydantic model is one, and is licensed on the state parameter but **not** on the return
1040
+ (see :data:`_TYPED_DICT_ONLY`).
1041
+ """
1042
+ if isinstance(annotation, types.GenericAlias) or not isinstance(annotation, type):
1043
+ # The `GenericAlias` half is checked *first* and is not redundant. `dict[str, Any]` is
1044
+ # the ordinary annotation on a LangGraph node and declares no keys, and a parameterized
1045
+ # generic forwards attribute lookups it does not answer itself — ``__class__`` among
1046
+ # them on the older interpreters in the supported range — to its **origin**. That is
1047
+ # what lets `isinstance(dict[str, Any], type)` answer `True` while `issubclass` on the
1048
+ # same object raises `TypeError`. Excluding it by its own type is the answer that does
1049
+ # not depend on which interpreter is running.
1050
+ return None, Blocker.NOT_A_PROJECTION
1051
+ if issubclass(annotation, BaseModel):
1052
+ if not pydantic:
1053
+ return None, Blocker.NOT_A_TYPED_DICT
1054
+ try:
1055
+ return tuple(annotation.model_fields), Blocker.NOT_A_PROJECTION
1056
+ except Exception: # noqa: BLE001 - see below
1057
+ # A model's field names come from the model, and asking is the only way to get
1058
+ # them: `model_fields` is a metaclass property, so a class can answer it however
1059
+ # it likes. Inference is the tier that guesses, so a class that will not say what
1060
+ # it declares is "no projection here" and the node takes the D-011 floor —
1061
+ # aborting an extraction over a heuristic read would be the "total in name only"
1062
+ # failure this posture exists to prevent.
1063
+ return None, Blocker.PROJECTION_UNREADABLE
1064
+ if not _is_typed_dict(annotation):
1065
+ return None, Blocker.NOT_A_PROJECTION
1066
+ namespace = getattr(annotation, "__dict__", None)
1067
+ if not isinstance(namespace, MappingProxyType): # pragma: no cover - every class has one
1068
+ return None, Blocker.NOT_A_PROJECTION
1069
+ declared = MappingProxyType.get(namespace, "__annotations__")
1070
+ if not isinstance(declared, dict): # pragma: no cover - a TypedDict always carries one
1071
+ return (), Blocker.NOT_A_PROJECTION
1072
+ return tuple(key for key in dict.keys(declared) if isinstance(key, str)), (
1073
+ Blocker.NOT_A_PROJECTION
1074
+ )
1075
+
1076
+
1077
+ def _is_typed_dict(annotation: type) -> bool:
1078
+ """Whether ``annotation`` is a ``TypedDict`` class, whichever module declared it.
1079
+
1080
+ Structural rather than ``typing.is_typeddict``: a ``TypedDict`` from
1081
+ ``typing_extensions`` — which is what a library supporting older Pythons writes, and what
1082
+ LangGraph's own examples import — is not an instance of the stdlib's private metaclass on
1083
+ every version. The three marks below are what every ``TypedDict`` class carries and no
1084
+ ordinary ``dict`` subclass does.
1085
+ """
1086
+ if not issubclass(annotation, dict):
1087
+ return False
1088
+ namespace = getattr(annotation, "__dict__", None)
1089
+ if not isinstance(namespace, MappingProxyType): # pragma: no cover - every class has one
1090
+ return False
1091
+ return all(
1092
+ MappingProxyType.get(namespace, mark) is not None
1093
+ for mark in ("__annotations__", "__required_keys__", "__optional_keys__")
1094
+ )
1095
+
1096
+
1097
+ # ── The body walk ────────────────────────────────────────────────────────────────────────
1098
+
1099
+
1100
+ class _Walk(ast.NodeVisitor):
1101
+ """One pass over a node body, collecting §4's body-derived evidence.
1102
+
1103
+ Scope is the node's **own** body: a nested ``def``/``lambda`` is not descended into, since
1104
+ DEC-08 rules out "helper-function dataflow … and closures" in terms. A class body *is*
1105
+ descended into — it runs where it is written — while its methods are nested definitions
1106
+ and are not.
1107
+ """
1108
+
1109
+ def __init__(self, parameter: str | None) -> None:
1110
+ self.parameter = parameter
1111
+ self.reads: dict[str, Pattern] = {}
1112
+ self.writes: dict[str, Pattern] = {}
1113
+ self.write_evidence = False
1114
+ self.unlicensed_output = False
1115
+ self.rebound = False
1116
+ self.return_sites = 0
1117
+ self.blockers: list[Blocker] = []
1118
+
1119
+ def run(self, definition: _Definition) -> None:
1120
+ """Walk ``definition``'s body — the statements, or a ``lambda``'s one expression."""
1121
+ if isinstance(definition, ast.Lambda):
1122
+ # §4: "A bare `lambda` used as a node has an expression body: pattern (b) applies
1123
+ # to subscript/attribute reads of its first parameter, and a dict-display body
1124
+ # counts as output pattern (a)." So the expression is the single return site.
1125
+ self._return(definition.body)
1126
+ self.visit(definition.body)
1127
+ return
1128
+ for statement in definition.body:
1129
+ self.visit(statement)
1130
+
1131
+ # ── Scope ────────────────────────────────────────────────────────────────────────────
1132
+
1133
+ def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
1134
+ """A nested definition is not this node's body (DEC-08: no helper dataflow, no
1135
+ closures), so it is not descended into and its ``return``\\ s are not return sites."""
1136
+
1137
+ def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
1138
+ """As :meth:`visit_FunctionDef`."""
1139
+
1140
+ def visit_Lambda(self, node: ast.Lambda) -> None:
1141
+ """As :meth:`visit_FunctionDef`."""
1142
+
1143
+ # ── Return sites ─────────────────────────────────────────────────────────────────────
1144
+
1145
+ def visit_Return(self, node: ast.Return) -> None:
1146
+ """A return site, plus whatever the returned expression itself reads."""
1147
+ self._return(node.value)
1148
+ self.generic_visit(node)
1149
+
1150
+ def _return(self, value: ast.expr | None) -> None:
1151
+ """Classify one return site under §4's ``output`` patterns and multi-return rule."""
1152
+ self.return_sites += 1
1153
+ if value is None or _is_none(value):
1154
+ # `return` / `return None` writes nothing and says so in the source. Licensed
1155
+ # with no keys: the multi-return rule's own gloss for unlicensed is
1156
+ # "(non-literal)", and a constant is a literal.
1157
+ return
1158
+ if isinstance(value, ast.Dict):
1159
+ self._update(_literal_dict(value), Pattern.RETURN_LITERAL, Blocker.RETURN_NOT_LITERAL)
1160
+ return
1161
+ if isinstance(value, ast.Call) and _is_command(value):
1162
+ # Licensed; its keys — or its refusal — are recorded by `visit_Call`, since §4
1163
+ # puts pattern (c) on the construction rather than on the return.
1164
+ return
1165
+ self._abandon_output(Blocker.RETURN_NOT_LITERAL)
1166
+
1167
+ def _update(self, update: _Update, pattern: Pattern, blocker: Blocker) -> None:
1168
+ """Apply one written-update reading — §4's two questions, asked separately.
1169
+
1170
+ *Is a write evident?* is the D-011 defaults' test, and *are the keys readable?* is the
1171
+ multi-return rule's. They come apart exactly where a display or a ``Command`` shows a
1172
+ state update whose full key set it does not spell — ``{**base, "plan": …}`` evidences a
1173
+ write to ``plan`` while hiding whatever ``base`` carries — so the update is counted as
1174
+ evidence and the key set is abandoned, which is the conservative answer to both.
1175
+ """
1176
+ if update.evident:
1177
+ self.write_evidence = True
1178
+ if not update.complete:
1179
+ self._abandon_output(blocker)
1180
+ return
1181
+ for key in update.keys:
1182
+ self.writes.setdefault(key, pattern)
1183
+
1184
+ def _abandon_output(self, blocker: Blocker) -> None:
1185
+ """§4's multi-return rule: one unlicensed site abandons ``output`` wholesale."""
1186
+ self.unlicensed_output = True
1187
+ if blocker not in self.blockers:
1188
+ self.blockers.append(blocker)
1189
+
1190
+ # ── Reads, writes and mutations ──────────────────────────────────────────────────────
1191
+
1192
+ def visit_Subscript(self, node: ast.Subscript) -> None:
1193
+ """``state["k"]`` — input pattern (b) when read, write evidence when assigned."""
1194
+ if isinstance(node.ctx, (ast.Store, ast.Del)):
1195
+ if self._rooted_at_state(node.value):
1196
+ self.write_evidence = True
1197
+ elif self._is_state(node.value):
1198
+ key = _literal_key(node)
1199
+ if key is not None:
1200
+ self.reads.setdefault(key, Pattern.STATE_ACCESS)
1201
+ self.generic_visit(node)
1202
+
1203
+ def visit_Attribute(self, node: ast.Attribute) -> None:
1204
+ """``state.k`` — input pattern (b) when read, write evidence when assigned.
1205
+
1206
+ A leading underscore is not read as a state key: ``state._cache`` and
1207
+ ``state.__class__`` are the object's own business, not the graph's state.
1208
+ """
1209
+ if isinstance(node.ctx, (ast.Store, ast.Del)):
1210
+ if self._rooted_at_state(node.value):
1211
+ self.write_evidence = True
1212
+ elif self._is_state(node.value) and not node.attr.startswith("_"):
1213
+ self.reads.setdefault(node.attr, Pattern.STATE_ACCESS)
1214
+ self.generic_visit(node)
1215
+
1216
+ def visit_AugAssign(self, node: ast.AugAssign) -> None:
1217
+ """``state["k"] += 1`` writes *and* reads, though the target's context says Store."""
1218
+ target = node.target
1219
+ if isinstance(target, ast.Subscript) and self._is_state(target.value):
1220
+ key = _literal_key(target)
1221
+ if key is not None:
1222
+ self.reads.setdefault(key, Pattern.STATE_ACCESS)
1223
+ elif (
1224
+ isinstance(target, ast.Attribute)
1225
+ and self._is_state(target.value)
1226
+ and not target.attr.startswith("_")
1227
+ ):
1228
+ self.reads.setdefault(target.attr, Pattern.STATE_ACCESS)
1229
+ self.generic_visit(node)
1230
+
1231
+ def visit_Name(self, node: ast.Name) -> None:
1232
+ """Assigning to the state parameter's own name retargets every later read."""
1233
+ if node.id == self.parameter and isinstance(node.ctx, (ast.Store, ast.Del)):
1234
+ self.rebound = True
1235
+
1236
+ def visit_Call(self, node: ast.Call) -> None:
1237
+ """``Command(update={...})`` (pattern (c)), and mutating calls on the state.
1238
+
1239
+ The callee of a method call is visited as an *object* and not as an attribute read:
1240
+ ``state.get("k")`` reads no state key called ``get``, and treating it as one would
1241
+ put a method name in the IR's ``input``.
1242
+ """
1243
+ if _is_command(node):
1244
+ self._command(node)
1245
+ function = node.func
1246
+ if isinstance(function, ast.Attribute):
1247
+ if function.attr in MUTATING_METHODS and self._rooted_at_state(function.value):
1248
+ self.write_evidence = True
1249
+ self.visit(function.value)
1250
+ else:
1251
+ self.visit(function)
1252
+ for argument in node.args:
1253
+ self.visit(argument)
1254
+ for keyword in node.keywords:
1255
+ self.visit(keyword.value)
1256
+
1257
+ def _command(self, node: ast.Call) -> None:
1258
+ """§4 output pattern (c): a literal ``Command(update={"k": ...})`` construction."""
1259
+ self._update(
1260
+ _command_update(node), Pattern.COMMAND_UPDATE, Blocker.COMMAND_UPDATE_NOT_LITERAL
1261
+ )
1262
+
1263
+ # ── The state parameter ──────────────────────────────────────────────────────────────
1264
+
1265
+ def _is_state(self, node: ast.expr) -> bool:
1266
+ """Whether ``node`` is the state parameter itself — §4's "direct … access"."""
1267
+ return (
1268
+ self.parameter is not None and isinstance(node, ast.Name) and node.id == self.parameter
1269
+ )
1270
+
1271
+ def _rooted_at_state(self, node: ast.expr) -> bool:
1272
+ """Whether ``node`` reaches the state parameter through subscripts and attributes.
1273
+
1274
+ Wider than :meth:`_is_state` on purpose, and only for write evidence:
1275
+ ``state["messages"].append(m)`` mutates the graph's state at one remove, while the key
1276
+ it *reads* is still only the direct one.
1277
+ """
1278
+ current = node
1279
+ while isinstance(current, (ast.Subscript, ast.Attribute)):
1280
+ current = current.value
1281
+ return self._is_state(current)
1282
+
1283
+
1284
+ # ── Literal readers ──────────────────────────────────────────────────────────────────────
1285
+
1286
+
1287
+ def _is_none(value: ast.expr) -> bool:
1288
+ """Whether ``value`` is the literal ``None``."""
1289
+ return isinstance(value, ast.Constant) and value.value is None
1290
+
1291
+
1292
+ def _literal_key(node: ast.Subscript) -> str | None:
1293
+ """The literal string key of ``state["k"]``, or ``None`` for a computed one."""
1294
+ index = node.slice
1295
+ if isinstance(index, ast.Constant) and isinstance(index.value, str):
1296
+ return index.value
1297
+ return None
1298
+
1299
+
1300
+ @dataclass(frozen=True)
1301
+ class _Update:
1302
+ """One written state update as the source shows it — §4's two questions, separately.
1303
+
1304
+ Attributes:
1305
+ keys: The literal string keys it spells.
1306
+ complete: Whether those are *all* its keys. ``False`` for ``{**other}`` and for a
1307
+ computed key — the two non-literal constructions §4 rules out by name.
1308
+ evident: Whether a state write is statically evident at all, which is the D-011
1309
+ defaults' question and not the multi-return rule's.
1310
+ """
1311
+
1312
+ keys: tuple[str, ...] = ()
1313
+ complete: bool = True
1314
+ evident: bool = False
1315
+
1316
+
1317
+ def _literal_dict(node: ast.Dict) -> _Update:
1318
+ """A dict display read as an update: its literal keys, and whether they are all of them."""
1319
+ keys: list[str] = []
1320
+ complete = True
1321
+ for key in node.keys:
1322
+ if key is None or not isinstance(key, ast.Constant) or not isinstance(key.value, str):
1323
+ complete = False
1324
+ continue
1325
+ keys.append(key.value)
1326
+ return _Update(keys=tuple(keys), complete=complete, evident=bool(keys))
1327
+
1328
+
1329
+ def _is_command(node: ast.Call) -> bool:
1330
+ """Whether ``node`` is written as a ``Command(...)`` construction.
1331
+
1332
+ By the name as written — ``Command(...)`` or ``types.Command(...)`` — because shallow
1333
+ analysis reads source, not bindings. §4 licenses the construction "in the node body"; what
1334
+ the name is bound to at run time is exactly the kind of question DEC-08 rules out.
1335
+ """
1336
+ function = node.func
1337
+ if isinstance(function, ast.Name):
1338
+ return function.id == _COMMAND
1339
+ return isinstance(function, ast.Attribute) and function.attr == _COMMAND
1340
+
1341
+
1342
+ def _command_update(node: ast.Call) -> _Update:
1343
+ """A ``Command`` construction's ``update=``, read the same way as a returned display.
1344
+
1345
+ Three outcomes, and the middle one is why :class:`_Update` has two flags. A ``Command``
1346
+ with **no** ``update=`` is a route that writes no state and says so, so it is complete,
1347
+ keyless and no evidence. A ``Command(update=<name>)`` **is** evidence of a write — the
1348
+ update is right there — whose keys are not readable, so the key set is abandoned. A
1349
+ ``Command(**built)`` shows neither: it may carry an update and may not, so the key set is
1350
+ abandoned and nothing is claimed about writing.
1351
+ """
1352
+ for keyword in node.keywords:
1353
+ if keyword.arg is None:
1354
+ return _Update(complete=False)
1355
+ if keyword.arg == "update":
1356
+ value = keyword.value
1357
+ if not isinstance(value, ast.Dict):
1358
+ return _Update(complete=False, evident=True)
1359
+ return _literal_dict(value)
1360
+ return _Update()
1361
+
1362
+
1363
+ # ── Findings ─────────────────────────────────────────────────────────────────────────────
1364
+
1365
+
1366
+ def _findings(
1367
+ keys: Mapping[AnnotationSlot, tuple[InferredKey, ...]],
1368
+ default: DefaultRule | None,
1369
+ source: NodeSource,
1370
+ blockers: tuple[Blocker, ...],
1371
+ ) -> tuple[InferenceFinding, ...]:
1372
+ """One record per grade that occurred — §4: "every inferred slot carries a warning".
1373
+
1374
+ Both rows are read through §5's (node id, slot) lookup, so the slots are the record's
1375
+ load-bearing field; the rest is the "what it carries" column of the §4 registry.
1376
+ """
1377
+ findings: list[InferenceFinding] = []
1378
+ if keys:
1379
+ slots = tuple(slot for slot in ANNOTATION_SLOTS if slot in keys)
1380
+ findings.append(
1381
+ InferenceFinding(
1382
+ grade=SlotGrade.INFERRED,
1383
+ slots=slots,
1384
+ message=(
1385
+ f"{' and '.join(slots)} inferred from the closed ANNOTATION-API-SPEC §4 "
1386
+ "patterns rather than declared; the claim is heuristic-grade and no other "
1387
+ "slot was upgraded"
1388
+ ),
1389
+ detail={
1390
+ "surface": "inference",
1391
+ "patterns": {
1392
+ slot: {inferred.key: inferred.pattern.value for inferred in inferred_keys}
1393
+ for slot, inferred_keys in keys.items()
1394
+ },
1395
+ "claims_not_upgraded": list(NEVER_INFERRED),
1396
+ "depth": "shallow-only (DEC-08)",
1397
+ },
1398
+ )
1399
+ )
1400
+ if default is not None:
1401
+ applied: dict[str, Any] = (
1402
+ {"pure": True}
1403
+ if default is DefaultRule.NO_WRITE_EVIDENCE
1404
+ else {"effect": list(DEFAULT_EFFECT)}
1405
+ )
1406
+ slot: AnnotationSlot = "pure" if default is DefaultRule.NO_WRITE_EVIDENCE else "effect"
1407
+ findings.append(
1408
+ InferenceFinding(
1409
+ grade=SlotGrade.DEFAULTED,
1410
+ slots=(slot,),
1411
+ message=(
1412
+ f"no ANNOTATION-API-SPEC §4 pattern set {slot!r}, so the decision D-011 "
1413
+ f"conservative default applied ({default.value}); declare the contract with "
1414
+ "@gebra.contract or a gebra.toml entry to replace it"
1415
+ ),
1416
+ detail={
1417
+ "surface": "inference",
1418
+ "rule": default.value,
1419
+ "applied": applied,
1420
+ "why": [blocker.value for blocker in blockers],
1421
+ "source": source.rule.value,
1422
+ "declaration_surfaces": ["decorator", "sidecar"],
1423
+ },
1424
+ )
1425
+ )
1426
+ return tuple(findings)