teaql 0.2.6__tar.gz → 0.2.8__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.6 → teaql-0.2.8}/PKG-INFO +44 -1
  2. {teaql-0.2.6 → teaql-0.2.8}/README.md +43 -0
  3. {teaql-0.2.6 → teaql-0.2.8}/pyproject.toml +1 -1
  4. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/core/dynamic_search.py +2 -2
  5. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/core/meta.py +10 -1
  6. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/data_service/__init__.py +14 -0
  7. teaql-0.2.8/src/teaql/provider/mysql/dialect.py +13 -0
  8. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/provider/mysql/transport.py +47 -2
  9. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/provider/postgres/dialect.py +1 -1
  10. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/provider/postgres/transport.py +46 -2
  11. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/runtime/audit.py +16 -5
  12. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/runtime/context.py +43 -11
  13. teaql-0.2.8/src/teaql/runtime/log_privacy.py +195 -0
  14. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/sql/dialect.py +58 -22
  15. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/sql/executor.py +193 -92
  16. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/sql/types.py +62 -5
  17. {teaql-0.2.6 → teaql-0.2.8}/src/teaql.egg-info/PKG-INFO +44 -1
  18. {teaql-0.2.6 → teaql-0.2.8}/src/teaql.egg-info/SOURCES.txt +1 -0
  19. teaql-0.2.6/src/teaql/provider/mysql/dialect.py +0 -31
  20. {teaql-0.2.6 → teaql-0.2.8}/LICENSE +0 -0
  21. {teaql-0.2.6 → teaql-0.2.8}/setup.cfg +0 -0
  22. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/__init__.py +0 -0
  23. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/core/__init__.py +0 -0
  24. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/core/entity.py +0 -0
  25. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/core/eval.py +0 -0
  26. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/core/expr.py +0 -0
  27. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/core/graph.py +0 -0
  28. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/core/list.py +0 -0
  29. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/core/mutation.py +0 -0
  30. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/core/query.py +0 -0
  31. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/core/safe_expression.py +0 -0
  32. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/core/value.py +0 -0
  33. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/core/xls.py +0 -0
  34. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/provider/__init__.py +0 -0
  35. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/provider/mysql/__init__.py +0 -0
  36. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/provider/postgres/__init__.py +0 -0
  37. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/provider/redis/__init__.py +0 -0
  38. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/provider/redis/remote.py +0 -0
  39. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/provider/redis/store.py +0 -0
  40. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/provider/sqlite/__init__.py +0 -0
  41. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/provider/sqlite/dialect.py +0 -0
  42. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/provider/sqlite/transport.py +0 -0
  43. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/provider/tfp_client/__init__.py +0 -0
  44. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/py.typed +0 -0
  45. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/runtime/__init__.py +0 -0
  46. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/runtime/_schema_capability.py +0 -0
  47. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/runtime/builtin-messages-v1.json +0 -0
  48. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/runtime/env.py +0 -0
  49. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/runtime/i18n.py +0 -0
  50. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/runtime/module.py +0 -0
  51. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/runtime/opentelemetry.py +0 -0
  52. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/runtime/store.py +0 -0
  53. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/runtime/telemetry.py +0 -0
  54. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/runtime/tools.py +0 -0
  55. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/runtime/wire_fields.py +0 -0
  56. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/sql/__init__.py +0 -0
  57. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/web_integration/__init__.py +0 -0
  58. {teaql-0.2.6 → teaql-0.2.8}/src/teaql/web_integration/fastapi/__init__.py +0 -0
  59. {teaql-0.2.6 → teaql-0.2.8}/src/teaql.egg-info/dependency_links.txt +0 -0
  60. {teaql-0.2.6 → teaql-0.2.8}/src/teaql.egg-info/requires.txt +0 -0
  61. {teaql-0.2.6 → teaql-0.2.8}/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.6
3
+ Version: 0.2.8
4
4
  Summary: TeaQL Runtime and Data Service for Python
