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,93 @@
1
+ """``GebraContractError`` — the decoration-time refusal of ANNOTATION-API-SPEC §1.
2
+
3
+ §1 puts the annotation surface's *errors* in exactly one place: "Decoration-time consistency
4
+ rules (violations raise ``GebraContractError`` at import time — cheap, early, never at
5
+ extraction)". Everything else on the annotation surface degrades instead: the sidecar's
6
+ validation is warning-grade "because the sidecar is config and extraction stays total" (§2),
7
+ the cross-surface precedence conflicts are warnings (§3, DEC-07), and even a resolved contract
8
+ that violates a §1 invariant across surfaces is repaired-with-a-warning rather than raised
9
+ (§3). So this exception says something narrow and specific: **one author's own decorator
10
+ stack contradicts itself**, and "a single author's stack has no drift to excuse".
11
+
12
+ Where it is raised is part of the meaning. A decorator runs when the defining module is
13
+ imported, so a violation surfaces at ``import my_agent``, before any graph is built and long
14
+ before ``gebra.extract()`` — which is the whole point of §1 putting these four rules here
15
+ rather than in the resolved-contract pass.
16
+
17
+ **Why one class with a reason code**, rather than a hierarchy: the same reasoning
18
+ :mod:`gebra.extraction.errors` records for :class:`~gebra.extraction.errors.ExtractionError`.
19
+ The refusals are one posture with several causes, and a caller that wants to branch does it
20
+ on :attr:`GebraContractError.reason` — a stable string — exactly as callers branch on
21
+ :class:`~gebra.ir.identity.NodeIdErrorReason`. It subclasses :class:`Exception` rather than
22
+ ``TypeError`` or ``ValueError`` because the causes are split between the two: a duplicate
23
+ slot is neither a wrong type nor a bad value.
24
+
25
+ Nothing here imports langgraph, opens a socket, or executes anything (WA-07).
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ from enum import Enum
31
+
32
+ __all__ = ["ContractErrorReason", "GebraContractError"]
33
+
34
+
35
+ class ContractErrorReason(str, Enum):
36
+ """Why decoration was refused — a stable code to branch on.
37
+
38
+ The first four are the four §1 consistency rules, one code each, so that "each rule
39
+ raises" is a checkable statement rather than a shared code with a variable message. The
40
+ last three are refusals of a *shape* the surface does not have: a slot that is not one
41
+ of the nine, a value that is not of the slot's kind, and a target that cannot carry the
42
+ attribute at all.
43
+
44
+ Attributes:
45
+ DUPLICATE_SLOT: A slot was set twice across one decorator stack. §1: "Each slot is
46
+ settable **at most once** across a decorator stack; a duplicate slot assignment
47
+ is an error, not a merge — **regardless of value, identical duplicates
48
+ included**." Deliberately stricter than §3's cross-surface rule, where identical
49
+ values are not a conflict.
50
+ PURE_EFFECT_EXCLUSIVE: ``pure=True`` and a non-empty ``effects`` were both declared
51
+ (decision D-011). Checked over the whole stack, so declaring them through two
52
+ different decorators is caught the same way as declaring both at once.
53
+ UNKNOWN_EFFECT_TAG: An ``effects`` tag outside the closed D-011 vocabulary
54
+ :data:`~gebra.annotations.slots.EFFECT_TAGS`. §1: "an unknown tag is an error".
55
+ DETERMINISTIC_SEED_REQUIRED: The ``deterministic`` object form was used without
56
+ ``seed``. §1 names the case outright: "``@gebra.deterministic(temperature=0.0)``
57
+ without ``seed=`` raises at decoration time"; the frozen ledger §3 shape
58
+ ``{seed: int, temperature?: number}`` owns the ruling.
59
+ UNKNOWN_SLOT: A keyword that is not one of the nine annotatable slots — a typo, or
60
+ one of the slots §1 puts out of annotation reach ("extracted or computed, never
61
+ annotated").
62
+ SLOT_VALUE_INVALID: A slot's value is not of that slot's kind — a bare string where
63
+ a sequence of state keys is meant, a non-string effect tag, an ``args_schema``
64
+ that is not a JSON object.
65
+ ATTACHMENT_IMPOSSIBLE: The target cannot carry ``__gebra_contract__`` at all — a
66
+ slotted or frozen object, a ``functools.partial``. §6 names this case and names
67
+ its answer: "the **sidecar is the designated fallback**".
68
+ """
69
+
70
+ DUPLICATE_SLOT = "duplicate-slot"
71
+ PURE_EFFECT_EXCLUSIVE = "pure-effect-exclusive"
72
+ UNKNOWN_EFFECT_TAG = "unknown-effect-tag"
73
+ DETERMINISTIC_SEED_REQUIRED = "deterministic-seed-required"
74
+ UNKNOWN_SLOT = "unknown-slot"
75
+ SLOT_VALUE_INVALID = "slot-value-invalid"
76
+ ATTACHMENT_IMPOSSIBLE = "attachment-impossible"
77
+
78
+
79
+ class GebraContractError(Exception):
80
+ """A decorator stack contradicts itself — raised at import time (§1).
81
+
82
+ Attributes:
83
+ reason: The :class:`ContractErrorReason` code — match on this, not on the message.
84
+ slot: The annotation slot the refusal is about, as its IR name, or ``None`` for a
85
+ refusal that is not about one slot (an unknown keyword, an unattachable target).
86
+ """
87
+
88
+ def __init__(
89
+ self, message: str, *, reason: ContractErrorReason, slot: str | None = None
90
+ ) -> None:
91
+ super().__init__(message)
92
+ self.reason = reason
93
+ self.slot = slot