teaql 0.2.7__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 (63) hide show
  1. {teaql-0.2.7 → teaql-0.2.9}/PKG-INFO +26 -1
  2. {teaql-0.2.7 → teaql-0.2.9}/README.md +25 -0
  3. {teaql-0.2.7 → teaql-0.2.9}/pyproject.toml +1 -1
  4. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/dynamic_search.py +2 -2
  5. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/meta.py +10 -1
  6. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/data_service/__init__.py +14 -0
  7. teaql-0.2.9/src/teaql/provider/mysql/dialect.py +13 -0
  8. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/mysql/transport.py +47 -2
  9. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/postgres/dialect.py +1 -1
  10. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/postgres/transport.py +46 -2
  11. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/tfp_client/__init__.py +26 -21
  12. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/__init__.py +32 -0
  13. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/audit.py +12 -8
  14. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/context.py +76 -10
  15. teaql-0.2.9/src/teaql/runtime/log_privacy.py +195 -0
  16. teaql-0.2.9/src/teaql/runtime/mutation_policy.py +607 -0
  17. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/sql/dialect.py +58 -22
  18. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/sql/executor.py +216 -100
  19. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/sql/types.py +62 -5
  20. {teaql-0.2.7 → teaql-0.2.9}/src/teaql.egg-info/PKG-INFO +26 -1
  21. {teaql-0.2.7 → teaql-0.2.9}/src/teaql.egg-info/SOURCES.txt +1 -0
  22. teaql-0.2.7/src/teaql/provider/mysql/dialect.py +0 -31
  23. teaql-0.2.7/src/teaql/runtime/log_privacy.py +0 -93
  24. {teaql-0.2.7 → teaql-0.2.9}/LICENSE +0 -0
  25. {teaql-0.2.7 → teaql-0.2.9}/setup.cfg +0 -0
  26. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/__init__.py +0 -0
  27. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/__init__.py +0 -0
  28. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/entity.py +0 -0
  29. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/eval.py +0 -0
  30. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/expr.py +0 -0
  31. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/graph.py +0 -0
  32. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/list.py +0 -0
  33. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/mutation.py +0 -0
  34. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/query.py +0 -0
  35. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/safe_expression.py +0 -0
  36. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/value.py +0 -0
  37. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/core/xls.py +0 -0
  38. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/__init__.py +0 -0
  39. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/mysql/__init__.py +0 -0
  40. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/postgres/__init__.py +0 -0
  41. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/redis/__init__.py +0 -0
  42. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/redis/remote.py +0 -0
  43. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/redis/store.py +0 -0
  44. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/sqlite/__init__.py +0 -0
  45. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/sqlite/dialect.py +0 -0
  46. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/provider/sqlite/transport.py +0 -0
  47. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/py.typed +0 -0
  48. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/_schema_capability.py +0 -0
  49. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/builtin-messages-v1.json +0 -0
  50. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/env.py +0 -0
  51. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/i18n.py +0 -0
  52. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/module.py +0 -0
  53. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/opentelemetry.py +0 -0
  54. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/store.py +0 -0
  55. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/telemetry.py +0 -0
  56. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/tools.py +0 -0
  57. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/runtime/wire_fields.py +0 -0
  58. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/sql/__init__.py +0 -0
  59. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/web_integration/__init__.py +0 -0
  60. {teaql-0.2.7 → teaql-0.2.9}/src/teaql/web_integration/fastapi/__init__.py +0 -0
  61. {teaql-0.2.7 → teaql-0.2.9}/src/teaql.egg-info/dependency_links.txt +0 -0
  62. {teaql-0.2.7 → teaql-0.2.9}/src/teaql.egg-info/requires.txt +0 -0
  63. {teaql-0.2.7 → 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.7
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.7"
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"
@@ -17,8 +17,8 @@ def _reject_json_constant(_):
17
17
 
18
18
 
19
19
  def _warning(warning):
20
- _LOG.warning('%s entity=%s clause=%s fieldPath=%s', warning['code'],
21
- warning['entity'], warning['clause'], warning['fieldPath'])
20
+ _LOG.warning('%s entity=%s clause=%s fieldPath=<omitted>', warning['code'],
21
+ warning['entity'], warning['clause'])
22
22
 
23
23
 
24
24
  def normalize_dynamic_search(source, entity, models, warn=_warning, max_clauses=100):
@@ -6,6 +6,13 @@ class PropertyDescriptor:
6
6
  self._is_id = False
7
7
  self._is_version = False
8
8
  self.nullable = True
9
+ self.log_policy_val = 'unknown'
10
+ def log_policy(self, policy):
11
+ """Trusted schema policy; incoming requests cannot override it."""
12
+ if policy not in ('plain', 'masked', 'credential', 'unknown'):
13
+ raise ValueError('invalid SQL parameter log policy')
14
+ self.log_policy_val = policy
15
+ return self
9
16
  def column_name(self, name):
10
17
  self.column_name_val = name
11
18
  return self
@@ -46,6 +53,7 @@ class EntityDescriptor:
46
53
  self.properties = []
47
54
  self.relations = []
48
55
  self.audit_mask_fields_val = []
56
+ self.audit_mask_fields_declared = False
49
57
  self.audit_value_max_len_val = None
50
58
  def table_name(self, name):
51
59
  self.table_name_val = name
@@ -65,7 +73,8 @@ class EntityDescriptor:
65
73
  return next((prop for prop in self.properties if prop.name == name), None)
66
74
 
67
75
  def audit_mask_fields(self, fields):
68
- self.audit_mask_fields_val = list(fields)
76
+ self.audit_mask_fields_val = list(fields) if fields is not None else []
77
+ self.audit_mask_fields_declared = fields is not None
69
78
  return self
70
79
 
71
80
  def audit_value_max_len(self, max_len):
@@ -32,6 +32,15 @@ class QueryRequest:
32
32
  _comment: Optional[str] = None
33
33
  _purpose: Optional[str] = None
34
34
 
35
+ def __post_init__(self) -> None:
36
+ # Older generated wrappers store intent on SelectQuery but construct
37
+ # QueryRequest(query) without forwarding it. Keep the explicit request
38
+ # values authoritative while preserving their diagnostic intent.
39
+ if self._comment is None:
40
+ self._comment = getattr(self.query, 'comment_text', None)
41
+ if self._purpose is None:
42
+ self._purpose = getattr(self.query, 'purpose_text', None)
43
+
35
44
  def comment(self, text: str) -> 'QueryRequest':
36
45
  if not text:
37
46
  raise ValueError("comment cannot be empty")
@@ -71,6 +80,11 @@ class ExecutionMetadata:
71
80
  audit_reason: Optional[str] = None
72
81
  backend_request_id: Optional[str] = None
73
82
  debug_query: Optional[str] = None
83
+ database_kind: Any = None
84
+ parameter_log_policies: Optional[List[str]] = None
85
+ sql_origin: Optional[str] = None
86
+ # Statement/cursor termination only, not transaction commit.
87
+ execution_outcome: Optional[str] = None
74
88
 
75
89
 
76
90
  @dataclass
@@ -0,0 +1,13 @@
1
+ from teaql.sql.dialect import SqlDialect, quote_identifier_if_needed
2
+ from teaql.sql.types import DatabaseKind
3
+
4
+
5
+ class MysqlDialect(SqlDialect):
6
+ def kind(self) -> DatabaseKind:
7
+ return DatabaseKind.MySql
8
+
9
+ def quote_ident(self, ident: str) -> str:
10
+ return quote_identifier_if_needed(ident, "`")
11
+
12
+ def placeholder(self, index: int) -> str:
13
+ return "%s"
@@ -3,11 +3,11 @@ import aiomysql
3
3
  from decimal import Decimal
4
4
  from datetime import date, datetime, timezone
5
5
  from typing import List, Dict, Any, Optional, AsyncIterator
6
- from teaql.sql.executor import SqlTransport
6
+ from teaql.sql.executor import SqlTransactionTransport, SqlTransactionTransportTx
7
7
  from teaql.sql.types import CompiledQuery
8
8
  from teaql.core.value import Value, DataType, Timestamp
9
9
 
10
- class MysqlTransport(SqlTransport):
10
+ class MysqlTransport(SqlTransactionTransport):
11
11
  def __init__(self, db_url: str):
12
12
  self.db_url = db_url
13
13
 
@@ -99,3 +99,48 @@ class MysqlTransport(SqlTransport):
99
99
  return cur.rowcount, cur.lastrowid
100
100
  finally:
101
101
  conn.close()
102
+
103
+ async def begin_sql(self) -> SqlTransactionTransportTx:
104
+ user, password, host, port, db = self._parse_url()
105
+ conn = await aiomysql.connect(
106
+ host=host, port=port, user=user, password=password, db=db,
107
+ cursorclass=aiomysql.DictCursor, autocommit=False,
108
+ )
109
+ try:
110
+ await conn.begin()
111
+ return _MysqlTransaction(conn, self)
112
+ except BaseException:
113
+ conn.close()
114
+ raise
115
+
116
+
117
+ class _MysqlTransaction(SqlTransactionTransportTx):
118
+ def __init__(self, conn, owner: MysqlTransport):
119
+ self._conn = conn
120
+ self._owner = owner
121
+
122
+ async def fetch_all_sql(self, query: CompiledQuery) -> List[Dict[str, Any]]:
123
+ async with self._conn.cursor() as cursor:
124
+ await cursor.execute(query.sql_with_comment(), self._owner._bind_values(query.params))
125
+ rows = await cursor.fetchall()
126
+ return [
127
+ {key: self._owner._decode_value(value) for key, value in row.items()}
128
+ for row in rows
129
+ ]
130
+
131
+ async def execute_sql(self, query: CompiledQuery) -> tuple[int, int]:
132
+ async with self._conn.cursor() as cursor:
133
+ await cursor.execute(query.sql_with_comment(), self._owner._bind_values(query.params))
134
+ return cursor.rowcount, cursor.lastrowid
135
+
136
+ async def commit_sql(self) -> None:
137
+ try:
138
+ await self._conn.commit()
139
+ finally:
140
+ self._conn.close()
141
+
142
+ async def rollback_sql(self) -> None:
143
+ try:
144
+ await self._conn.rollback()
145
+ finally:
146
+ self._conn.close()
@@ -5,7 +5,7 @@ from teaql.core.meta import PropertyDescriptor
5
5
 
6
6
  class PostgresDialect(SqlDialect):
7
7
  def kind(self) -> DatabaseKind:
8
- return DatabaseKind.Postgres
8
+ return DatabaseKind.PostgreSql
9
9
 
10
10
  def quote_ident(self, ident: str) -> str:
11
11
  return quote_identifier_if_needed(ident, '"')
@@ -3,11 +3,11 @@ import asyncpg
3
3
  from decimal import Decimal
4
4
  from datetime import date, datetime, timezone
5
5
  from typing import List, Dict, Any, Optional, AsyncIterator
6
- from teaql.sql.executor import SqlTransport
6
+ from teaql.sql.executor import SqlTransactionTransport, SqlTransactionTransportTx
7
7
  from teaql.sql.types import CompiledQuery
8
8
  from teaql.core.value import Value, DataType, Timestamp
9
9
 
10
- class PostgresTransport(SqlTransport):
10
+ class PostgresTransport(SqlTransactionTransport):
11
11
  def __init__(self, db_url: str):
12
12
  self.db_url = db_url
13
13
 
@@ -88,3 +88,47 @@ class PostgresTransport(SqlTransport):
88
88
  return affected_rows, 0
89
89
  finally:
90
90
  await conn.close()
91
+
92
+ async def begin_sql(self) -> SqlTransactionTransportTx:
93
+ conn = await asyncpg.connect(self.db_url)
94
+ try:
95
+ transaction = conn.transaction()
96
+ await transaction.start()
97
+ return _PostgresTransaction(conn, transaction, self)
98
+ except BaseException:
99
+ await conn.close()
100
+ raise
101
+
102
+
103
+ class _PostgresTransaction(SqlTransactionTransportTx):
104
+ def __init__(self, conn, transaction, owner: PostgresTransport):
105
+ self._conn = conn
106
+ self._transaction = transaction
107
+ self._owner = owner
108
+
109
+ async def fetch_all_sql(self, query: CompiledQuery) -> List[Dict[str, Any]]:
110
+ rows = await self._conn.fetch(query.sql_with_comment(), *self._owner._bind_values(query.params))
111
+ return [
112
+ {key: self._owner._decode_value(value) for key, value in row.items()}
113
+ for row in rows
114
+ ]
115
+
116
+ async def execute_sql(self, query: CompiledQuery) -> tuple[int, int]:
117
+ status = await self._conn.execute(query.sql_with_comment(), *self._owner._bind_values(query.params))
118
+ if status.startswith("INSERT "):
119
+ return int(status.split()[-1]), 0
120
+ if status.startswith(("UPDATE ", "DELETE ")):
121
+ return int(status.split()[-1]), 0
122
+ return 0, 0
123
+
124
+ async def commit_sql(self) -> None:
125
+ try:
126
+ await self._transaction.commit()
127
+ finally:
128
+ await self._conn.close()
129
+
130
+ async def rollback_sql(self) -> None:
131
+ try:
132
+ await self._transaction.rollback()
133
+ finally:
134
+ await self._conn.close()
@@ -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
@@ -35,22 +36,23 @@ class RawAuditEvent:
35
36
  fields = []
36
37
  for change in self.changes:
37
38
  value = None if change.new_value is None else str(getattr(change.new_value, "val", change.new_value))
38
- masked = (credential_name(change.field)
39
- or payload_has_credentials(change.new_value)
40
- or payload_has_credentials(change.old_value)
41
- or (change.field in mask_fields and not allow))
39
+ credential = (credential_name(change.field)
40
+ or payload_has_credentials(change.new_value)
41
+ or payload_has_credentials(change.old_value))
42
+ masked = credential or (change.field in mask_fields and not allow)
42
43
  if masked:
43
44
  secrets.extend(value_strings(change.old_value))
44
45
  secrets.extend(value_strings(change.new_value))
45
46
  if value is not None and masked:
46
- value = REDACTED
47
+ value = REDACTED if credential else _mask(value)
47
48
  truncated = value is not None and max_length is not None and len(value) > max_length
48
49
  if truncated:
49
50
  value = "*" * max_length if max_length <= 3 else value[:max_length - 3] + "..."
50
51
  fields.append(SafeAuditField(change.field, value, masked, truncated))
52
+ intent_values = secrets + value_strings(self.entity_id)
51
53
  return SafeAuditEvent(
52
- self.kind, self.entity, self.entity_id, scrub(tuple(fields), secrets), scrub(self.trace_chain, secrets),
53
- scrub(self.actor, secrets), self.category,
54
+ self.kind, self.entity, self.entity_id, scrub(tuple(fields), secrets), scrub(self.trace_chain, intent_values),
55
+ scrub(self.actor, intent_values), self.category, self.mutation_governance,
54
56
  )
55
57
 
56
58
 
@@ -71,10 +73,12 @@ class SafeAuditEvent:
71
73
  trace_chain: tuple[Any, ...] = field(default_factory=tuple)
72
74
  actor: Optional[str] = None
73
75
  category: Optional[str] = None
76
+ mutation_governance: Any = None
74
77
 
75
78
 
76
79
  def _mask(value: str) -> str:
77
- if len(value) < 8:
80
+ # Unicode scalar length, ASCII digits: the same contract as Rust and Go.
81
+ if len(value) < 8 or (value.isascii() and value.isdigit()):
78
82
  return "*" * len(value)
79
83
  return value[:2] + "*" * (len(value) - 4) + value[-2:]
80
84
 
@@ -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
@@ -705,6 +745,10 @@ class UserContext:
705
745
  return self.get_resource("locale") or Locale.ENGLISH
706
746
 
707
747
  def record_metadata_log(self, metadata: Any):
748
+ self._record_metadata_log(metadata)
749
+
750
+ def _record_metadata_log(self, metadata: Any, *, intent_source=None, intent_values=()):
751
+ """Internal statement plumbing: source bindings never reach sinks/buffers."""
708
752
  op = SqlLogOperation.Select
709
753
  op_str = str(getattr(metadata, 'operation', '')).lower()
710
754
  if 'insert' in op_str: op = SqlLogOperation.Insert
@@ -726,6 +770,10 @@ class UserContext:
726
770
  params=list(getattr(metadata, 'parameters', [])),
727
771
  debug_sql=getattr(metadata, 'debug_query', '') or '',
728
772
  pretty_sql=getattr(metadata, 'debug_query', '') or '',
773
+ database_kind=getattr(metadata, 'database_kind', None),
774
+ parameter_log_policies=getattr(metadata, 'parameter_log_policies', None),
775
+ sql_origin=getattr(metadata, 'sql_origin', None),
776
+ execution_outcome=getattr(metadata, 'execution_outcome', None),
729
777
  started_at=started_at,
730
778
  ended_at=ended_at,
731
779
  elapsed=ended_at - started_at,
@@ -740,13 +788,11 @@ class UserContext:
740
788
  entry.result_summary = f"{entry.affected_rows} rows affected"
741
789
 
742
790
  from .log_privacy import sql_log_projection
743
- entry = sql_log_projection(entry)
791
+ entry = sql_log_projection(entry, _intent_source=intent_source, _intent_values=intent_values)
744
792
  logs = self.sql_logs()
745
793
  logs.append(entry)
746
794
  self._resources["sql_logs"] = logs
747
- sink = self.get_resource("diagnostic_sql_log_sink")
748
- if sink is not None:
749
- sink.write(entry)
795
+ self._write_diagnostic_sql_log(entry)
750
796
  buf = self.get_resource("UnifiedLogBuffer")
751
797
  if buf:
752
798
  buf.entries.append(UnifiedLogEntry(
@@ -760,7 +806,8 @@ class UserContext:
760
806
  if not self.sql_log_options().enabled_for(operation):
761
807
  return
762
808
 
763
- debug_sql = getattr(query, 'debug_sql', lambda *args: "")() if hasattr(query, 'debug_sql') else getattr(query, 'sql', "")
809
+ # Projection renders only safe values. Never materialize plaintext first.
810
+ debug_sql = ''
764
811
 
765
812
  entry = SqlLogEntry(
766
813
  operation=operation,
@@ -772,6 +819,9 @@ class UserContext:
772
819
  params=getattr(query, 'params', []),
773
820
  debug_sql=debug_sql,
774
821
  pretty_sql=debug_sql,
822
+ database_kind=getattr(query, 'database_kind', None),
823
+ parameter_log_policies=getattr(query, 'parameter_log_policies', None),
824
+ sql_origin=getattr(query, 'sql_origin', None),
775
825
  started_at=started_at,
776
826
  ended_at=ended_at,
777
827
  elapsed=elapsed,
@@ -791,9 +841,7 @@ class UserContext:
791
841
  logs = self.sql_logs()
792
842
  logs.append(entry)
793
843
  self._resources["sql_logs"] = logs
794
- sink = self.get_resource("diagnostic_sql_log_sink")
795
- if sink is not None:
796
- sink.write(entry)
844
+ self._write_diagnostic_sql_log(entry)
797
845
 
798
846
  buf = self.get_resource("UnifiedLogBuffer")
799
847
  if buf:
@@ -804,6 +852,17 @@ class UserContext:
804
852
  payload=LogPayload.Sql(entry)
805
853
  ))
806
854
 
855
+ def _write_diagnostic_sql_log(self, entry: 'SqlLogEntry'):
856
+ sink = self.get_resource("diagnostic_sql_log_sink")
857
+ if sink is None:
858
+ return
859
+ try:
860
+ sink.write(entry)
861
+ except Exception:
862
+ # An optional diagnostic destination must not change SQL outcomes.
863
+ # Do not print the exception: custom sinks may include raw values.
864
+ pass
865
+
807
866
  def register_executor(self, executor: Any):
808
867
  self.insert_resource("executor", executor)
809
868
 
@@ -1035,6 +1094,13 @@ class SqlLogEntry:
1035
1094
  result_type: Optional[str]
1036
1095
  affected_rows: Optional[int]
1037
1096
  result_summary: str
1097
+ database_kind: Any = None
1098
+ parameter_log_policies: Optional[List[str]] = None
1099
+ sql_origin: Optional[str] = None
1100
+ masked_parameters: Optional[List[bool]] = None
1101
+ log_mode: Optional[str] = None
1102
+ omission_reason: Optional[str] = None
1103
+ execution_outcome: Optional[str] = None
1038
1104
 
1039
1105
  class DiagnosticSqlLogSink:
1040
1106
  """Policy-projected SQL destination; the text sink is installed by default."""
@@ -1051,9 +1117,9 @@ class TextDiagnosticSqlLogSink(DiagnosticSqlLogSink):
1051
1117
  elapsed_us = int(entry.elapsed.total_seconds() * 1_000_000) if entry.elapsed else 0
1052
1118
  self._writer(
1053
1119
  f"[TeaQL SQL][{entry.operation.name.lower()}][{elapsed_us}us] "
1054
- f"{entry.result_summary} comment={entry.comment!r} purpose={entry.purpose!r} "
1120
+ f"{entry.result_summary} outcome={entry.execution_outcome or 'unknown'} comment={entry.comment!r} purpose={entry.purpose!r} "
1055
1121
  f"auditReason={entry.audit_reason!r} tracePath={entry.trace_path!r}\n"
1056
- f"Parameterized SQL: {entry.sql} params={entry.params!r}\n"
1122
+ f"SQL omission reason: {entry.omission_reason or 'none'}\n"
1057
1123
  f"Debug SQL: {entry.debug_sql}"
1058
1124
  )
1059
1125