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.
Files changed (61) hide show
  1. {teaql-0.2.8 → teaql-0.2.9}/PKG-INFO +26 -1
  2. {teaql-0.2.8 → teaql-0.2.9}/README.md +25 -0
  3. {teaql-0.2.8 → teaql-0.2.9}/pyproject.toml +1 -1
  4. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/tfp_client/__init__.py +26 -21
  5. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/__init__.py +32 -0
  6. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/audit.py +3 -1
  7. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/context.py +40 -0
  8. teaql-0.2.9/src/teaql/runtime/mutation_policy.py +607 -0
  9. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/sql/executor.py +23 -8
  10. {teaql-0.2.8 → teaql-0.2.9}/src/teaql.egg-info/PKG-INFO +26 -1
  11. {teaql-0.2.8 → teaql-0.2.9}/src/teaql.egg-info/SOURCES.txt +1 -0
  12. {teaql-0.2.8 → teaql-0.2.9}/LICENSE +0 -0
  13. {teaql-0.2.8 → teaql-0.2.9}/setup.cfg +0 -0
  14. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/__init__.py +0 -0
  15. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/__init__.py +0 -0
  16. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/dynamic_search.py +0 -0
  17. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/entity.py +0 -0
  18. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/eval.py +0 -0
  19. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/expr.py +0 -0
  20. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/graph.py +0 -0
  21. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/list.py +0 -0
  22. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/meta.py +0 -0
  23. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/mutation.py +0 -0
  24. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/query.py +0 -0
  25. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/safe_expression.py +0 -0
  26. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/value.py +0 -0
  27. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/core/xls.py +0 -0
  28. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/data_service/__init__.py +0 -0
  29. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/__init__.py +0 -0
  30. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/mysql/__init__.py +0 -0
  31. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/mysql/dialect.py +0 -0
  32. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/mysql/transport.py +0 -0
  33. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/postgres/__init__.py +0 -0
  34. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/postgres/dialect.py +0 -0
  35. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/postgres/transport.py +0 -0
  36. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/redis/__init__.py +0 -0
  37. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/redis/remote.py +0 -0
  38. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/redis/store.py +0 -0
  39. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/sqlite/__init__.py +0 -0
  40. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/sqlite/dialect.py +0 -0
  41. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/provider/sqlite/transport.py +0 -0
  42. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/py.typed +0 -0
  43. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/_schema_capability.py +0 -0
  44. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/builtin-messages-v1.json +0 -0
  45. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/env.py +0 -0
  46. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/i18n.py +0 -0
  47. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/log_privacy.py +0 -0
  48. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/module.py +0 -0
  49. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/opentelemetry.py +0 -0
  50. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/store.py +0 -0
  51. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/telemetry.py +0 -0
  52. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/tools.py +0 -0
  53. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/runtime/wire_fields.py +0 -0
  54. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/sql/__init__.py +0 -0
  55. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/sql/dialect.py +0 -0
  56. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/sql/types.py +0 -0
  57. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/web_integration/__init__.py +0 -0
  58. {teaql-0.2.8 → teaql-0.2.9}/src/teaql/web_integration/fastapi/__init__.py +0 -0
  59. {teaql-0.2.8 → teaql-0.2.9}/src/teaql.egg-info/dependency_links.txt +0 -0
  60. {teaql-0.2.8 → teaql-0.2.9}/src/teaql.egg-info/requires.txt +0 -0
  61. {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.8
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.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "teaql"
7
- version = "0.2.8"
7
+ version = "0.2.9"
8
8
  description = "TeaQL Runtime and Data Service for Python"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -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
- started_at = datetime.now()
168
- federal = _mutation_request(request)
169
- data = await self.federal_client.execute_mutation(federal)
170
- records = data.get("data") or []
171
- generated = records[0] if records else {}
172
- affected = int(data.get("affectedRows", 0))
173
- operation = {
174
- "Create": DataServiceOperation.Insert,
175
- "Update": DataServiceOperation.Update,
176
- "Delete": DataServiceOperation.Delete,
177
- "Recover": DataServiceOperation.Recover,
178
- }[federal.action]
179
- return MutationResult(
180
- affected_rows=affected, generated_values=generated,
181
- persisted_record=generated or None,
182
- metadata=ExecutionMetadata(
183
- backend="teaql-federal", operation=operation,
184
- started_at=started_at, ended_at=datetime.now(), affected_rows=affected,
185
- comment=federal.comment,
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.check_and_fix_mutation(request._data)
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
- return await observe_runtime_operation(
676
- telemetry,
677
- RuntimeOperation("mutation", f"{entity}.{kind}", {
678
- "teaql.entity.type": entity,
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.8
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