5
5
  Author: TeaQL
6
6
  License-Expression: Apache-2.0
@@ -39,6 +39,28 @@ Dynamic: license-file
39
39
 
40
40
  # TeaQL Python SDK
41
41
 
42
+ ## Sensitive log data
43
+
44
+ Runtime diagnostic logs redact payload values by default, before delivery to
45
+ file, console, buffers, or custom logging sinks. Selecting a diagnostic sink
46
+ alone does not authorize plaintext. For controlled troubleshooting only:
47
+
48
+ ```bash
49
+ export TEAQL_ALLOW_SENSITIVE_PLAINTEXT_LOGS=I_UNDERSTAND_SENSITIVE_DATA_MAY_BE_WRITTEN_TO_DISK
50
+ ```
51
+
52
+ Only this exact value enables plaintext permission; empty values, `true`, and
53
+ whitespace variants do not. Enabling it emits a warning. Credential-classified
54
+ fields remain redacted. The flag does not force every sink to expose values.
55
+ SQL without reliable field/literal provenance may be suppressed and marked
56
+ `NOT REPLAYABLE`. Execution parameters and persisted business data are unchanged.
57
+
58
+ Do not put sensitive data in free-text comments or purpose declarations.
59
+ TeaQL cannot govern arbitrary application prints or independent driver loggers;
60
+ configure those separately. This setting does not erase older plaintext files.
61
+ Restrict access and retention when using plaintext diagnostics, then unset the
62
+ variable and restart processes when troubleshooting is complete.
63
+
42
64
  TeaQL Python SDK is a runtime engine and toolkit for building data-driven business applications. It provides seamless integration with the TeaQL ecosystem, fully aligned with the `teaql-rs` baseline.
43
65
 
44
66
  ## Recommended Agent Harness
