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.
- gebra/__init__.py +114 -0
- gebra/annotations/__init__.py +154 -0
- gebra/annotations/contract.py +1036 -0
- gebra/annotations/errors.py +93 -0
- gebra/annotations/inference.py +1426 -0
- gebra/annotations/resolve.py +676 -0
- gebra/annotations/sidecar.py +776 -0
- gebra/annotations/slots.py +105 -0
- gebra/audit/__init__.py +79 -0
- gebra/audit/export.py +332 -0
- gebra/audit/freshness.py +128 -0
- gebra/audit/models.py +258 -0
- gebra/cli/__init__.py +47 -0
- gebra/cli/__main__.py +8 -0
- gebra/cli/app.py +681 -0
- gebra/cli/common.py +148 -0
- gebra/cli/diff.py +556 -0
- gebra/cli/display.py +307 -0
- gebra/cli/history.py +353 -0
- gebra/cli/invocation.py +192 -0
- gebra/cli/render.py +126 -0
- gebra/cli/resolve.py +378 -0
- gebra/cli/snapshot.py +343 -0
- gebra/cli/verify.py +357 -0
- gebra/diff/__init__.py +118 -0
- gebra/diff/contracts.py +375 -0
- gebra/diff/graph.py +190 -0
- gebra/diff/models.py +338 -0
- gebra/diff/state.py +260 -0
- gebra/diff/topology.py +367 -0
- gebra/diff/workflow.py +220 -0
- gebra/display/__init__.py +26 -0
- gebra/display/mermaid.py +240 -0
- gebra/display/overlay.py +349 -0
- gebra/extraction/__init__.py +231 -0
- gebra/extraction/base.py +83 -0
- gebra/extraction/builder.py +1229 -0
- gebra/extraction/compat.py +392 -0
- gebra/extraction/compiled.py +1330 -0
- gebra/extraction/contracts.py +616 -0
- gebra/extraction/digests.py +813 -0
- gebra/extraction/dispatch.py +320 -0
- gebra/extraction/envelope.py +297 -0
- gebra/extraction/errors.py +127 -0
- gebra/extraction/inference.py +82 -0
- gebra/extraction/lcel.py +1192 -0
- gebra/extraction/routing.py +309 -0
- gebra/extraction/sidecar.py +104 -0
- gebra/extraction/state.py +693 -0
- gebra/extraction/stock.py +121 -0
- gebra/extraction/warnings.py +368 -0
- gebra/ir/__init__.py +181 -0
- gebra/ir/base.py +59 -0
- gebra/ir/canonical.py +791 -0
- gebra/ir/identity.py +590 -0
- gebra/ir/models.py +515 -0
- gebra/ir/serialization.py +617 -0
- gebra/lineage/__init__.py +72 -0
- gebra/lineage/document.py +138 -0
- gebra/lineage/engine.py +265 -0
- gebra/lineage/models.py +244 -0
- gebra/naming.py +84 -0
- gebra/py.typed +0 -0
- gebra/pytest_plugin.py +2279 -0
- gebra/report/__init__.py +164 -0
- gebra/report/anchors.py +300 -0
- gebra/report/evidence.py +373 -0
- gebra/report/findings.py +149 -0
- gebra/report/human.py +465 -0
- gebra/report/native.py +38 -0
- gebra/report/rules.py +293 -0
- gebra/report/sarif.py +257 -0
- gebra/report/suggestions.py +82 -0
- gebra/snapshot/__init__.py +72 -0
- gebra/snapshot/engine.py +524 -0
- gebra/snapshot/models.py +164 -0
- gebra/store/__init__.py +121 -0
- gebra/store/atomic.py +124 -0
- gebra/store/base.py +63 -0
- gebra/store/models.py +361 -0
- gebra/store/serialization.py +198 -0
- gebra/store/store.py +507 -0
- gebra/testing/__init__.py +122 -0
- gebra/testing/fixtures.py +808 -0
- gebra/testing/harness.py +894 -0
- gebra/testing/mutations.py +2172 -0
- gebra/testing/strategies.py +1027 -0
- gebra/verify/__init__.py +422 -0
- gebra/verify/base.py +358 -0
- gebra/verify/conditions.py +741 -0
- gebra/verify/graph.py +898 -0
- gebra/verify/guards.py +657 -0
- gebra/verify/locations.py +245 -0
- gebra/verify/properties/__init__.py +37 -0
- gebra/verify/properties/dataflow_completeness.py +673 -0
- gebra/verify/properties/determinism_replay.py +334 -0
- gebra/verify/properties/effect_safety.py +489 -0
- gebra/verify/properties/graph_well_formed.py +351 -0
- gebra/verify/properties/termination_witness.py +1023 -0
- gebra/verify/registry.py +477 -0
- gebra/verify/report.py +242 -0
- gebra/verify/run.py +863 -0
- gebra/verify/witnesses.py +430 -0
- gebra/versioning/__init__.py +85 -0
- gebra/versioning/classify.py +289 -0
- gebra/versioning/models.py +301 -0
- gebra-0.0.1.dist-info/METADATA +453 -0
- gebra-0.0.1.dist-info/RECORD +112 -0
- gebra-0.0.1.dist-info/WHEEL +4 -0
- gebra-0.0.1.dist-info/entry_points.txt +5 -0
- gebra-0.0.1.dist-info/licenses/LICENSE +201 -0
- 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)
|