teaql 0.2.7__tar.gz → 0.2.8__tar.gz

{teaql-0.2.7 → teaql-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: teaql
-Version: 0.2.7
+Version: 0.2.8
 Summary: TeaQL Runtime and Data Service for Python
 Author: TeaQL
 License-Expression: Apache-2.0

{teaql-0.2.7 → teaql-0.2.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "teaql"
-version = "0.2.7"
+version = "0.2.8"
 description = "TeaQL Runtime and Data Service for Python"
 readme = "README.md"
 requires-python = ">=3.10"

{teaql-0.2.7 → teaql-0.2.8}/src/teaql/core/dynamic_search.py

@@ -17,8 +17,8 @@ def _reject_json_constant(_):
 
 
 def _warning(warning):
-    _LOG.warning('%s entity=%s clause=%s fieldPath=%s', warning['code'],
-                 warning['entity'], warning['clause'], warning['fieldPath'])
+    _LOG.warning('%s entity=%s clause=%s fieldPath=<omitted>', warning['code'],
+                 warning['entity'], warning['clause'])
 
 
 def normalize_dynamic_search(source, entity, models, warn=_warning, max_clauses=100):

{teaql-0.2.7 → teaql-0.2.8}/src/teaql/core/meta.py

@@ -6,6 +6,13 @@ class PropertyDescriptor:
         self._is_id = False
         self._is_version = False
         self.nullable = True
+        self.log_policy_val = 'unknown'
+    def log_policy(self, policy):
+        """Trusted schema policy; incoming requests cannot override it."""
+        if policy not in ('plain', 'masked', 'credential', 'unknown'):
+            raise ValueError('invalid SQL parameter log policy')
+        self.log_policy_val = policy
+        return self
     def column_name(self, name): 
         self.column_name_val = name
         return self
@@ -46,6 +53,7 @@ class EntityDescriptor:
         self.properties = []
         self.relations = []
         self.audit_mask_fields_val = []
+        self.audit_mask_fields_declared = False
         self.audit_value_max_len_val = None
     def table_name(self, name): 
         self.table_name_val = name
@@ -65,7 +73,8 @@ class EntityDescriptor:
         return next((prop for prop in self.properties if prop.name == name), None)
 
     def audit_mask_fields(self, fields):
-        self.audit_mask_fields_val = list(fields)
+        self.audit_mask_fields_val = list(fields) if fields is not None else []
+        self.audit_mask_fields_declared = fields is not None
         return self
 
     def audit_value_max_len(self, max_len):

{teaql-0.2.7 → teaql-0.2.8}/src/teaql/data_service/__init__.py

@@ -32,6 +32,15 @@ class QueryRequest:
     _comment: Optional[str] = None
     _purpose: Optional[str] = None
 
+    def __post_init__(self) -> None:
+        # Older generated wrappers store intent on SelectQuery but construct
+        # QueryRequest(query) without forwarding it. Keep the explicit request
+        # values authoritative while preserving their diagnostic intent.
+        if self._comment is None:
+            self._comment = getattr(self.query, 'comment_text', None)
+        if self._purpose is None:
+            self._purpose = getattr(self.query, 'purpose_text', None)
+
     def comment(self, text: str) -> 'QueryRequest':
         if not text:
             raise ValueError("comment cannot be empty")
@@ -71,6 +80,11 @@ class ExecutionMetadata:
     audit_reason: Optional[str] = None
     backend_request_id: Optional[str] = None
     debug_query: Optional[str] = None
+    database_kind: Any = None
+    parameter_log_policies: Optional[List[str]] = None
+    sql_origin: Optional[str] = None
+    # Statement/cursor termination only, not transaction commit.
+    execution_outcome: Optional[str] = None
 
 
 @dataclass

teaql-0.2.8/src/teaql/provider/mysql/dialect.py

@@ -0,0 +1,13 @@
+from teaql.sql.dialect import SqlDialect, quote_identifier_if_needed
+from teaql.sql.types import DatabaseKind
+
+
+class MysqlDialect(SqlDialect):
+    def kind(self) -> DatabaseKind:
+        return DatabaseKind.MySql
+
+    def quote_ident(self, ident: str) -> str:
+        return quote_identifier_if_needed(ident, "`")
+
+    def placeholder(self, index: int) -> str:
+        return "%s"

{teaql-0.2.7 → teaql-0.2.8}/src/teaql/provider/mysql/transport.py

@@ -3,11 +3,11 @@ import aiomysql
 from decimal import Decimal
 from datetime import date, datetime, timezone
 from typing import List, Dict, Any, Optional, AsyncIterator
-from teaql.sql.executor import SqlTransport
+from teaql.sql.executor import SqlTransactionTransport, SqlTransactionTransportTx
 from teaql.sql.types import CompiledQuery
 from teaql.core.value import Value, DataType, Timestamp
 
-class MysqlTransport(SqlTransport):
+class MysqlTransport(SqlTransactionTransport):
     def __init__(self, db_url: str):
         self.db_url = db_url
 
@@ -99,3 +99,48 @@ class MysqlTransport(SqlTransport):
                 return cur.rowcount, cur.lastrowid
         finally:
             conn.close()
+
+    async def begin_sql(self) -> SqlTransactionTransportTx:
+        user, password, host, port, db = self._parse_url()
+        conn = await aiomysql.connect(
+            host=host, port=port, user=user, password=password, db=db,
+            cursorclass=aiomysql.DictCursor, autocommit=False,
+        )
+        try:
+            await conn.begin()
+            return _MysqlTransaction(conn, self)
+        except BaseException:
+            conn.close()
+            raise
+
+
+class _MysqlTransaction(SqlTransactionTransportTx):
+    def __init__(self, conn, owner: MysqlTransport):
+        self._conn = conn
+        self._owner = owner
+
+    async def fetch_all_sql(self, query: CompiledQuery) -> List[Dict[str, Any]]:
+        async with self._conn.cursor() as cursor:
+            await cursor.execute(query.sql_with_comment(), self._owner._bind_values(query.params))
+            rows = await cursor.fetchall()
+            return [
+                {key: self._owner._decode_value(value) for key, value in row.items()}
+                for row in rows
+            ]
+
+    async def execute_sql(self, query: CompiledQuery) -> tuple[int, int]:
+        async with self._conn.cursor() as cursor:
+            await cursor.execute(query.sql_with_comment(), self._owner._bind_values(query.params))
+            return cursor.rowcount, cursor.lastrowid
+
+    async def commit_sql(self) -> None:
+        try:
+            await self._conn.commit()
+        finally:
+            self._conn.close()
+
+    async def rollback_sql(self) -> None:
+        try:
+            await self._conn.rollback()
+        finally:
+            self._conn.close()

{teaql-0.2.7 → teaql-0.2.8}/src/teaql/provider/postgres/dialect.py

@@ -5,7 +5,7 @@ from teaql.core.meta import PropertyDescriptor
 
 class PostgresDialect(SqlDialect):
     def kind(self) -> DatabaseKind:
-        return DatabaseKind.Postgres
+        return DatabaseKind.PostgreSql
 
     def quote_ident(self, ident: str) -> str:
         return quote_identifier_if_needed(ident, '"')

{teaql-0.2.7 → teaql-0.2.8}/src/teaql/provider/postgres/transport.py

@@ -3,11 +3,11 @@ import asyncpg
 from decimal import Decimal
 from datetime import date, datetime, timezone
 from typing import List, Dict, Any, Optional, AsyncIterator
-from teaql.sql.executor import SqlTransport
+from teaql.sql.executor import SqlTransactionTransport, SqlTransactionTransportTx
 from teaql.sql.types import CompiledQuery
 from teaql.core.value import Value, DataType, Timestamp
 
-class PostgresTransport(SqlTransport):
+class PostgresTransport(SqlTransactionTransport):
     def __init__(self, db_url: str):
         self.db_url = db_url
 
@@ -88,3 +88,47 @@ class PostgresTransport(SqlTransport):
             return affected_rows, 0
         finally:
             await conn.close()
+
+    async def begin_sql(self) -> SqlTransactionTransportTx:
+        conn = await asyncpg.connect(self.db_url)
+        try:
+            transaction = conn.transaction()
+            await transaction.start()
+            return _PostgresTransaction(conn, transaction, self)
+        except BaseException:
+            await conn.close()
+            raise
+
+
+class _PostgresTransaction(SqlTransactionTransportTx):
+    def __init__(self, conn, transaction, owner: PostgresTransport):
+        self._conn = conn
+        self._transaction = transaction
+        self._owner = owner
+
+    async def fetch_all_sql(self, query: CompiledQuery) -> List[Dict[str, Any]]:
+        rows = await self._conn.fetch(query.sql_with_comment(), *self._owner._bind_values(query.params))
+        return [
+            {key: self._owner._decode_value(value) for key, value in row.items()}
+            for row in rows
+        ]
+
+    async def execute_sql(self, query: CompiledQuery) -> tuple[int, int]:
+        status = await self._conn.execute(query.sql_with_comment(), *self._owner._bind_values(query.params))
+        if status.startswith("INSERT "):
+            return int(status.split()[-1]), 0
+        if status.startswith(("UPDATE ", "DELETE ")):
+            return int(status.split()[-1]), 0
+        return 0, 0
+
+    async def commit_sql(self) -> None:
+        try:
+            await self._transaction.commit()
+        finally:
+            await self._conn.close()
+
+    async def rollback_sql(self) -> None:
+        try:
+            await self._transaction.rollback()
+        finally:
+            await self._conn.close()

{teaql-0.2.7 → teaql-0.2.8}/src/teaql/runtime/audit.py

@@ -35,22 +35,23 @@ class RawAuditEvent:
         fields = []
         for change in self.changes:
             value = None if change.new_value is None else str(getattr(change.new_value, "val", change.new_value))
-            masked = (credential_name(change.field)
-                      or payload_has_credentials(change.new_value)
-                      or payload_has_credentials(change.old_value)
-                      or (change.field in mask_fields and not allow))
+            credential = (credential_name(change.field)
+                          or payload_has_credentials(change.new_value)
+                          or payload_has_credentials(change.old_value))
+            masked = credential or (change.field in mask_fields and not allow)
             if masked:
                 secrets.extend(value_strings(change.old_value))
                 secrets.extend(value_strings(change.new_value))
             if value is not None and masked:
-                value = REDACTED
+                value = REDACTED if credential else _mask(value)
             truncated = value is not None and max_length is not None and len(value) > max_length
             if truncated:
                 value = "*" * max_length if max_length <= 3 else value[:max_length - 3] + "..."
             fields.append(SafeAuditField(change.field, value, masked, truncated))
+        intent_values = secrets + value_strings(self.entity_id)
         return SafeAuditEvent(
-            self.kind, self.entity, self.entity_id, scrub(tuple(fields), secrets), scrub(self.trace_chain, secrets),
-            scrub(self.actor, secrets), self.category,
+            self.kind, self.entity, self.entity_id, scrub(tuple(fields), secrets), scrub(self.trace_chain, intent_values),
+            scrub(self.actor, intent_values), self.category,
         )
 
 
@@ -74,7 +75,8 @@ class SafeAuditEvent:
 
 
 def _mask(value: str) -> str:
-    if len(value) < 8:
+    # Unicode scalar length, ASCII digits: the same contract as Rust and Go.
+    if len(value) < 8 or (value.isascii() and value.isdigit()):
         return "*" * len(value)
     return value[:2] + "*" * (len(value) - 4) + value[-2:]
 

{teaql-0.2.7 → teaql-0.2.8}/src/teaql/runtime/context.py

@@ -705,6 +705,10 @@ class UserContext:
         return self.get_resource("locale") or Locale.ENGLISH
 
     def record_metadata_log(self, metadata: Any):
+        self._record_metadata_log(metadata)
+
+    def _record_metadata_log(self, metadata: Any, *, intent_source=None, intent_values=()):
+        """Internal statement plumbing: source bindings never reach sinks/buffers."""
         op = SqlLogOperation.Select
         op_str = str(getattr(metadata, 'operation', '')).lower()
         if 'insert' in op_str: op = SqlLogOperation.Insert
@@ -726,6 +730,10 @@ class UserContext:
             params=list(getattr(metadata, 'parameters', [])),
             debug_sql=getattr(metadata, 'debug_query', '') or '',
             pretty_sql=getattr(metadata, 'debug_query', '') or '',
+            database_kind=getattr(metadata, 'database_kind', None),
+            parameter_log_policies=getattr(metadata, 'parameter_log_policies', None),
+            sql_origin=getattr(metadata, 'sql_origin', None),
+            execution_outcome=getattr(metadata, 'execution_outcome', None),
             started_at=started_at,
             ended_at=ended_at,
             elapsed=ended_at - started_at,
@@ -740,13 +748,11 @@ class UserContext:
             entry.result_summary = f"{entry.affected_rows} rows affected"
 
         from .log_privacy import sql_log_projection
-        entry = sql_log_projection(entry)
+        entry = sql_log_projection(entry, _intent_source=intent_source, _intent_values=intent_values)
         logs = self.sql_logs()
         logs.append(entry)
         self._resources["sql_logs"] = logs
-        sink = self.get_resource("diagnostic_sql_log_sink")
-        if sink is not None:
-            sink.write(entry)
+        self._write_diagnostic_sql_log(entry)
         buf = self.get_resource("UnifiedLogBuffer")
         if buf:
             buf.entries.append(UnifiedLogEntry(
@@ -760,7 +766,8 @@ class UserContext:
         if not self.sql_log_options().enabled_for(operation):
             return
             
-        debug_sql = getattr(query, 'debug_sql', lambda *args: "")() if hasattr(query, 'debug_sql') else getattr(query, 'sql', "")
+        # Projection renders only safe values. Never materialize plaintext first.
+        debug_sql = ''
         
         entry = SqlLogEntry(
             operation=operation,
@@ -772,6 +779,9 @@ class UserContext:
             params=getattr(query, 'params', []),
             debug_sql=debug_sql,
             pretty_sql=debug_sql,
+            database_kind=getattr(query, 'database_kind', None),
+            parameter_log_policies=getattr(query, 'parameter_log_policies', None),
+            sql_origin=getattr(query, 'sql_origin', None),
             started_at=started_at,
             ended_at=ended_at,
             elapsed=elapsed,
@@ -791,9 +801,7 @@ class UserContext:
         logs = self.sql_logs()
         logs.append(entry)
         self._resources["sql_logs"] = logs
-        sink = self.get_resource("diagnostic_sql_log_sink")
-        if sink is not None:
-            sink.write(entry)
+        self._write_diagnostic_sql_log(entry)
         
         buf = self.get_resource("UnifiedLogBuffer")
         if buf:
@@ -804,6 +812,17 @@ class UserContext:
                 payload=LogPayload.Sql(entry)
             ))
 
+    def _write_diagnostic_sql_log(self, entry: 'SqlLogEntry'):
+        sink = self.get_resource("diagnostic_sql_log_sink")
+        if sink is None:
+            return
+        try:
+            sink.write(entry)
+        except Exception:
+            # An optional diagnostic destination must not change SQL outcomes.
+            # Do not print the exception: custom sinks may include raw values.
+            pass
+
     def register_executor(self, executor: Any):
         self.insert_resource("executor", executor)
 
@@ -1035,6 +1054,13 @@ class SqlLogEntry:
     result_type: Optional[str]
     affected_rows: Optional[int]
     result_summary: str
+    database_kind: Any = None
+    parameter_log_policies: Optional[List[str]] = None
+    sql_origin: Optional[str] = None
+    masked_parameters: Optional[List[bool]] = None
+    log_mode: Optional[str] = None
+    omission_reason: Optional[str] = None
+    execution_outcome: Optional[str] = None
 
 class DiagnosticSqlLogSink:
     """Policy-projected SQL destination; the text sink is installed by default."""
@@ -1051,9 +1077,9 @@ class TextDiagnosticSqlLogSink(DiagnosticSqlLogSink):
         elapsed_us = int(entry.elapsed.total_seconds() * 1_000_000) if entry.elapsed else 0
         self._writer(
             f"[TeaQL SQL][{entry.operation.name.lower()}][{elapsed_us}us] "
-            f"{entry.result_summary} comment={entry.comment!r} purpose={entry.purpose!r} "
+            f"{entry.result_summary} outcome={entry.execution_outcome or 'unknown'} comment={entry.comment!r} purpose={entry.purpose!r} "
             f"auditReason={entry.audit_reason!r} tracePath={entry.trace_path!r}\n"
-            f"Parameterized SQL: {entry.sql} params={entry.params!r}\n"
+            f"SQL omission reason: {entry.omission_reason or 'none'}\n"
             f"Debug SQL: {entry.debug_sql}"
         )
 

teaql-0.2.8/src/teaql/runtime/log_privacy.py

@@ -0,0 +1,195 @@
+"""Log-only projections. Never modify execution parameters or stored values."""
+
+import logging
+import os
+import re
+import weakref
+from copy import deepcopy
+from dataclasses import fields, is_dataclass, replace
+from functools import lru_cache
+
+PLAINTEXT_ENV = "TEAQL_ALLOW_SENSITIVE_PLAINTEXT_LOGS"
+PLAINTEXT_ACK = "I_UNDERSTAND_SENSITIVE_DATA_MAY_BE_WRITTEN_TO_DISK"
+REDACTED = "[REDACTED]"
+SQL_REDACTED = "[REDACTED SQL; NOT REPLAYABLE]"
+DEBUG_LABEL = "-- TeaQL DEBUG PLAINTEXT; EXPLICIT OPT-IN\n"
+
+
+def label_debug_sql(sql):
+    return sql if not sql or sql.startswith(DEBUG_LABEL) else DEBUG_LABEL + sql
+
+
+@lru_cache(maxsize=1)
+def _warn_plaintext():
+    logging.getLogger("teaql.runtime").warning(
+        "Sensitive plaintext logging enabled: application data may be written to disk. "
+        "Authentication secrets remain redacted."
+    )
+
+
+def plaintext_enabled():
+    enabled = os.environ.get(PLAINTEXT_ENV) == PLAINTEXT_ACK
+    if enabled:
+        _warn_plaintext()
+    return enabled
+
+
+def credential_name(name):
+    normalized = re.sub(r"[^a-z0-9]", "", str(name).lower())
+    return any(word in normalized for word in (
+        "password", "passwd", "passphrase", "privatekey", "secret", "accesstoken",
+        "refreshtoken", "idtoken", "apikey", "authorization", "credential",
+        "sessiontoken", "magiclinktoken",
+    ))
+
+
+def payload_has_credentials(value):
+    value = getattr(value, "val", value)
+    if isinstance(value, dict):
+        return any(credential_name(k) or payload_has_credentials(v) for k, v in value.items())
+    if isinstance(value, (tuple, list)):
+        return any(payload_has_credentials(v) for v in value)
+    return False
+
+
+def value_strings(value):
+    value = getattr(value, "val", value)
+    if isinstance(value, dict):
+        return [s for v in value.values() for s in value_strings(v)]
+    if isinstance(value, (tuple, list)):
+        return [s for v in value for s in value_strings(v)]
+    return [] if value is None or value == "" else [str(value)]
+
+
+def scrub(value, secrets, hide_all=False):
+    """Copy annotations, removing known values even when embedded in intent."""
+    if isinstance(value, str):
+        if hide_all:
+            return REDACTED if value else value
+        for secret in sorted(set(secrets), key=len, reverse=True):
+            value = value.replace(secret, REDACTED)
+        return value
+    if isinstance(value, list):
+        return [scrub(v, secrets, hide_all) for v in value]
+    if isinstance(value, tuple):
+        return tuple(scrub(v, secrets, hide_all) for v in value)
+    if isinstance(value, dict):
+        return {k: scrub(v, secrets, hide_all) for k, v in value.items()}
+    if is_dataclass(value):
+        return replace(value, **{f.name: scrub(getattr(value, f.name), secrets, hide_all)
+                                 for f in fields(value) if f.init})
+    return value
+
+
+_projections = {}
+
+def _remember_projection(projected, allow, alternative=None):
+    key = id(projected)
+    _projections[key] = (weakref.ref(projected, lambda _: _projections.pop(key, None)),
+                         allow, deepcopy(projected), alternative)
+    return projected
+
+def _business_mask(value):
+    from .audit import _mask
+    value = getattr(value, 'val', value)
+    if value is None:
+        return None
+    if isinstance(value, (tuple, list)):
+        return [_business_mask(child) for child in value]
+    if isinstance(value, dict):
+        return REDACTED
+    return _mask(str(value))
+
+def _binding_policies(source):
+    supplied = source.parameter_log_policies
+    valid = supplied is not None and len(supplied) == len(source.params)
+    credentials = credential_name(source.sql) and (source.sql_origin != 'generated' or not valid)
+    policies = []
+    for index, value in enumerate(source.params):
+        policy = supplied[index] if valid else 'unknown'
+        if credentials or payload_has_credentials(value):
+            policy = 'credential'
+        policies.append(policy if policy in ('plain', 'masked', 'credential') else 'unknown')
+    return policies
+
+
+def _is_masked(policy, allow):
+    return policy in ('credential', 'unknown') or (not allow and policy != 'plain')
+
+
+def sql_log_projection(entry, *, _intent_source=None, _intent_values=()):
+    """Source bindings are call-local runtime plumbing, never stored on a log entry."""
+    allow = plaintext_enabled() and entry.log_mode != 'masked'
+    prior = _projections.get(id(entry))
+    # Log entries are mutable: reuse only an unchanged projection. Weak references
+    # keep this idempotence bookkeeping from retaining a long-running log history.
+    if prior and prior[0]() is entry and prior[2] == entry:
+        if not prior[1] or allow:
+            return entry
+        # Entries are mutable. Do not expose the cached safe alternative itself.
+        if prior[3] is not None:
+            return _remember_projection(deepcopy(prior[3]), False)
+    projected = _project_with_policy(entry, allow, _intent_source, _intent_values)
+    alternative = _project_with_policy(entry, False, _intent_source, _intent_values) if allow else None
+    return _remember_projection(projected, allow, alternative)
+
+
+def _project_with_policy(entry, allow, intent_source, intent_values):
+    from teaql.sql.types import DatabaseKind, render_log_sql, _sql_literal
+    from teaql.core.value import Value
+    supplied = entry.parameter_log_policies
+    valid = supplied is None or len(supplied) == len(entry.params)
+    # Compiler-owned bindings already identify individual credential fields. A
+    # credential column elsewhere in the projection must not hide ordinary binds.
+    # Unclassified/custom statements retain the conservative whole-SQL fallback.
+    credentials = credential_name(entry.sql) and (
+        entry.sql_origin != 'generated' or supplied is None or not valid)
+    policies = _binding_policies(entry)
+    masked = [_is_masked(policy, allow) for policy in policies]
+    safe_values = [(_business_mask(value) if policies[index] == 'masked' else REDACTED)
+                   if masked[index] else deepcopy(value) for index, value in enumerate(entry.params)]
+    secrets = [text for index, value in enumerate(entry.params) if masked[index]
+               for text in value_strings(value)]
+    if intent_source is not None:
+        source_policies = _binding_policies(intent_source)
+        secrets.extend(text for index, value in enumerate(intent_source.params)
+                       if _is_masked(source_policies[index], allow) for text in value_strings(value))
+    intent_secrets = secrets + [text for value in intent_values for text in value_strings(value)]
+    # A copied/changed debug record has lost its reliable private alternative.
+    # Its inherited intent may mention values absent from its own SQL bindings.
+    unknown_debug_intent = not allow and entry.log_mode == 'debug-plaintext' and intent_source is None
+    def intent(value):
+        return scrub(value, intent_secrets, hide_all=unknown_debug_intent)
+    bare = re.sub(r'\$[0-9]+', '?', entry.sql)
+    unsafe = ((not allow or credentials) and entry.sql_origin != 'generated' and
+              bool(re.search(r"['\"`$]|--|/\*|\b\d+\b|:[A-Za-z_]", bare)))
+    reason = 'untrusted-literal-sql' if unsafe else 'policy-count-mismatch' if not valid else None
+    rendered = SQL_REDACTED
+    kind = entry.database_kind or (DatabaseKind.PostgreSql if re.search(r'\$[0-9]+', entry.sql)
+                                  else DatabaseKind.MySql if '%s' in entry.sql else DatabaseKind.Sqlite)
+    if reason is None:
+        try:
+            def literal(index):
+                value = safe_values[index]
+                value = value if isinstance(value, Value) else Value.from_any(value)
+                return _sql_literal(value, kind) + (' /* masked */' if masked[index] else '')
+            rendered = render_log_sql(entry.sql, safe_values, kind, literal)
+            prefix = (('-- TeaQL DEBUG PLAINTEXT; EXPLICIT OPT-IN; PARTIALLY MASKED; NOT REPLAYABLE\n'
+                       if any(masked) else DEBUG_LABEL) if allow else '-- TeaQL MASKED; NOT REPLAYABLE\n')
+            rendered = prefix + rendered
+        except Exception:
+            # Renderer failures must not echo source SQL, values, or exception text.
+            rendered = SQL_REDACTED
+            reason = 'unsupported-or-mismatched-bindings'
+    projected = replace(entry, sql=SQL_REDACTED if unsafe else entry.sql
+                        if entry.sql_origin == 'generated' else scrub(entry.sql, secrets),
+                        params=safe_values, parameter_log_policies=policies, masked_parameters=masked,
+                        debug_sql=rendered, pretty_sql=rendered, omission_reason=reason,
+                        log_mode='debug-plaintext' if allow else 'masked',
+                        comment=intent(entry.comment), purpose=intent(entry.purpose),
+                        audit_reason=intent(entry.audit_reason),
+                        result_summary=(f'{entry.result_count} rows returned' if entry.result_count is not None
+                            else f'{entry.affected_rows} rows affected' if entry.affected_rows is not None
+                            else scrub(entry.result_summary, secrets, hide_all=unknown_debug_intent)),
+                        trace_path=intent(entry.trace_path))
+    return projected