teaql 0.2.8__tar.gz → 0.2.9__tar.gz
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.
- {teaql-0.2.8 → teaql-0.2.9}/PKG-INFO +26 -1
- {teaql-0.2.8 → teaql-0.2.9}/README.md +25 -0
- {teaql-0.2.8 → teaql-0.2.9}/pyproject.toml +1 -1
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/tfp_client/__init__.py +26 -21
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/__init__.py +32 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/audit.py +3 -1
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/context.py +40 -0
- teaql-0.2.9/src/teaql/runtime/mutation_policy.py +607 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/sql/executor.py +23 -8
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql.egg-info/PKG-INFO +26 -1
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql.egg-info/SOURCES.txt +1 -0
- {teaql-0.2.8 → teaql-0.2.9}/LICENSE +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/setup.cfg +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/__init__.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/__init__.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/dynamic_search.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/entity.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/eval.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/expr.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/graph.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/list.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/meta.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/mutation.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/query.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/safe_expression.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/value.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/xls.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/data_service/__init__.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/__init__.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/mysql/__init__.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/mysql/dialect.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/mysql/transport.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/postgres/__init__.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/postgres/dialect.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/postgres/transport.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/redis/__init__.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/redis/remote.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/redis/store.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/sqlite/__init__.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/sqlite/dialect.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/sqlite/transport.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/py.typed +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/_schema_capability.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/builtin-messages-v1.json +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/env.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/i18n.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/log_privacy.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/module.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/opentelemetry.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/store.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/telemetry.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/tools.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/wire_fields.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/sql/__init__.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/sql/dialect.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/sql/types.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/web_integration/__init__.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql/web_integration/fastapi/__init__.py +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql.egg-info/dependency_links.txt +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql.egg-info/requires.txt +0 -0
- {teaql-0.2.8 → teaql-0.2.9}/src/teaql.egg-info/top_level.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: teaql
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.9
|
|
4
4
|
Summary: TeaQL Runtime and Data Service for Python
|
|
5
5
|
Author: TeaQL
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -104,6 +104,11 @@ The SDK's organizational architecture strictly mirrors the Rust version:
|
|
|
104
104
|
* **Facet Aggregation & Grouping**: Out-of-the-box support for multi-dimensional facet aggregations, group-bys, and hierarchical data processing.
|
|
105
105
|
* **Provider Support**: Highly extensible asynchronous database connectivity (integrating third-party async drivers like `aiosqlite` through a unified Transport layer).
|
|
106
106
|
* **Context & Logging Management**: Built-in support for lifecycle context passing, end-to-end tracing, and SQL execution log interception and dispatch.
|
|
107
|
+
* **Governed Mutation Policy**: An application-owned policy can review an
|
|
108
|
+
immutable whole-graph plan after Checker/Fix and before the first provider
|
|
109
|
+
mutation. Exact policy identity and approval state are retained with audit
|
|
110
|
+
evidence. Missing customer policy or approval emits stable warnings without
|
|
111
|
+
changing persistence semantics; an explicit denial fails closed.
|
|
107
112
|
* **TeaQL Federal Protocol Client**: `TeaQLFederalClient` and `TfpHttpProvider`
|
|
108
113
|
execute governed canonical TFP v1 queries and audited mutations against a
|
|
109
114
|
remote TeaQL endpoint such as Rust. Direct query execution returns
|
|
@@ -143,5 +148,25 @@ development-only acknowledgement are maintained in the canonical
|
|
|
143
148
|
Opaque tokens never replace the backend's authorization, tenant, ownership,
|
|
144
149
|
role, or optimistic-version checks.
|
|
145
150
|
|
|
151
|
+
### Mutation Policy installation
|
|
152
|
+
|
|
153
|
+
Policy implementations are installed from trusted application startup through
|
|
154
|
+
`UserContext`; request JSON cannot select or replace them. Built-in SQL and TFP
|
|
155
|
+
providers enter the same governed boundary.
|
|
156
|
+
|
|
157
|
+
```python
|
|
158
|
+
context = (
|
|
159
|
+
UserContext.new()
|
|
160
|
+
.with_mutation_policy_registry(policy_registry)
|
|
161
|
+
.with_mutation_policy_approval_provider(approval_provider)
|
|
162
|
+
.with_mutation_governance_sink(warning_sink)
|
|
163
|
+
)
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Generated graph saves call `preflight_mutation(...)` for every operation before
|
|
167
|
+
the first provider write. See the repeatable
|
|
168
|
+
[`examples/mutation-policy`](examples/mutation-policy) example for allow,
|
|
169
|
+
approval, audit propagation, and zero-write denial evidence.
|
|
170
|
+
|
|
146
171
|
---
|
|
147
172
|
To run test validations and business logic simulations locally, simply run `pytest` in the project root.
|
|
@@ -65,6 +65,11 @@ The SDK's organizational architecture strictly mirrors the Rust version:
|
|
|
65
65
|
* **Facet Aggregation & Grouping**: Out-of-the-box support for multi-dimensional facet aggregations, group-bys, and hierarchical data processing.
|
|
66
66
|
* **Provider Support**: Highly extensible asynchronous database connectivity (integrating third-party async drivers like `aiosqlite` through a unified Transport layer).
|
|
67
67
|
* **Context & Logging Management**: Built-in support for lifecycle context passing, end-to-end tracing, and SQL execution log interception and dispatch.
|
|
68
|
+
* **Governed Mutation Policy**: An application-owned policy can review an
|
|
69
|
+
immutable whole-graph plan after Checker/Fix and before the first provider
|
|
70
|
+
mutation. Exact policy identity and approval state are retained with audit
|
|
71
|
+
evidence. Missing customer policy or approval emits stable warnings without
|
|
72
|
+
changing persistence semantics; an explicit denial fails closed.
|
|
68
73
|
* **TeaQL Federal Protocol Client**: `TeaQLFederalClient` and `TfpHttpProvider`
|
|
69
74
|
execute governed canonical TFP v1 queries and audited mutations against a
|
|
70
75
|
remote TeaQL endpoint such as Rust. Direct query execution returns
|
|
@@ -104,5 +109,25 @@ development-only acknowledgement are maintained in the canonical
|
|
|
104
109
|
Opaque tokens never replace the backend's authorization, tenant, ownership,
|
|
105
110
|
role, or optimistic-version checks.
|
|
106
111
|
|
|
112
|
+
### Mutation Policy installation
|
|
113
|
+
|
|
114
|
+
Policy implementations are installed from trusted application startup through
|
|
115
|
+
`UserContext`; request JSON cannot select or replace them. Built-in SQL and TFP
|
|
116
|
+
providers enter the same governed boundary.
|
|
117
|
+
|
|
118
|
+
```python
|
|
119
|
+
context = (
|
|
120
|
+
UserContext.new()
|
|
121
|
+
.with_mutation_policy_registry(policy_registry)
|
|
122
|
+
.with_mutation_policy_approval_provider(approval_provider)
|
|
123
|
+
.with_mutation_governance_sink(warning_sink)
|
|
124
|
+
)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Generated graph saves call `preflight_mutation(...)` for every operation before
|
|
128
|
+
the first provider write. See the repeatable
|
|
129
|
+
[`examples/mutation-policy`](examples/mutation-policy) example for allow,
|
|
130
|
+
approval, audit propagation, and zero-write denial evidence.
|
|
131
|
+
|
|
107
132
|
---
|
|
108
133
|
To run test validations and business logic simulations locally, simply run `pytest` in the project root.
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
from __future__ import annotations
|
|
2
2
|
|
|
3
|
+
from contextlib import nullcontext
|
|
3
4
|
from dataclasses import dataclass, field
|
|
4
5
|
from datetime import datetime
|
|
5
6
|
from typing import Any, Awaitable, Callable, Dict, Mapping, Optional
|
|
@@ -164,27 +165,31 @@ class TfpHttpProvider(DataService):
|
|
|
164
165
|
)
|
|
165
166
|
|
|
166
167
|
async def mutate(self, context: Any, request: MutationRequest) -> MutationResult:
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
"
|
|
175
|
-
|
|
176
|
-
"
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
168
|
+
if context is not None and not context.consume_mutation_checked(request._data):
|
|
169
|
+
context.check_and_fix_mutation(request._data)
|
|
170
|
+
scope = context.mutation_policy_execution(request) if context is not None else nullcontext()
|
|
171
|
+
with scope:
|
|
172
|
+
started_at = datetime.now()
|
|
173
|
+
federal = _mutation_request(request)
|
|
174
|
+
data = await self.federal_client.execute_mutation(federal)
|
|
175
|
+
records = data.get("data") or []
|
|
176
|
+
generated = records[0] if records else {}
|
|
177
|
+
affected = int(data.get("affectedRows", 0))
|
|
178
|
+
operation = {
|
|
179
|
+
"Create": DataServiceOperation.Insert,
|
|
180
|
+
"Update": DataServiceOperation.Update,
|
|
181
|
+
"Delete": DataServiceOperation.Delete,
|
|
182
|
+
"Recover": DataServiceOperation.Recover,
|
|
183
|
+
}[federal.action]
|
|
184
|
+
return MutationResult(
|
|
185
|
+
affected_rows=affected, generated_values=generated,
|
|
186
|
+
persisted_record=generated or None,
|
|
187
|
+
metadata=ExecutionMetadata(
|
|
188
|
+
backend="teaql-federal", operation=operation,
|
|
189
|
+
started_at=started_at, ended_at=datetime.now(), affected_rows=affected,
|
|
190
|
+
comment=federal.comment,
|
|
191
|
+
),
|
|
192
|
+
)
|
|
188
193
|
|
|
189
194
|
|
|
190
195
|
def _federal_query_payload(query: FederalQuery) -> Dict[str, Any]:
|
|
@@ -10,12 +10,44 @@ from .tools import (
|
|
|
10
10
|
from .module import RuntimeModule, DefaultEntityDataServiceBehavior
|
|
11
11
|
from .store import DataStore
|
|
12
12
|
from .audit import RawAuditEvent, SafeAuditEvent, MutationAuditKind
|
|
13
|
+
from .mutation_policy import (
|
|
14
|
+
MISSING_APPROVAL,
|
|
15
|
+
MISSING_POLICY,
|
|
16
|
+
DelegatingMutationGovernanceSink,
|
|
17
|
+
DelegatingMutationPolicyApprovalProvider,
|
|
18
|
+
DelegatingMutationPolicyRegistry,
|
|
19
|
+
MutationDecision,
|
|
20
|
+
MutationGovernanceEvent,
|
|
21
|
+
MutationGovernanceSnapshot,
|
|
22
|
+
MutationOperation,
|
|
23
|
+
MutationOperationKind,
|
|
24
|
+
MutationOperationSummary,
|
|
25
|
+
MutationPlan,
|
|
26
|
+
MutationPolicyApproval,
|
|
27
|
+
MutationPolicyApprovalStatus,
|
|
28
|
+
MutationPolicyError,
|
|
29
|
+
MutationPolicyIdentity,
|
|
30
|
+
MutationPolicySource,
|
|
31
|
+
MutationVerdict,
|
|
32
|
+
)
|
|
13
33
|
from .i18n import CheckException, CheckResult, I18nCatalog, JsonFieldNamingProfile, Locale, ObjectLocation, UnsupportedLocaleError
|
|
14
34
|
from .wire_fields import NormalizedWireInput, WireEntityMetadata, WireFieldMetadata, WireInputError, create_wire_entity_metadata, encode_wire_output, normalize_wire_input, retain_submitted_paths
|
|
15
35
|
from teaql.core.entity import EntityKey, EntityChangeSet, EntityRoot
|
|
16
36
|
|
|
17
37
|
__all__ = ["WireFieldMetadata", "WireEntityMetadata", "NormalizedWireInput", "WireInputError", "create_wire_entity_metadata", "normalize_wire_input", "encode_wire_output", "retain_submitted_paths", "EntityKey", "EntityChangeSet", "EntityRoot", "ContextEntityRef", "ContextRootError", "CheckException", "CheckResult", "I18nCatalog", "JsonFieldNamingProfile", "Locale", "ObjectLocation", "UnsupportedLocaleError", "UserContext", "TeaqlRuntime", "SqlLogEntry", "SqlLogOperation", "DiagnosticSqlLogSink", "TextDiagnosticSqlLogSink", "ServiceRuntimeFromEnv", "RuntimeModule", "DataStore", "RawAuditEvent", "SafeAuditEvent", "MutationAuditKind", "ContextTools", "ExecutableHttpTool", "HTTP_TOOL", "HttpIntentPhase", "HttpTool", "HttpToolProvider", "ToolDeniedError", "ToolError", "ToolPolicy", "ToolRisk", "Tools", "ToolToken", "ToolUnavailableError"]
|
|
18
38
|
|
|
39
|
+
__all__ += [
|
|
40
|
+
"MISSING_APPROVAL", "MISSING_POLICY",
|
|
41
|
+
"DelegatingMutationGovernanceSink",
|
|
42
|
+
"DelegatingMutationPolicyApprovalProvider",
|
|
43
|
+
"DelegatingMutationPolicyRegistry", "MutationDecision",
|
|
44
|
+
"MutationGovernanceEvent", "MutationGovernanceSnapshot",
|
|
45
|
+
"MutationOperation", "MutationOperationKind", "MutationOperationSummary",
|
|
46
|
+
"MutationPlan", "MutationPolicyApproval", "MutationPolicyApprovalStatus",
|
|
47
|
+
"MutationPolicyError", "MutationPolicyIdentity", "MutationPolicySource",
|
|
48
|
+
"MutationVerdict",
|
|
49
|
+
]
|
|
50
|
+
|
|
19
51
|
|
|
20
52
|
def __getattr__(name):
|
|
21
53
|
# Keep provider construction lazy: importing a SQL provider loads runtime
|
|
@@ -27,6 +27,7 @@ class RawAuditEvent:
|
|
|
27
27
|
trace_chain: tuple[Any, ...] = field(default_factory=tuple)
|
|
28
28
|
actor: Optional[str] = None
|
|
29
29
|
category: Optional[str] = None
|
|
30
|
+
mutation_governance: Any = None
|
|
30
31
|
|
|
31
32
|
def safe(self, mask_fields: List[str], max_length: Optional[int]) -> "SafeAuditEvent":
|
|
32
33
|
from .log_privacy import REDACTED, credential_name, payload_has_credentials, plaintext_enabled, scrub, value_strings
|
|
@@ -51,7 +52,7 @@ class RawAuditEvent:
|
|
|
51
52
|
intent_values = secrets + value_strings(self.entity_id)
|
|
52
53
|
return SafeAuditEvent(
|
|
53
54
|
self.kind, self.entity, self.entity_id, scrub(tuple(fields), secrets), scrub(self.trace_chain, intent_values),
|
|
54
|
-
scrub(self.actor, intent_values), self.category,
|
|
55
|
+
scrub(self.actor, intent_values), self.category, self.mutation_governance,
|
|
55
56
|
)
|
|
56
57
|
|
|
57
58
|
|
|
@@ -72,6 +73,7 @@ class SafeAuditEvent:
|
|
|
72
73
|
trace_chain: tuple[Any, ...] = field(default_factory=tuple)
|
|
73
74
|
actor: Optional[str] = None
|
|
74
75
|
category: Optional[str] = None
|
|
76
|
+
mutation_governance: Any = None
|
|
75
77
|
|
|
76
78
|
|
|
77
79
|
def _mask(value: str) -> str:
|
|
@@ -105,6 +105,8 @@ class UserContext:
|
|
|
105
105
|
self._fix_evidence_current: List[FixEvidence] = []
|
|
106
106
|
self._fix_evidence_last: List[FixEvidence] = []
|
|
107
107
|
self._checked_mutations = set()
|
|
108
|
+
from .mutation_policy import MutationPolicyRuntimeState
|
|
109
|
+
self._mutation_policy = MutationPolicyRuntimeState()
|
|
108
110
|
|
|
109
111
|
def begin_fix_evidence(self):
|
|
110
112
|
self._fix_evidence_current = []
|
|
@@ -159,6 +161,7 @@ class UserContext:
|
|
|
159
161
|
transaction = await begin()
|
|
160
162
|
owner_token = self._graph_save_owner.set(object())
|
|
161
163
|
self._graph_save_active = True
|
|
164
|
+
self._mutation_policy.begin_graph()
|
|
162
165
|
self._graph_commit_actions = []
|
|
163
166
|
self._graph_rollback_actions = []
|
|
164
167
|
self.insert_resource("fix_time", datetime.now())
|
|
@@ -175,6 +178,7 @@ class UserContext:
|
|
|
175
178
|
raise
|
|
176
179
|
else:
|
|
177
180
|
try:
|
|
181
|
+
self._mutation_policy.ensure_graph_complete()
|
|
178
182
|
await self._finish_graph_transaction(transaction, "commit")
|
|
179
183
|
except BaseException:
|
|
180
184
|
try:
|
|
@@ -189,6 +193,7 @@ class UserContext:
|
|
|
189
193
|
finally:
|
|
190
194
|
self.insert_resource("dataService", provider)
|
|
191
195
|
self._graph_save_active = False
|
|
196
|
+
self._mutation_policy.end_graph()
|
|
192
197
|
self._graph_commit_actions = []
|
|
193
198
|
self._graph_rollback_actions = []
|
|
194
199
|
self._resources.pop("fix_time", None)
|
|
@@ -639,6 +644,41 @@ class UserContext:
|
|
|
639
644
|
self._app_audit_sink = sink
|
|
640
645
|
return self
|
|
641
646
|
|
|
647
|
+
def with_mutation_policy_registry(self, registry: Any) -> 'UserContext':
|
|
648
|
+
if registry is None or not callable(getattr(registry, "resolve", None)):
|
|
649
|
+
raise TypeError("mutation policy registry must expose resolve(request_key)")
|
|
650
|
+
self._mutation_policy.registry = registry
|
|
651
|
+
return self
|
|
652
|
+
|
|
653
|
+
def with_mutation_policy_approval_provider(self, provider: Any) -> 'UserContext':
|
|
654
|
+
if provider is None or not callable(getattr(provider, "find_approval", None)):
|
|
655
|
+
raise TypeError(
|
|
656
|
+
"mutation policy approval provider must expose find_approval(identity)"
|
|
657
|
+
)
|
|
658
|
+
self._mutation_policy.approval_provider = provider
|
|
659
|
+
return self
|
|
660
|
+
|
|
661
|
+
def with_mutation_governance_sink(self, sink: Any) -> 'UserContext':
|
|
662
|
+
if sink is None or not callable(getattr(sink, "on_warning", None)):
|
|
663
|
+
raise TypeError("mutation governance sink must expose on_warning(context, event)")
|
|
664
|
+
self._mutation_policy.warning_sink = sink
|
|
665
|
+
return self
|
|
666
|
+
|
|
667
|
+
def current_mutation_governance(self):
|
|
668
|
+
return self._mutation_policy.current
|
|
669
|
+
|
|
670
|
+
def review_mutation_plan(self, plan: Any):
|
|
671
|
+
return self._mutation_policy.review(self, plan)
|
|
672
|
+
|
|
673
|
+
def preflight_mutation(self, mutation: Any) -> None:
|
|
674
|
+
"""Check/fix and snapshot one operation for whole-graph policy review."""
|
|
675
|
+
self.check_and_fix_mutation(mutation)
|
|
676
|
+
self._mutation_policy.record_preflight(mutation)
|
|
677
|
+
|
|
678
|
+
def mutation_policy_execution(self, request: Any):
|
|
679
|
+
"""Provider boundary scope; entered after validation and before mutation."""
|
|
680
|
+
return self._mutation_policy.enter_mutation(self, request)
|
|
681
|
+
|
|
642
682
|
def with_sql_log_options(self, options: 'SqlLogOptions') -> 'UserContext':
|
|
643
683
|
self.insert_resource("sql_log_options", options)
|
|
644
684
|
return self
|
|
@@ -0,0 +1,607 @@
|
|
|
1
|
+
"""Governed, whole-graph mutation policy contracts.
|
|
2
|
+
|
|
3
|
+
The policy receives a detached snapshot after Checker/Fix and before the first
|
|
4
|
+
provider mutation. Runtime-specific transaction setup may already have happened;
|
|
5
|
+
the portable guarantee is that no provider mutation has executed.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import contextvars
|
|
11
|
+
import logging
|
|
12
|
+
import threading
|
|
13
|
+
from collections import Counter
|
|
14
|
+
from copy import deepcopy
|
|
15
|
+
from dataclasses import dataclass
|
|
16
|
+
from datetime import date, datetime
|
|
17
|
+
from decimal import Decimal
|
|
18
|
+
from enum import Enum
|
|
19
|
+
from types import MappingProxyType
|
|
20
|
+
from typing import Any, Callable, Mapping, Optional, Protocol, Sequence
|
|
21
|
+
|
|
22
|
+
from teaql.core.mutation import (
|
|
23
|
+
DeleteCommand,
|
|
24
|
+
InsertCommand,
|
|
25
|
+
MutationRequest,
|
|
26
|
+
RecoverCommand,
|
|
27
|
+
UpdateCommand,
|
|
28
|
+
)
|
|
29
|
+
from teaql.core.value import Timestamp, Value
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
MISSING_POLICY = "MUTATION-POLICY-001"
|
|
33
|
+
MISSING_APPROVAL = "MUTATION-POLICY-002"
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class MutationPolicyError(RuntimeError):
|
|
37
|
+
pass
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class MutationOperationKind(str, Enum):
|
|
41
|
+
CREATE = "create"
|
|
42
|
+
UPDATE = "update"
|
|
43
|
+
DELETE = "delete"
|
|
44
|
+
RECOVER = "recover"
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
@dataclass(frozen=True)
|
|
48
|
+
class MutationPolicyIdentity:
|
|
49
|
+
policy_id: str
|
|
50
|
+
version: str
|
|
51
|
+
fingerprint: str
|
|
52
|
+
|
|
53
|
+
def __post_init__(self) -> None:
|
|
54
|
+
for name in ("policy_id", "version", "fingerprint"):
|
|
55
|
+
value = getattr(self, name)
|
|
56
|
+
if not isinstance(value, str) or not value.strip():
|
|
57
|
+
raise ValueError("mutation policy identity values must not be blank")
|
|
58
|
+
object.__setattr__(self, name, value.strip())
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
@dataclass(frozen=True)
|
|
62
|
+
class MutationOperation:
|
|
63
|
+
kind: MutationOperationKind
|
|
64
|
+
entity: str
|
|
65
|
+
entity_id: Optional[Value]
|
|
66
|
+
original_version: Optional[int]
|
|
67
|
+
changed_values: Mapping[str, Value]
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
@dataclass(frozen=True)
|
|
71
|
+
class MutationPlan:
|
|
72
|
+
execution_id: str
|
|
73
|
+
request_key: str
|
|
74
|
+
root_entity_type: str
|
|
75
|
+
audit_reason: Optional[str]
|
|
76
|
+
operations: tuple[MutationOperation, ...]
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
class MutationVerdict(str, Enum):
|
|
80
|
+
ALLOW = "allow"
|
|
81
|
+
DENY = "deny"
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
@dataclass(frozen=True)
|
|
85
|
+
class MutationDecision:
|
|
86
|
+
verdict: MutationVerdict
|
|
87
|
+
code: Optional[str] = None
|
|
88
|
+
message: Optional[str] = None
|
|
89
|
+
field_paths: tuple[str, ...] = ()
|
|
90
|
+
|
|
91
|
+
@classmethod
|
|
92
|
+
def allowed(cls) -> "MutationDecision":
|
|
93
|
+
return cls(MutationVerdict.ALLOW)
|
|
94
|
+
|
|
95
|
+
@classmethod
|
|
96
|
+
def denied(
|
|
97
|
+
cls, code: str, message: str, *field_paths: str
|
|
98
|
+
) -> "MutationDecision":
|
|
99
|
+
if not isinstance(code, str) or not code.strip():
|
|
100
|
+
raise ValueError("a mutation policy denial code is required")
|
|
101
|
+
return cls(MutationVerdict.DENY, code.strip(), message, tuple(field_paths))
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
class MutationPolicy(Protocol):
|
|
105
|
+
identity: MutationPolicyIdentity
|
|
106
|
+
|
|
107
|
+
def review(self, context: Any, plan: MutationPlan) -> MutationDecision:
|
|
108
|
+
...
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
class MutationPolicyRegistry(Protocol):
|
|
112
|
+
def resolve(self, request_key: str) -> Optional[MutationPolicy]:
|
|
113
|
+
...
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
class DelegatingMutationPolicyRegistry:
|
|
117
|
+
def __init__(self, resolve: Callable[[str], Optional[MutationPolicy]]):
|
|
118
|
+
self._resolve = resolve
|
|
119
|
+
|
|
120
|
+
def resolve(self, request_key: str) -> Optional[MutationPolicy]:
|
|
121
|
+
return self._resolve(request_key)
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
@dataclass(frozen=True)
|
|
125
|
+
class MutationPolicyApproval:
|
|
126
|
+
policy: MutationPolicyIdentity
|
|
127
|
+
approved_by: str
|
|
128
|
+
approved_at: datetime
|
|
129
|
+
|
|
130
|
+
def is_valid_for(self, identity: MutationPolicyIdentity) -> bool:
|
|
131
|
+
return (
|
|
132
|
+
self.policy == identity
|
|
133
|
+
and isinstance(self.approved_by, str)
|
|
134
|
+
and bool(self.approved_by.strip())
|
|
135
|
+
and isinstance(self.approved_at, datetime)
|
|
136
|
+
and self.approved_at.replace(tzinfo=None) != datetime.min
|
|
137
|
+
)
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
class MutationPolicyApprovalProvider(Protocol):
|
|
141
|
+
def find_approval(
|
|
142
|
+
self, identity: MutationPolicyIdentity
|
|
143
|
+
) -> Optional[MutationPolicyApproval]:
|
|
144
|
+
...
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
class DelegatingMutationPolicyApprovalProvider:
|
|
148
|
+
def __init__(
|
|
149
|
+
self,
|
|
150
|
+
find: Callable[[MutationPolicyIdentity], Optional[MutationPolicyApproval]],
|
|
151
|
+
):
|
|
152
|
+
self._find = find
|
|
153
|
+
|
|
154
|
+
def find_approval(
|
|
155
|
+
self, identity: MutationPolicyIdentity
|
|
156
|
+
) -> Optional[MutationPolicyApproval]:
|
|
157
|
+
return self._find(identity)
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
class MutationPolicySource(str, Enum):
|
|
161
|
+
GENERATED_DEFAULT = "generated_default"
|
|
162
|
+
CUSTOMER = "customer"
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
class MutationPolicyApprovalStatus(str, Enum):
|
|
166
|
+
NOT_APPLICABLE = "not_applicable"
|
|
167
|
+
MISSING = "missing"
|
|
168
|
+
APPROVED = "approved"
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
@dataclass(frozen=True)
|
|
172
|
+
class MutationOperationSummary:
|
|
173
|
+
kind: MutationOperationKind
|
|
174
|
+
entity: str
|
|
175
|
+
entity_id: Optional[Value]
|
|
176
|
+
changed_fields: tuple[str, ...]
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
@dataclass(frozen=True)
|
|
180
|
+
class MutationGovernanceSnapshot:
|
|
181
|
+
execution_id: str
|
|
182
|
+
request_key: str
|
|
183
|
+
source: MutationPolicySource
|
|
184
|
+
policy: Optional[MutationPolicyIdentity]
|
|
185
|
+
approval_status: MutationPolicyApprovalStatus
|
|
186
|
+
warning_codes: tuple[str, ...]
|
|
187
|
+
operations: tuple[MutationOperationSummary, ...]
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
@dataclass(frozen=True)
|
|
191
|
+
class MutationGovernanceEvent:
|
|
192
|
+
snapshot: MutationGovernanceSnapshot
|
|
193
|
+
warning_code: str
|
|
194
|
+
first_occurrence: bool
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
class MutationGovernanceSink(Protocol):
|
|
198
|
+
def on_warning(self, context: Any, warning: MutationGovernanceEvent) -> None:
|
|
199
|
+
...
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
class DelegatingMutationGovernanceSink:
|
|
203
|
+
def __init__(self, warning: Callable[[Any, MutationGovernanceEvent], None]):
|
|
204
|
+
self._warning = warning
|
|
205
|
+
|
|
206
|
+
def on_warning(self, context: Any, warning: MutationGovernanceEvent) -> None:
|
|
207
|
+
self._warning(context, warning)
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
class _TextMutationGovernanceSink:
|
|
211
|
+
def on_warning(self, context: Any, warning: MutationGovernanceEvent) -> None:
|
|
212
|
+
if not warning.first_occurrence:
|
|
213
|
+
return
|
|
214
|
+
logging.getLogger("teaql.mutation_policy").warning(
|
|
215
|
+
"TeaQL mutation policy warning code=%s request_key=%s source=%s approval=%s",
|
|
216
|
+
warning.warning_code,
|
|
217
|
+
warning.snapshot.request_key,
|
|
218
|
+
warning.snapshot.source.value,
|
|
219
|
+
warning.snapshot.approval_status.value,
|
|
220
|
+
)
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
class MutationPolicyRuntimeState:
|
|
224
|
+
_sequence = 0
|
|
225
|
+
_sequence_lock = threading.Lock()
|
|
226
|
+
|
|
227
|
+
def __init__(self) -> None:
|
|
228
|
+
self.registry: Optional[MutationPolicyRegistry] = None
|
|
229
|
+
self.approval_provider: Optional[MutationPolicyApprovalProvider] = None
|
|
230
|
+
self.warning_sink: MutationGovernanceSink = _TextMutationGovernanceSink()
|
|
231
|
+
self._emitted_warnings: set[str] = set()
|
|
232
|
+
self._warning_lock = threading.Lock()
|
|
233
|
+
self._active = contextvars.ContextVar(
|
|
234
|
+
f"teaql_mutation_policy_{id(self)}", default=None
|
|
235
|
+
)
|
|
236
|
+
self._graph_active = False
|
|
237
|
+
self._graph_reviewed = False
|
|
238
|
+
self._preflight: list[MutationOperation] = []
|
|
239
|
+
self._root_entity: Optional[str] = None
|
|
240
|
+
self._audit_reason: Optional[str] = None
|
|
241
|
+
self._remaining: Counter[Any] = Counter()
|
|
242
|
+
|
|
243
|
+
@property
|
|
244
|
+
def current(self) -> Optional[MutationGovernanceSnapshot]:
|
|
245
|
+
return self._active.get()
|
|
246
|
+
|
|
247
|
+
def begin_graph(self) -> None:
|
|
248
|
+
self._graph_active = True
|
|
249
|
+
self._graph_reviewed = False
|
|
250
|
+
self._preflight.clear()
|
|
251
|
+
self._root_entity = None
|
|
252
|
+
self._audit_reason = None
|
|
253
|
+
self._remaining.clear()
|
|
254
|
+
self._active.set(None)
|
|
255
|
+
|
|
256
|
+
def end_graph(self) -> None:
|
|
257
|
+
self._graph_active = False
|
|
258
|
+
self._graph_reviewed = False
|
|
259
|
+
self._preflight.clear()
|
|
260
|
+
self._root_entity = None
|
|
261
|
+
self._audit_reason = None
|
|
262
|
+
self._remaining.clear()
|
|
263
|
+
self._active.set(None)
|
|
264
|
+
|
|
265
|
+
def record_preflight(self, command: Any) -> None:
|
|
266
|
+
if not self._graph_active:
|
|
267
|
+
return
|
|
268
|
+
if self._graph_reviewed:
|
|
269
|
+
raise MutationPolicyError(
|
|
270
|
+
"mutation preflight cannot add operations after policy review"
|
|
271
|
+
)
|
|
272
|
+
operations = _operations_from_data(command)
|
|
273
|
+
if not operations:
|
|
274
|
+
raise MutationPolicyError("mutation preflight must contain an operation")
|
|
275
|
+
self._root_entity = self._root_entity or operations[0].entity
|
|
276
|
+
self._audit_reason = self._audit_reason or _comment_from_data(command)
|
|
277
|
+
self._preflight.extend(operations)
|
|
278
|
+
|
|
279
|
+
def enter_mutation(self, context: Any, request: MutationRequest):
|
|
280
|
+
operations = _operations_from_data(request._data)
|
|
281
|
+
if not operations:
|
|
282
|
+
raise MutationPolicyError("mutation request must contain an operation")
|
|
283
|
+
# Legacy/manual graph transactions cannot describe the complete graph
|
|
284
|
+
# before their first provider call. Keep those writes governed by the
|
|
285
|
+
# generated-default policy one operation at a time. Installing a
|
|
286
|
+
# customer policy still requires a complete preflight and therefore
|
|
287
|
+
# remains fail-closed.
|
|
288
|
+
if self._graph_active and self.registry is None and not self._preflight:
|
|
289
|
+
plan = self._build_plan(
|
|
290
|
+
context, operations[0].entity, _request_comment(request), tuple(operations)
|
|
291
|
+
)
|
|
292
|
+
token = self._active.set(self.review(context, plan))
|
|
293
|
+
return _ResetScope(self._active, token)
|
|
294
|
+
if self._graph_active:
|
|
295
|
+
if not self._graph_reviewed:
|
|
296
|
+
if self.registry is not None and not self._preflight:
|
|
297
|
+
raise MutationPolicyError(
|
|
298
|
+
"customer mutation policy requires complete graph preflight "
|
|
299
|
+
"before provider mutation"
|
|
300
|
+
)
|
|
301
|
+
planned = tuple(self._preflight or operations)
|
|
302
|
+
root = self._root_entity or planned[0].entity
|
|
303
|
+
reason = self._audit_reason or _request_comment(request)
|
|
304
|
+
snapshot = self.review(context, self._build_plan(context, root, reason, planned))
|
|
305
|
+
self._active.set(snapshot)
|
|
306
|
+
self._remaining = Counter(_operation_signature(item) for item in planned)
|
|
307
|
+
self._graph_reviewed = True
|
|
308
|
+
self._consume_planned(operations)
|
|
309
|
+
return _NoopScope()
|
|
310
|
+
|
|
311
|
+
plan = self._build_plan(
|
|
312
|
+
context, operations[0].entity, _request_comment(request), tuple(operations)
|
|
313
|
+
)
|
|
314
|
+
token = self._active.set(self.review(context, plan))
|
|
315
|
+
return _ResetScope(self._active, token)
|
|
316
|
+
|
|
317
|
+
def ensure_graph_complete(self) -> None:
|
|
318
|
+
if self._graph_reviewed and self._remaining:
|
|
319
|
+
raise MutationPolicyError(
|
|
320
|
+
"reviewed mutation plan contains operations that were not executed"
|
|
321
|
+
)
|
|
322
|
+
|
|
323
|
+
def review(self, context: Any, plan: MutationPlan) -> MutationGovernanceSnapshot:
|
|
324
|
+
_validate_plan(plan)
|
|
325
|
+
policy = self.registry.resolve(plan.request_key) if self.registry else None
|
|
326
|
+
if policy is None:
|
|
327
|
+
source = MutationPolicySource.GENERATED_DEFAULT
|
|
328
|
+
identity = None
|
|
329
|
+
approval = MutationPolicyApprovalStatus.NOT_APPLICABLE
|
|
330
|
+
warnings = (MISSING_POLICY,)
|
|
331
|
+
else:
|
|
332
|
+
identity = policy.identity
|
|
333
|
+
if not isinstance(identity, MutationPolicyIdentity):
|
|
334
|
+
raise MutationPolicyError("customer mutation policy identity is invalid")
|
|
335
|
+
decision = policy.review(context, _clone_plan(plan))
|
|
336
|
+
if not isinstance(decision, MutationDecision):
|
|
337
|
+
raise MutationPolicyError("customer mutation policy returned an invalid decision")
|
|
338
|
+
if decision.verdict == MutationVerdict.DENY:
|
|
339
|
+
raise MutationPolicyError(
|
|
340
|
+
f"[MUTATION POLICY DENIED] "
|
|
341
|
+
f"{decision.code or 'MUTATION-POLICY-DENIED'}: "
|
|
342
|
+
f"{decision.message or 'mutation rejected'}"
|
|
343
|
+
)
|
|
344
|
+
if decision.verdict != MutationVerdict.ALLOW:
|
|
345
|
+
raise MutationPolicyError("customer mutation policy returned an invalid verdict")
|
|
346
|
+
source = MutationPolicySource.CUSTOMER
|
|
347
|
+
found = (
|
|
348
|
+
self.approval_provider.find_approval(identity)
|
|
349
|
+
if self.approval_provider
|
|
350
|
+
else None
|
|
351
|
+
)
|
|
352
|
+
approval = (
|
|
353
|
+
MutationPolicyApprovalStatus.APPROVED
|
|
354
|
+
if found is not None and found.is_valid_for(identity)
|
|
355
|
+
else MutationPolicyApprovalStatus.MISSING
|
|
356
|
+
)
|
|
357
|
+
warnings = () if approval == MutationPolicyApprovalStatus.APPROVED else (MISSING_APPROVAL,)
|
|
358
|
+
|
|
359
|
+
snapshot = MutationGovernanceSnapshot(
|
|
360
|
+
execution_id=plan.execution_id,
|
|
361
|
+
request_key=plan.request_key,
|
|
362
|
+
source=source,
|
|
363
|
+
policy=identity,
|
|
364
|
+
approval_status=approval,
|
|
365
|
+
warning_codes=warnings,
|
|
366
|
+
operations=tuple(
|
|
367
|
+
MutationOperationSummary(
|
|
368
|
+
item.kind,
|
|
369
|
+
item.entity,
|
|
370
|
+
_clone_value(item.entity_id) if item.entity_id else None,
|
|
371
|
+
tuple(sorted(item.changed_values)),
|
|
372
|
+
)
|
|
373
|
+
for item in plan.operations
|
|
374
|
+
),
|
|
375
|
+
)
|
|
376
|
+
for warning in warnings:
|
|
377
|
+
self._emit_warning(context, snapshot, warning)
|
|
378
|
+
return snapshot
|
|
379
|
+
|
|
380
|
+
def _consume_planned(self, operations: Sequence[MutationOperation]) -> None:
|
|
381
|
+
for operation in operations:
|
|
382
|
+
signature = _operation_signature(operation)
|
|
383
|
+
if self._remaining[signature] <= 0:
|
|
384
|
+
raise MutationPolicyError(
|
|
385
|
+
"provider mutation is not present in the reviewed graph plan"
|
|
386
|
+
)
|
|
387
|
+
self._remaining[signature] -= 1
|
|
388
|
+
if self._remaining[signature] == 0:
|
|
389
|
+
del self._remaining[signature]
|
|
390
|
+
|
|
391
|
+
def _build_plan(
|
|
392
|
+
self,
|
|
393
|
+
context: Any,
|
|
394
|
+
root: str,
|
|
395
|
+
reason: Optional[str],
|
|
396
|
+
operations: tuple[MutationOperation, ...],
|
|
397
|
+
) -> MutationPlan:
|
|
398
|
+
with self._sequence_lock:
|
|
399
|
+
type(self)._sequence += 1
|
|
400
|
+
sequence = type(self)._sequence
|
|
401
|
+
trace_id = getattr(context, "trace_id", lambda: "")()
|
|
402
|
+
return MutationPlan(
|
|
403
|
+
execution_id=f"{trace_id or 'teaql'}-mutation-{sequence}",
|
|
404
|
+
request_key=f"{root}.saveGraph",
|
|
405
|
+
root_entity_type=root,
|
|
406
|
+
audit_reason=reason,
|
|
407
|
+
operations=tuple(_clone_operation(item) for item in operations),
|
|
408
|
+
)
|
|
409
|
+
|
|
410
|
+
def _emit_warning(
|
|
411
|
+
self,
|
|
412
|
+
context: Any,
|
|
413
|
+
snapshot: MutationGovernanceSnapshot,
|
|
414
|
+
warning_code: str,
|
|
415
|
+
) -> None:
|
|
416
|
+
identity = (
|
|
417
|
+
"none"
|
|
418
|
+
if snapshot.policy is None
|
|
419
|
+
else f"{snapshot.policy.policy_id}:{snapshot.policy.version}:"
|
|
420
|
+
f"{snapshot.policy.fingerprint}"
|
|
421
|
+
)
|
|
422
|
+
key = f"{snapshot.request_key}|{identity}|{warning_code}"
|
|
423
|
+
with self._warning_lock:
|
|
424
|
+
first = key not in self._emitted_warnings
|
|
425
|
+
self._emitted_warnings.add(key)
|
|
426
|
+
try:
|
|
427
|
+
self.warning_sink.on_warning(
|
|
428
|
+
context,
|
|
429
|
+
MutationGovernanceEvent(snapshot, warning_code, first),
|
|
430
|
+
)
|
|
431
|
+
except BaseException:
|
|
432
|
+
# Warning delivery must not change business persistence semantics.
|
|
433
|
+
pass
|
|
434
|
+
|
|
435
|
+
|
|
436
|
+
class _NoopScope:
|
|
437
|
+
def __enter__(self):
|
|
438
|
+
return self
|
|
439
|
+
|
|
440
|
+
def __exit__(self, exc_type, exc_value, traceback):
|
|
441
|
+
return False
|
|
442
|
+
|
|
443
|
+
|
|
444
|
+
class _ResetScope:
|
|
445
|
+
def __init__(self, variable: contextvars.ContextVar, token: contextvars.Token):
|
|
446
|
+
self._variable = variable
|
|
447
|
+
self._token = token
|
|
448
|
+
|
|
449
|
+
def __enter__(self):
|
|
450
|
+
return self
|
|
451
|
+
|
|
452
|
+
def __exit__(self, exc_type, exc_value, traceback):
|
|
453
|
+
self._variable.reset(self._token)
|
|
454
|
+
return False
|
|
455
|
+
|
|
456
|
+
|
|
457
|
+
def _operations_from_data(data: Any) -> list[MutationOperation]:
|
|
458
|
+
if isinstance(data, MutationRequest):
|
|
459
|
+
return _operations_from_data(data._data)
|
|
460
|
+
if isinstance(data, list):
|
|
461
|
+
operations: list[MutationOperation] = []
|
|
462
|
+
for item in data:
|
|
463
|
+
operations.extend(_operations_from_data(item))
|
|
464
|
+
return operations
|
|
465
|
+
if isinstance(data, InsertCommand):
|
|
466
|
+
return [MutationOperation(
|
|
467
|
+
MutationOperationKind.CREATE,
|
|
468
|
+
data.entity,
|
|
469
|
+
_clone_value(data.values.get("id")),
|
|
470
|
+
None,
|
|
471
|
+
_readonly_values(data.values),
|
|
472
|
+
)]
|
|
473
|
+
if isinstance(data, UpdateCommand):
|
|
474
|
+
return [MutationOperation(
|
|
475
|
+
MutationOperationKind.UPDATE,
|
|
476
|
+
data.entity,
|
|
477
|
+
_clone_value(data.id),
|
|
478
|
+
data.expected_version_val,
|
|
479
|
+
_readonly_values(data.values),
|
|
480
|
+
)]
|
|
481
|
+
if isinstance(data, DeleteCommand):
|
|
482
|
+
return [MutationOperation(
|
|
483
|
+
MutationOperationKind.DELETE,
|
|
484
|
+
data.entity,
|
|
485
|
+
_clone_value(data.id),
|
|
486
|
+
data.expected_version_val,
|
|
487
|
+
MappingProxyType({}),
|
|
488
|
+
)]
|
|
489
|
+
if isinstance(data, RecoverCommand):
|
|
490
|
+
return [MutationOperation(
|
|
491
|
+
MutationOperationKind.RECOVER,
|
|
492
|
+
data.entity,
|
|
493
|
+
_clone_value(data.id),
|
|
494
|
+
data.expected_version_val,
|
|
495
|
+
MappingProxyType({}),
|
|
496
|
+
)]
|
|
497
|
+
raise MutationPolicyError(f"unsupported mutation command {type(data).__name__}")
|
|
498
|
+
|
|
499
|
+
|
|
500
|
+
def _comment_from_data(data: Any) -> Optional[str]:
|
|
501
|
+
if isinstance(data, MutationRequest):
|
|
502
|
+
return _request_comment(data)
|
|
503
|
+
if isinstance(data, list):
|
|
504
|
+
for item in data:
|
|
505
|
+
comment = _comment_from_data(item)
|
|
506
|
+
if comment:
|
|
507
|
+
return comment
|
|
508
|
+
return None
|
|
509
|
+
traces = getattr(data, "trace_chain", ())
|
|
510
|
+
return traces[-1].comment if traces else None
|
|
511
|
+
|
|
512
|
+
|
|
513
|
+
def _request_comment(request: MutationRequest) -> Optional[str]:
|
|
514
|
+
comment = getattr(request, "comment", None)
|
|
515
|
+
return comment() if callable(comment) else comment
|
|
516
|
+
|
|
517
|
+
|
|
518
|
+
def _readonly_values(values: Mapping[str, Value]) -> Mapping[str, Value]:
|
|
519
|
+
return MappingProxyType({key: _clone_value(value) for key, value in values.items()})
|
|
520
|
+
|
|
521
|
+
|
|
522
|
+
def _clone_value(value: Optional[Value]) -> Optional[Value]:
|
|
523
|
+
if value is None:
|
|
524
|
+
return None
|
|
525
|
+
raw = value.val
|
|
526
|
+
if hasattr(raw, "id"):
|
|
527
|
+
raw = getattr(raw, "id")
|
|
528
|
+
else:
|
|
529
|
+
try:
|
|
530
|
+
raw = deepcopy(raw)
|
|
531
|
+
except BaseException:
|
|
532
|
+
raw = repr(raw)
|
|
533
|
+
return Value(raw, getattr(value, "_type_hint", None))
|
|
534
|
+
|
|
535
|
+
|
|
536
|
+
def _clone_operation(operation: MutationOperation) -> MutationOperation:
|
|
537
|
+
return MutationOperation(
|
|
538
|
+
operation.kind,
|
|
539
|
+
operation.entity,
|
|
540
|
+
_clone_value(operation.entity_id),
|
|
541
|
+
operation.original_version,
|
|
542
|
+
_readonly_values(operation.changed_values),
|
|
543
|
+
)
|
|
544
|
+
|
|
545
|
+
|
|
546
|
+
def _clone_plan(plan: MutationPlan) -> MutationPlan:
|
|
547
|
+
return MutationPlan(
|
|
548
|
+
plan.execution_id,
|
|
549
|
+
plan.request_key,
|
|
550
|
+
plan.root_entity_type,
|
|
551
|
+
plan.audit_reason,
|
|
552
|
+
tuple(_clone_operation(item) for item in plan.operations),
|
|
553
|
+
)
|
|
554
|
+
|
|
555
|
+
|
|
556
|
+
def _validate_plan(plan: MutationPlan) -> None:
|
|
557
|
+
if not isinstance(plan.execution_id, str) or not plan.execution_id.strip():
|
|
558
|
+
raise MutationPolicyError("mutation plan execution id is required")
|
|
559
|
+
if not isinstance(plan.request_key, str) or not plan.request_key.strip():
|
|
560
|
+
raise MutationPolicyError("mutation plan request key is required")
|
|
561
|
+
if not isinstance(plan.root_entity_type, str) or not plan.root_entity_type.strip():
|
|
562
|
+
raise MutationPolicyError("mutation plan root entity type is required")
|
|
563
|
+
if not plan.operations:
|
|
564
|
+
raise MutationPolicyError("mutation plan must contain an operation")
|
|
565
|
+
if any(not item.entity for item in plan.operations):
|
|
566
|
+
raise MutationPolicyError("mutation operation entity type is required")
|
|
567
|
+
|
|
568
|
+
|
|
569
|
+
def _operation_signature(operation: MutationOperation):
|
|
570
|
+
return (
|
|
571
|
+
operation.kind.value,
|
|
572
|
+
operation.entity,
|
|
573
|
+
_freeze_value(operation.entity_id),
|
|
574
|
+
operation.original_version,
|
|
575
|
+
tuple(
|
|
576
|
+
(key, _freeze_value(value))
|
|
577
|
+
for key, value in sorted(operation.changed_values.items())
|
|
578
|
+
),
|
|
579
|
+
)
|
|
580
|
+
|
|
581
|
+
|
|
582
|
+
def _freeze_value(value: Optional[Value]):
|
|
583
|
+
if value is None:
|
|
584
|
+
return None
|
|
585
|
+
raw = value.val
|
|
586
|
+
hint = getattr(getattr(value, "_type_hint", None), "name", None)
|
|
587
|
+
return (hint, _freeze_raw(raw))
|
|
588
|
+
|
|
589
|
+
|
|
590
|
+
def _freeze_raw(value: Any):
|
|
591
|
+
if isinstance(value, Value):
|
|
592
|
+
return _freeze_value(value)
|
|
593
|
+
if isinstance(value, Mapping):
|
|
594
|
+
return tuple((str(key), _freeze_raw(item)) for key, item in sorted(value.items()))
|
|
595
|
+
if isinstance(value, (list, tuple)):
|
|
596
|
+
return tuple(_freeze_raw(item) for item in value)
|
|
597
|
+
if isinstance(value, Timestamp):
|
|
598
|
+
return ("timestamp", value.millis)
|
|
599
|
+
if isinstance(value, (date, datetime)):
|
|
600
|
+
return (type(value).__name__, value.isoformat())
|
|
601
|
+
if isinstance(value, Decimal):
|
|
602
|
+
return ("decimal", str(value))
|
|
603
|
+
if hasattr(value, "id"):
|
|
604
|
+
return (type(value).__name__, _freeze_raw(getattr(value, "id")))
|
|
605
|
+
if isinstance(value, (str, int, float, bool, type(None))):
|
|
606
|
+
return value
|
|
607
|
+
return (type(value).__name__, repr(value))
|
|
@@ -53,6 +53,13 @@ def _intent_bindings(compiled, request):
|
|
|
53
53
|
sql_origin='generated')
|
|
54
54
|
|
|
55
55
|
|
|
56
|
+
class _NoopContextManager:
|
|
57
|
+
def __enter__(self):
|
|
58
|
+
return self
|
|
59
|
+
|
|
60
|
+
def __exit__(self, exc_type, exc_value, traceback):
|
|
61
|
+
return False
|
|
62
|
+
|
|
56
63
|
def _canonical_id_set_value(value):
|
|
57
64
|
if isinstance(value, Value):
|
|
58
65
|
return ("Value", str(value._type_hint), _canonical_id_set_value(value.val))
|
|
@@ -670,16 +677,23 @@ class SqlDataServiceExecutor(QueryExecutor, MutationExecutor):
|
|
|
670
677
|
entity = getattr(request._data, "entity", "unknown")
|
|
671
678
|
kind = type(request._data).__name__.replace("Command", "").lower()
|
|
672
679
|
if context is not None:
|
|
673
|
-
context.
|
|
680
|
+
if not context.consume_mutation_checked(request._data):
|
|
681
|
+
context.check_and_fix_mutation(request._data)
|
|
674
682
|
telemetry = context.runtime_telemetry() if context is not None else None
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
"teaql.mutation.kind": kind,
|
|
680
|
-
}),
|
|
681
|
-
lambda: self._mutate(context, request),
|
|
683
|
+
scope = (
|
|
684
|
+
context.mutation_policy_execution(request)
|
|
685
|
+
if context is not None
|
|
686
|
+
else _NoopContextManager()
|
|
682
687
|
)
|
|
688
|
+
with scope:
|
|
689
|
+
return await observe_runtime_operation(
|
|
690
|
+
telemetry,
|
|
691
|
+
RuntimeOperation("mutation", f"{entity}.{kind}", {
|
|
692
|
+
"teaql.entity.type": entity,
|
|
693
|
+
"teaql.mutation.kind": kind,
|
|
694
|
+
}),
|
|
695
|
+
lambda: self._mutate(context, request),
|
|
696
|
+
)
|
|
683
697
|
|
|
684
698
|
async def _mutate(self, context: 'UserContext', request: MutationRequest) -> MutationResult:
|
|
685
699
|
if isinstance(self.transport, SqlTransactionTransport):
|
|
@@ -855,6 +869,7 @@ class SqlDataServiceExecutor(QueryExecutor, MutationExecutor):
|
|
|
855
869
|
tuple(request.trace_chain()),
|
|
856
870
|
context.user_identifier(),
|
|
857
871
|
context.get_resource("bootstrapCategory"),
|
|
872
|
+
context.current_mutation_governance(),
|
|
858
873
|
))
|
|
859
874
|
return MutationResult(
|
|
860
875
|
affected_rows=affected_rows,
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: teaql
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.9
|
|
4
4
|
Summary: TeaQL Runtime and Data Service for Python
|
|
5
5
|
Author: TeaQL
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -104,6 +104,11 @@ The SDK's organizational architecture strictly mirrors the Rust version:
|
|
|
104
104
|
* **Facet Aggregation & Grouping**: Out-of-the-box support for multi-dimensional facet aggregations, group-bys, and hierarchical data processing.
|
|
105
105
|
* **Provider Support**: Highly extensible asynchronous database connectivity (integrating third-party async drivers like `aiosqlite` through a unified Transport layer).
|
|
106
106
|
* **Context & Logging Management**: Built-in support for lifecycle context passing, end-to-end tracing, and SQL execution log interception and dispatch.
|
|
107
|
+
* **Governed Mutation Policy**: An application-owned policy can review an
|
|
108
|
+
immutable whole-graph plan after Checker/Fix and before the first provider
|
|
109
|
+
mutation. Exact policy identity and approval state are retained with audit
|
|
110
|
+
evidence. Missing customer policy or approval emits stable warnings without
|
|
111
|
+
changing persistence semantics; an explicit denial fails closed.
|
|
107
112
|
* **TeaQL Federal Protocol Client**: `TeaQLFederalClient` and `TfpHttpProvider`
|
|
108
113
|
execute governed canonical TFP v1 queries and audited mutations against a
|
|
109
114
|
remote TeaQL endpoint such as Rust. Direct query execution returns
|
|
@@ -143,5 +148,25 @@ development-only acknowledgement are maintained in the canonical
|
|
|
143
148
|
Opaque tokens never replace the backend's authorization, tenant, ownership,
|
|
144
149
|
role, or optimistic-version checks.
|
|
145
150
|
|
|
151
|
+
### Mutation Policy installation
|
|
152
|
+
|
|
153
|
+
Policy implementations are installed from trusted application startup through
|
|
154
|
+
`UserContext`; request JSON cannot select or replace them. Built-in SQL and TFP
|
|
155
|
+
providers enter the same governed boundary.
|
|
156
|
+
|
|
157
|
+
```python
|
|
158
|
+
context = (
|
|
159
|
+
UserContext.new()
|
|
160
|
+
.with_mutation_policy_registry(policy_registry)
|
|
161
|
+
.with_mutation_policy_approval_provider(approval_provider)
|
|
162
|
+
.with_mutation_governance_sink(warning_sink)
|
|
163
|
+
)
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Generated graph saves call `preflight_mutation(...)` for every operation before
|
|
167
|
+
the first provider write. See the repeatable
|
|
168
|
+
[`examples/mutation-policy`](examples/mutation-policy) example for allow,
|
|
169
|
+
approval, audit propagation, and zero-write denial evidence.
|
|
170
|
+
|
|
146
171
|
---
|
|
147
172
|
To run test validations and business logic simulations locally, simply run `pytest` in the project root.
|
|
@@ -45,6 +45,7 @@ src/teaql/runtime/env.py
|
|
|
45
45
|
src/teaql/runtime/i18n.py
|
|
46
46
|
src/teaql/runtime/log_privacy.py
|
|
47
47
|
src/teaql/runtime/module.py
|
|
48
|
+
src/teaql/runtime/mutation_policy.py
|
|
48
49
|
src/teaql/runtime/opentelemetry.py
|
|
49
50
|
src/teaql/runtime/store.py
|
|
50
51
|
src/teaql/runtime/telemetry.py
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|