@@ -100,5 +122,26 @@ orders = await client.execute_query(FederalQuery(
100
122
  await client.aclose()
101
123
  ```
102
124
 
125
+ ## Security Foundation Status
126
+
127
+ Python currently provides governed local SQL execution and a **TFP client**;
128
+ it does not claim a public TFP server endpoint. Application queries retain
129
+ non-empty comment/purpose and audited mutations retain their audit reason.
130
+ Runtime logging should keep parameterized SQL and intent separate from any
131
+ restricted value-bearing diagnostic output.
132
+
133
+ Portable `UserContext` opaque entity references are not implemented in the
134
+ Python runtime yet. Until that capability is added, applications must not
135
+ invent a Python-specific token format or serialize internal ID/version pairs as
136
+ if they were the TeaQL portable contract. A Python TFP client may carry an
137
+ opaque token issued by a trusted Java, Rust, Go, or .NET backend, but it must
138
+ not decode, rewrite, or mint that token.
139
+
140
+ The planned wire format, fail-closed behavior, shared golden vector, and exact
141
+ development-only acknowledgement are maintained in the canonical
142
+ [opaque entity reference contract](https://github.com/teaql/teaql-conformance/blob/main/design/opaque-entity-references.md).
143
+ Opaque tokens never replace the backend's authorization, tenant, ownership,
144
+ role, or optimistic-version checks.
145
+
103
146
  ---
104
147
  To run test validations and business logic simulations locally, simply run `pytest` in the project root.
@@ -1,5 +1,27 @@
1
1
  # TeaQL Python SDK
2
2
 
3
+ ## Sensitive log data
4
+
5
+ Runtime diagnostic logs redact payload values by default, before delivery to
6
+ file, console, buffers, or custom logging sinks. Selecting a diagnostic sink
7
+ alone does not authorize plaintext. For controlled troubleshooting only:
8
+
9
+ ```bash
10
+ export TEAQL_ALLOW_SENSITIVE_PLAINTEXT_LOGS=I_UNDERSTAND_SENSITIVE_DATA_MAY_BE_WRITTEN_TO_DISK
11
+ ```
12
+
13
+ Only this exact value enables plaintext permission; empty values, `true`, and
14
+ whitespace variants do not. Enabling it emits a warning. Credential-classified
15
+ fields remain redacted. The flag does not force every sink to expose values.
16
+ SQL without reliable field/literal provenance may be suppressed and marked
17
+ `NOT REPLAYABLE`. Execution parameters and persisted business data are unchanged.
18
+
19
+ Do not put sensitive data in free-text comments or purpose declarations.
20
+ TeaQL cannot govern arbitrary application prints or independent driver loggers;
21
+ configure those separately. This setting does not erase older plaintext files.
22
+ Restrict access and retention when using plaintext diagnostics, then unset the
23
+ variable and restart processes when troubleshooting is complete.
24
+
3
25
  TeaQL Python SDK is a runtime engine and toolkit for building data-driven business applications. It provides seamless integration with the TeaQL ecosystem, fully aligned with the `teaql-rs` baseline.
4
26
 
5
27
  ## Recommended Agent Harness
@@ -61,5 +83,26 @@ orders = await client.execute_query(FederalQuery(
61
83
  await client.aclose()
62
84
  ```
63
85
 
86
+ ## Security Foundation Status
87
+
88
+ Python currently provides governed local SQL execution and a **TFP client**;
89
+ it does not claim a public TFP server endpoint. Application queries retain
90
+ non-empty comment/purpose and audited mutations retain their audit reason.
91
+ Runtime logging should keep parameterized SQL and intent separate from any
92
+ restricted value-bearing diagnostic output.
93
+
94
+ Portable `UserContext` opaque entity references are not implemented in the
95
+ Python runtime yet. Until that capability is added, applications must not
96
+ invent a Python-specific token format or serialize internal ID/version pairs as
97
+ if they were the TeaQL portable contract. A Python TFP client may carry an
98
+ opaque token issued by a trusted Java, Rust, Go, or .NET backend, but it must
99
+ not decode, rewrite, or mint that token.
100
+
101
+ The planned wire format, fail-closed behavior, shared golden vector, and exact
102
+ development-only acknowledgement are maintained in the canonical
103
+ [opaque entity reference contract](https://github.com/teaql/teaql-conformance/blob/main/design/opaque-entity-references.md).
104
+ Opaque tokens never replace the backend's authorization, tenant, ownership,
105
+ role, or optimistic-version checks.
106
+
64
107
  ---
65
108
  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.6"
7
+ version = "0.2.8"
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()
@@ -29,19 +29,29 @@ class RawAuditEvent:
29
29
  category: Optional[str] = None
30
30
 
31
31
  def safe(self, mask_fields: List[str], max_length: Optional[int]) -> "SafeAuditEvent":
32
+ from .log_privacy import REDACTED, credential_name, payload_has_credentials, plaintext_enabled, scrub, value_strings
33
+ allow = plaintext_enabled()
34
+ secrets = []
32
35
  fields = []
33
36
  for change in self.changes:
34
37
  value = None if change.new_value is None else str(getattr(change.new_value, "val", change.new_value))
35
- masked = change.field in mask_fields
38
+ credential = (credential_name(change.field)
39
+ or payload_has_credentials(change.new_value)
40
+ or payload_has_credentials(change.old_value))
41
+ masked = credential or (change.field in mask_fields and not allow)
42
+ if masked:
43
+ secrets.extend(value_strings(change.old_value))
44
+ secrets.extend(value_strings(change.new_value))
36
45
  if value is not None and masked:
37
- value = _mask(value)
46
+ value = REDACTED if credential else _mask(value)
38
47
  truncated = value is not None and max_length is not None and len(value) > max_length
39
48
  if truncated:
40
49
  value = "*" * max_length if max_length <= 3 else value[:max_length - 3] + "..."
41
50
  fields.append(SafeAuditField(change.field, value, masked, truncated))
51
+ intent_values = secrets + value_strings(self.entity_id)
42
52
  return SafeAuditEvent(
43
- self.kind, self.entity, self.entity_id, tuple(fields), self.trace_chain,
44
- self.actor, self.category,
53
+ 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,
45
55
  )
46
56
 
47
57
 
@@ -65,7 +75,8 @@ class SafeAuditEvent:
65
75
 
66
76
 
67
77
  def _mask(value: str) -> str:
68
- if len(value) < 8:
78
+ # Unicode scalar length, ASCII digits: the same contract as Rust and Go.
79
+ if len(value) < 8 or (value.isascii() and value.isdigit()):
69
80
  return "*" * len(value)
70
81
  return value[:2] + "*" * (len(value) - 4) + value[-2:]
71
82
 
@@ -705,6 +705,10 @@ class UserContext:
705
705
  return self.get_resource("locale") or Locale.ENGLISH
706
706
 
707
707
  def record_metadata_log(self, metadata: Any):
708
+ self._record_metadata_log(metadata)
709
+
710
+ def _record_metadata_log(self, metadata: Any, *, intent_source=None, intent_values=()):
711
+ """Internal statement plumbing: source bindings never reach sinks/buffers."""
708
712
  op = SqlLogOperation.Select
709
713
  op_str = str(getattr(metadata, 'operation', '')).lower()
710
714
  if 'insert' in op_str: op = SqlLogOperation.Insert
@@ -726,6 +730,10 @@ class UserContext:
726
730
  params=list(getattr(metadata, 'parameters', [])),
727
731
  debug_sql=getattr(metadata, 'debug_query', '') or '',
728
732
  pretty_sql=getattr(metadata, 'debug_query', '') or '',
733
+ database_kind=getattr(metadata, 'database_kind', None),
734
+ parameter_log_policies=getattr(metadata, 'parameter_log_policies', None),
735
+ sql_origin=getattr(metadata, 'sql_origin', None),
736
+ execution_outcome=getattr(metadata, 'execution_outcome', None),
729
737
  started_at=started_at,
730
738
  ended_at=ended_at,
731
739
  elapsed=ended_at - started_at,
@@ -739,18 +747,18 @@ class UserContext:
739
747
  elif entry.affected_rows is not None:
740
748
  entry.result_summary = f"{entry.affected_rows} rows affected"
741
749
 
750
+ from .log_privacy import sql_log_projection
751
+ entry = sql_log_projection(entry, _intent_source=intent_source, _intent_values=intent_values)
742
752
  logs = self.sql_logs()
743
753
  logs.append(entry)
744
754
  self._resources["sql_logs"] = logs
745
- sink = self.get_resource("diagnostic_sql_log_sink")
746
- if sink is not None:
747
- sink.write(entry)
755
+ self._write_diagnostic_sql_log(entry)
748
756
  buf = self.get_resource("UnifiedLogBuffer")
749
757
  if buf:
750
758
  buf.entries.append(UnifiedLogEntry(
751
759
  timestamp=entry.started_at,
752
760
  user_identifier=self.user_identifier(),
753
- trace_chain=getattr(metadata, 'trace_chain', []),
761
+ trace_chain=entry.trace_path,
754
762
  payload=LogPayload.Sql(entry)
755
763
  ))
756
764
 
@@ -758,7 +766,8 @@ class UserContext:
758
766
  if not self.sql_log_options().enabled_for(operation):
759
767
  return
760
768
 
761
- debug_sql = getattr(query, 'debug_sql', lambda *args: "")() if hasattr(query, 'debug_sql') else getattr(query, 'sql', "")
769
+ # Projection renders only safe values. Never materialize plaintext first.
770
+ debug_sql = ''
762
771
 
763
772
  entry = SqlLogEntry(
764
773
  operation=operation,
@@ -770,6 +779,9 @@ class UserContext:
770
779
  params=getattr(query, 'params', []),
771
780
  debug_sql=debug_sql,
772
781
  pretty_sql=debug_sql,
782
+ database_kind=getattr(query, 'database_kind', None),
783
+ parameter_log_policies=getattr(query, 'parameter_log_policies', None),
784
+ sql_origin=getattr(query, 'sql_origin', None),
773
785
  started_at=started_at,
774
786
  ended_at=ended_at,
775
787
  elapsed=elapsed,
@@ -784,12 +796,12 @@ class UserContext:
784
796
  elif affected_rows is not None:
785
797
  entry.result_summary = f"{affected_rows} rows affected"
786
798
 
799
+ from .log_privacy import sql_log_projection
800
+ entry = sql_log_projection(entry)
787
801
  logs = self.sql_logs()
788
802
  logs.append(entry)
789
803
  self._resources["sql_logs"] = logs
790
- sink = self.get_resource("diagnostic_sql_log_sink")
791
- if sink is not None:
792
- sink.write(entry)
804
+ self._write_diagnostic_sql_log(entry)
793
805
 
794
806
  buf = self.get_resource("UnifiedLogBuffer")
795
807
  if buf:
@@ -800,6 +812,17 @@ class UserContext:
800
812
  payload=LogPayload.Sql(entry)
801
813
  ))
802
814
 
815
+ def _write_diagnostic_sql_log(self, entry: 'SqlLogEntry'):
816
+ sink = self.get_resource("diagnostic_sql_log_sink")
817
+ if sink is None:
818
+ return
819
+ try:
820
+ sink.write(entry)
821
+ except Exception:
822
+ # An optional diagnostic destination must not change SQL outcomes.
823
+ # Do not print the exception: custom sinks may include raw values.
824
+ pass
825
+
803
826
  def register_executor(self, executor: Any):
804
827
  self.insert_resource("executor", executor)
805
828
 
@@ -1031,9 +1054,16 @@ class SqlLogEntry:
1031
1054
  result_type: Optional[str]
1032
1055
  affected_rows: Optional[int]
1033
1056
  result_summary: str
1057
+ database_kind: Any = None
1058
+ parameter_log_policies: Optional[List[str]] = None
1059
+ sql_origin: Optional[str] = None
1060
+ masked_parameters: Optional[List[bool]] = None
1061
+ log_mode: Optional[str] = None
1062
+ omission_reason: Optional[str] = None
1063
+ execution_outcome: Optional[str] = None
1034
1064
 
1035
1065
  class DiagnosticSqlLogSink:
1036
- """Value-bearing diagnostic SQL destination; the text sink is installed by default."""
1066
+ """Policy-projected SQL destination; the text sink is installed by default."""
1037
1067
  def write(self, entry: SqlLogEntry) -> None:
1038
1068
  raise NotImplementedError
1039
1069
 
@@ -1042,12 +1072,14 @@ class TextDiagnosticSqlLogSink(DiagnosticSqlLogSink):
1042
1072
  self._writer = writer
1043
1073
 
1044
1074
  def write(self, entry: SqlLogEntry) -> None:
1075
+ from .log_privacy import sql_log_projection
1076
+ entry = sql_log_projection(entry)
1045
1077
  elapsed_us = int(entry.elapsed.total_seconds() * 1_000_000) if entry.elapsed else 0
1046
1078
  self._writer(
1047
1079
  f"[TeaQL SQL][{entry.operation.name.lower()}][{elapsed_us}us] "
1048
- f"{entry.result_summary} comment={entry.comment!r} purpose={entry.purpose!r} "
1080
+ f"{entry.result_summary} outcome={entry.execution_outcome or 'unknown'} comment={entry.comment!r} purpose={entry.purpose!r} "
1049
1081
  f"auditReason={entry.audit_reason!r} tracePath={entry.trace_path!r}\n"
1050
- f"Parameterized SQL: {entry.sql} params={entry.params!r}\n"
1082
+ f"SQL omission reason: {entry.omission_reason or 'none'}\n"
1051
1083
  f"Debug SQL: {entry.debug_sql}"
1052
1084
  )
1053
1085