tigrbl 0.0.1.dev1__py3-none-any.whl → 0.3.0.dev2__py3-none-any.whl

tigrbl/runtime/atoms/emit/readtime_alias.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, MutableMapping, Optional
+import logging
+
+from ... import events as _ev
+from ...opview import opview_from_ctx, ensure_schema_out, _ensure_temp
+
+# Runs near the end of the lifecycle, before wire:dump/out:masking.
+ANCHOR = _ev.EMIT_ALIASES_READ  # "emit:aliases:readtime"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """Emit safe read-time aliases into response extras."""
+    logger.debug("Running emit:readtime_alias")
+    temp = _ensure_temp(ctx)
+    emit_buf = _ensure_emit_buf(temp)
+    extras = _ensure_response_extras(temp)
+
+    ov = opview_from_ctx(ctx)
+    schema_out = ensure_schema_out(ctx, ov)
+    for field, desc in schema_out["by_field"].items():
+        out_alias = desc.get("alias_out")
+        if not out_alias:
+            continue
+        if out_alias in extras:
+            logger.debug("Alias %s already present in extras; skipping", out_alias)
+            continue
+
+        value = _read_current_value(obj, ctx, field)
+        if value is None:
+            logger.debug("No current value available for field %s", field)
+            continue
+
+        safe_val = _safe_readtime_value(value, desc)
+        extras[out_alias] = safe_val
+        logger.debug("Emitted read-time alias '%s' for field '%s'", out_alias, field)
+
+        emit_buf["read"].append(
+            {
+                "field": field,
+                "alias": out_alias,
+                "emitted": True,
+                "meta": _alias_meta(desc),
+            }
+        )
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Internals
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _ensure_emit_buf(temp: MutableMapping[str, Any]) -> Dict[str, list]:
+    buf = temp.get("emit_aliases")
+    if not isinstance(buf, dict):
+        buf = {"pre": [], "post": [], "read": []}
+        temp["emit_aliases"] = buf
+    else:
+        buf.setdefault("pre", [])
+        buf.setdefault("post", [])
+        buf.setdefault("read", [])
+    return buf  # type: ignore[return-value]
+
+
+def _ensure_response_extras(temp: MutableMapping[str, Any]) -> Dict[str, Any]:
+    extras = temp.get("response_extras")
+    if not isinstance(extras, dict):
+        extras = {}
+        temp["response_extras"] = extras
+    return extras  # type: ignore[return-value]
+
+
+def _alias_meta(desc: Mapping[str, Any]) -> Dict[str, Any]:
+    meta: Dict[str, Any] = {}
+    for attr in ("sensitive", "mask_last"):
+        if attr in desc:
+            meta[attr] = desc[attr]
+    return meta
+
+
+def _read_current_value(obj: Optional[object], ctx: Any, field: str) -> Optional[Any]:
+    if obj is not None and hasattr(obj, field):
+        try:
+            return getattr(obj, field)
+        except Exception:
+            pass
+    for name in ("row", "values", "current_values"):
+        src = getattr(ctx, name, None)
+        if isinstance(src, Mapping) and field in src:
+            return src.get(field)
+    hv = getattr(getattr(ctx, "temp", {}), "get", lambda *a, **k: None)(
+        "hydrated_values"
+    )  # type: ignore
+    if isinstance(hv, Mapping):
+        return hv.get(field)
+    return None
+
+
+def _mask_value(value: Any, keep_last: Optional[int]) -> str:
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return "••••"
+    s = str(value) if value is not None else ""
+    if not s:
+        return ""
+    n = keep_last if (isinstance(keep_last, int) and keep_last >= 0) else 4
+    n = min(n, len(s))
+    return "•" * (len(s) - n) + s[-n:]
+
+
+def _safe_readtime_value(value: Any, desc: Mapping[str, Any]) -> Any:
+    if desc.get("sensitive"):
+        keep_last = desc.get("mask_last")
+        return _mask_value(value, keep_last)
+    return value
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/out/__init__.py

@@ -0,0 +1,38 @@
+# tigrbl/v3/runtime/atoms/out/__init__.py
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional, Tuple
+import logging
+
+# Atom implementations (model-scoped)
+from . import masking as _masking
+
+# Runner signature: (obj|None, ctx) -> None
+RunFn = Callable[[Optional[object], Any], None]
+
+#: Domain-scoped registry consumed by the kernel plan (and aggregated at atoms/__init__.py).
+#: Keys are (domain, subject); values are (anchor, runner).
+REGISTRY: Dict[Tuple[str, str], Tuple[str, RunFn]] = {
+    ("out", "masking"): (_masking.ANCHOR, _masking.run),
+}
+
+logger = logging.getLogger("uvicorn")
+
+
+def subjects() -> Tuple[str, ...]:
+    """Return the subject names exported by this domain."""
+    subjects = tuple(s for (_, s) in REGISTRY.keys())
+    logger.debug("Listing 'out' subjects: %s", subjects)
+    return subjects
+
+
+def get(subject: str) -> Tuple[str, RunFn]:
+    """Return (anchor, runner) for a subject in the 'out' domain."""
+    key = ("out", subject)
+    if key not in REGISTRY:
+        raise KeyError(f"Unknown out atom subject: {subject!r}")
+    logger.debug("Retrieving 'out' subject %s", subject)
+    return REGISTRY[key]
+
+
+__all__ = ["REGISTRY", "RunFn", "subjects", "get"]

tigrbl/runtime/atoms/out/masking.py

@@ -0,0 +1,135 @@
+# tigrbl/v3/runtime/atoms/out/masking.py
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, MutableMapping, Optional, Sequence
+import logging
+
+from ... import events as _ev
+from ...opview import opview_from_ctx, ensure_schema_out, _ensure_temp
+
+# Runs at the very end of the lifecycle (after wire:dump).
+ANCHOR = _ev.OUT_DUMP  # "out:dump"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """
+    out:masking@out:dump
+
+    Purpose
+    -------
+    Mask sensitive top-level fields in the already-built response payload.
+    This runs AFTER wire:dump so the payload exists and after emit:readtime_alias
+    so alias extras are already present. It does NOT redact explicitly emitted
+    alias extras (e.g., secret-once raw tokens) — those are intentional.
+
+    Inputs / Conventions
+    --------------------
+    - ctx.temp["response_payload"] : dict or list[dict] (produced by wire:dump)
+    - ctx.temp["emit_aliases"]["post"] / ["read"] : lists of descriptors that
+      include {"alias": "..."}; these alias keys are skipped (not masked).
+
+    Effects
+    -------
+    - For each payload item (dict), if a key equals a ColumnSpec field name and
+      that column is marked sensitive (via `sensitive`/`redact`/`redact_last`),
+      replace the value with a masked hint.
+    - Leaves alias extras untouched (based on the alias sets captured from
+      emit_aliases.post/read).
+    """
+    logger.debug("Running out:masking")
+    ov = opview_from_ctx(ctx)
+    schema_out = ensure_schema_out(ctx, ov)
+
+    temp = _ensure_temp(ctx)
+    payload = temp.get("response_payload")
+    if payload is None:
+        logger.debug("No response payload found; skipping masking")
+        return
+    logger.debug("Original payload before masking: %s", payload)
+
+    emit_buf = _ensure_emit_buf(temp)
+    skip_aliases = _collect_emitted_aliases(emit_buf)
+
+    if isinstance(payload, dict):
+        logger.debug("Masking single-object payload")
+        _mask_one(payload, schema_out["by_field"], skip_aliases)
+    elif isinstance(payload, (list, tuple)):
+        logger.debug("Masking list payload with %d items", len(payload))
+        for item in payload:
+            if isinstance(item, dict):
+                _mask_one(item, schema_out["by_field"], skip_aliases)
+            else:
+                logger.debug("Skipping non-dict item in payload: %s", item)
+    else:
+        logger.debug(
+            "Unsupported payload type %s; leaving as-is", type(payload).__name__
+        )
+
+    logger.debug("Payload after masking: %s", payload)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Internals
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _ensure_emit_buf(temp: MutableMapping[str, Any]) -> Dict[str, list]:
+    buf = temp.get("emit_aliases")
+    if not isinstance(buf, dict):
+        buf = {"pre": [], "post": [], "read": []}
+        temp["emit_aliases"] = buf
+    else:
+        buf.setdefault("pre", [])
+        buf.setdefault("post", [])
+        buf.setdefault("read", [])
+    return buf  # type: ignore[return-value]
+
+
+def _collect_emitted_aliases(
+    emit_buf: Mapping[str, Sequence[Mapping[str, Any]]],
+) -> set[str]:
+    aliases: set[str] = set()
+    for bucket in ("post", "read"):
+        for d in emit_buf.get(bucket, ()) or ():
+            a = d.get("alias")
+            if isinstance(a, str) and a:
+                aliases.add(a)
+    return aliases
+
+
+def _mask_one(
+    item: Dict[str, Any],
+    by_field: Mapping[str, Mapping[str, Any]],
+    skip_aliases: set[str],
+) -> None:
+    for field, desc in by_field.items():
+        if field not in item or field in skip_aliases:
+            continue
+        val = item.get(field, None)
+        if val is None:
+            continue
+        if not (desc.get("sensitive") or desc.get("mask_last") is not None):
+            continue
+        masked = _mask_value(val, desc.get("mask_last"))
+        logger.debug("Masking field '%s': %r -> %r", field, val, masked)
+        item[field] = masked
+    logger.debug("Item after masking: %s", item)
+
+
+def _mask_value(value: Any, keep_last: Optional[int]) -> str:
+    """
+    Generic masking for strings/bytes; falls back to a fixed token when unknown.
+    """
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return "••••"
+    s = str(value) if value is not None else ""
+    if not s:
+        return ""
+    n = keep_last if (isinstance(keep_last, int) and keep_last >= 0) else 4
+    n = min(n, len(s))
+    return "•" * (len(s) - n) + s[-n:]
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/refresh/__init__.py

@@ -0,0 +1,38 @@
+# tigrbl/v3/runtime/atoms/refresh/__init__.py
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional, Tuple
+import logging
+
+# Atom implementations (model-scoped)
+from . import demand as _demand
+
+# Runner signature: (obj|None, ctx) -> None
+RunFn = Callable[[Optional[object], Any], None]
+
+#: Domain-scoped registry consumed by the kernel plan (and aggregated at atoms/__init__.py).
+#: Keys are (domain, subject); values are (anchor, runner).
+REGISTRY: Dict[Tuple[str, str], Tuple[str, RunFn]] = {
+    ("refresh", "demand"): (_demand.ANCHOR, _demand.run),
+}
+
+logger = logging.getLogger("uvicorn")
+
+
+def subjects() -> Tuple[str, ...]:
+    """Return the subject names exported by this domain."""
+    subjects = tuple(s for (_, s) in REGISTRY.keys())
+    logger.debug("Listing 'refresh' subjects: %s", subjects)
+    return subjects
+
+
+def get(subject: str) -> Tuple[str, RunFn]:
+    """Return (anchor, runner) for a subject in the 'refresh' domain."""
+    key = ("refresh", subject)
+    if key not in REGISTRY:
+        raise KeyError(f"Unknown refresh atom subject: {subject!r}")
+    logger.debug("Retrieving 'refresh' subject %s", subject)
+    return REGISTRY[key]
+
+
+__all__ = ["REGISTRY", "RunFn", "subjects", "get"]

tigrbl/runtime/atoms/refresh/demand.py

@@ -0,0 +1,130 @@
+# tigrbl/v3/runtime/atoms/refresh/demand.py
+from __future__ import annotations
+
+from typing import Any, Iterable, Optional
+import logging
+
+from ... import events as _ev
+from ...opview import opview_from_ctx, _ensure_temp
+
+# After the handler flushes changes; decide whether to hydrate DB-generated values.
+ANCHOR = _ev.POST_FLUSH  # "post:flush"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """
+    refresh:demand@post:flush
+
+    Purpose
+    -------
+    Decide whether to hydrate refreshed values from the DB after a write (INSERT/UPDATE).
+    We do NOT perform the refresh here; we only mark intent on the context so the
+    executor (or handler) can perform the vendor-specific action (RETURNING/refresh()).
+
+    Inputs (conventions)
+    --------------------
+    - ctx.persist : bool               → write op? (anchor is persist-tied but we guard)
+    - ctx.temp["used_returning"] : bool              → a prior step already satisfied hydration
+    - ctx.temp["hydrated_values"] : Mapping[str, Any]→ values captured from RETURNING
+    - ctx.cfg.refresh_after_write : Optional[bool]   → policy override (true/false)
+      (also checks ctx.cfg.refresh_policy.{always,never,auto})
+    - ctx.bulk    : Optional[bool]    → bulk write; executor may choose a different strategy
+
+    Effects
+    -------
+    - ctx.temp["refresh_demand"] : bool
+    - ctx.temp["refresh_fields"] : tuple[str, ...] (hint: which fields likely changed in DB)
+    - ctx.temp["refresh_reason"] : str (diagnostic only)
+    """
+    logger.debug("Running refresh:demand")
+    if getattr(ctx, "persist", True) is False:
+        logger.debug("Skipping refresh:demand; ctx.persist is False")
+        return
+
+    temp = _ensure_temp(ctx)
+    ov = opview_from_ctx(ctx)
+    refresh_hints = tuple(ov.refresh_hints)
+
+    # If RETURNING already produced hydrated values, skip unless policy forces refresh.
+    returning_satisfied = bool(temp.get("used_returning")) or bool(
+        temp.get("hydrated_values")
+    )
+    logger.debug("Returning satisfied: %s", returning_satisfied)
+
+    # Policy: cfg.refresh_after_write wins if explicitly set; otherwise "auto".
+    policy = _get_refresh_policy(ctx)
+    logger.debug("Refresh policy: %s", policy)
+    # auto → infer from specs (db-generated signals) OR absence of returning values
+    needs_by_specs = bool(refresh_hints)
+    logger.debug("Refresh hints: %s; fields=%s", needs_by_specs, refresh_hints)
+    need_refresh = _decide(policy, returning_satisfied, needs_by_specs)
+    logger.debug("Refresh decision: %s", need_refresh)
+
+    temp["refresh_demand"] = bool(need_refresh)
+    temp["refresh_fields"] = refresh_hints
+
+    if need_refresh:
+        temp["refresh_reason"] = _reason(
+            policy, returning_satisfied, needs_by_specs, refresh_hints
+        )
+        logger.debug("Refresh scheduled: %s", temp["refresh_reason"])
+    else:
+        temp["refresh_reason"] = "skipped: returning_satisfied or policy=false"
+        logger.debug("Refresh skipped: %s", temp["refresh_reason"])
+
+    # Executor/handler will look at ctx.temp["refresh_demand"] and act accordingly.
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Internals
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _get_refresh_policy(ctx: Any) -> str:
+    """
+    Return 'always' | 'never' | 'auto'.
+    Accepts any of the following on ctx.cfg (first hit wins):
+      - cfg.refresh_after_write: bool → True:'always' / False:'never'
+      - cfg.refresh_policy: str in {'always','never','auto'}
+    Defaults to 'auto'.
+    """
+    cfg = getattr(ctx, "cfg", None)
+    if cfg is not None:
+        val = getattr(cfg, "refresh_after_write", None)
+        if isinstance(val, bool):
+            return "always" if val else "never"
+        pol = getattr(getattr(cfg, "refresh_policy", None), "value", None) or getattr(
+            cfg, "refresh_policy", None
+        )
+        if isinstance(pol, str) and pol in {"always", "never", "auto"}:
+            return pol
+    return "auto"
+
+
+def _decide(policy: str, returning_satisfied: bool, needs_by_specs: bool) -> bool:
+    if policy == "always":
+        return True
+    if policy == "never":
+        return False
+    # auto
+    if returning_satisfied:
+        # RETURNING already hydrated values; only refresh if specs strongly indicate more work.
+        return bool(needs_by_specs)
+    # No returning: default to refresh to honor "hydrate after flush" decision.
+    return True
+
+
+def _reason(
+    policy: str, returning_satisfied: bool, needs_by_specs: bool, fields: Iterable[str]
+) -> str:
+    parts = [f"policy={policy}"]
+    parts.append(f"returning_satisfied={bool(returning_satisfied)}")
+    parts.append(f"specs_need={bool(needs_by_specs)}")
+    if fields:
+        parts.append(f"fields={','.join(fields)}")
+    return "; ".join(parts)
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/resolve/__init__.py

@@ -0,0 +1,40 @@
+# tigrbl/v3/runtime/atoms/resolve/__init__.py
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional, Tuple
+import logging
+
+# Atom implementations (model-scoped)
+from . import assemble as _assemble
+from . import paired_gen as _paired_gen
+
+# Runner signature: (obj|None, ctx) -> None
+RunFn = Callable[[Optional[object], Any], None]
+
+#: Domain-scoped registry consumed by the kernel plan (and aggregated at atoms/__init__.py).
+#: Keys are (domain, subject); values are (anchor, runner).
+REGISTRY: Dict[Tuple[str, str], Tuple[str, RunFn]] = {
+    ("resolve", "assemble"): (_assemble.ANCHOR, _assemble.run),
+    ("resolve", "paired_gen"): (_paired_gen.ANCHOR, _paired_gen.run),
+}
+
+logger = logging.getLogger("uvicorn")
+
+
+def subjects() -> Tuple[str, ...]:
+    """Return the subject names exported by this domain."""
+    subjects = tuple(s for (_, s) in REGISTRY.keys())
+    logger.debug("Listing 'resolve' subjects: %s", subjects)
+    return subjects
+
+
+def get(subject: str) -> Tuple[str, RunFn]:
+    """Return (anchor, runner) for a subject in the 'resolve' domain."""
+    key = ("resolve", subject)
+    if key not in REGISTRY:
+        raise KeyError(f"Unknown resolve atom subject: {subject!r}")
+    logger.debug("Retrieving 'resolve' subject %s", subject)
+    return REGISTRY[key]
+
+
+__all__ = ["REGISTRY", "RunFn", "subjects", "get"]

tigrbl/runtime/atoms/resolve/assemble.py

@@ -0,0 +1,167 @@
+# tigrbl/v3/runtime/atoms/resolve/assemble.py
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Dict, Tuple
+import logging
+
+from ... import events as _ev
+from ...opview import opview_from_ctx, ensure_schema_in, _ensure_temp
+
+# Runs in HANDLER phase, before pre:flush and any storage transforms.
+ANCHOR = _ev.RESOLVE_VALUES  # "resolve:values"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """
+    resolve:assemble@resolve:values
+
+    Purpose
+    -------
+    Build a normalized dict of inbound values to apply on the model (assembled_values).
+    - Prefer client-provided, validated values (from wire:build_in/validate).
+    - For fields that are **ABSENT** (not present in inbound), apply ColumnSpec.default_factory(ctx)
+      for simple server-side defaults (non-paired path).
+    - Virtual columns (storage=None) are never persisted; if present in inbound, stash them
+      under temp["virtual_in"] for downstream wire/out logic.
+
+    Inputs (conventions)
+    --------------------
+    - ctx.temp["in_values"] OR ctx.in_data / ctx.payload / ctx.data / ctx.body :
+        dict-like or Pydantic model; used as inbound source
+    - ctx.persist : bool  (writes only; non-persist ops typically prune this anchor)
+    - ctx.op      : str   (verb name; optional, only for diagnostics)
+
+    Effects
+    -------
+    - ctx.temp["assembled_values"] : dict[field -> value] (only persisted fields)
+    - ctx.temp["virtual_in"]       : dict[field -> value] (for storage=None)
+    - ctx.temp["absent_fields"]    : tuple[str, ...]      (those not in inbound)
+    - ctx.temp["used_default_factory"] : tuple[str, ...]  (fields defaulted here)
+    """
+    # Non-persisting ops should have pruned this anchor; retain guard for safety.
+    if getattr(ctx, "persist", True) is False:
+        logger.debug("Skipping resolve:assemble; ctx.persist is False")
+        return
+
+    logger.debug("Running resolve:assemble")
+    ov = opview_from_ctx(ctx)
+    schema_in = ensure_schema_in(ctx, ov)
+    inbound = _coerce_inbound(getattr(ctx, "temp", {}).get("in_values", None), ctx)
+
+    temp = _ensure_temp(ctx)
+    assembled: Dict[str, Any] = {}
+    virtual_in: Dict[str, Any] = {}
+    absent: list[str] = []
+    used_default: list[str] = []
+
+    # Iterate fields in a stable order
+    for field in sorted(schema_in["fields"]):
+        meta = schema_in["by_field"].get(field, {})
+        in_enabled = meta.get("in_enabled", True)
+        is_virtual = meta.get("virtual", False)
+
+        present, value = _try_read_inbound(inbound, field)
+        if present:
+            if is_virtual:
+                virtual_in[field] = value
+                logger.debug("Captured virtual inbound %s=%s", field, value)
+            elif in_enabled:
+                assembled[field] = value
+                logger.debug("Assembled inbound %s=%s", field, value)
+            continue
+
+        absent.append(field)
+        logger.debug("Field %s absent from inbound", field)
+
+        default_fn = meta.get("default_factory")
+        if callable(default_fn) and in_enabled and not is_virtual:
+            try:
+                default_val = default_fn(_ctx_view(ctx))
+                assembled[field] = default_val
+                used_default.append(field)
+                logger.debug("Applied default for field %s", field)
+            except Exception:
+                logger.debug("Default factory failed for field %s", field)
+
+    # Stash results on ctx.temp
+    temp["assembled_values"] = assembled
+    temp["virtual_in"] = virtual_in
+    temp["absent_fields"] = tuple(absent)
+    temp["used_default_factory"] = tuple(used_default)
+    logger.debug(
+        "Assembled values: %s, virtual_in: %s, absent: %s, defaults: %s",
+        assembled,
+        virtual_in,
+        absent,
+        used_default,
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Internals
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _coerce_inbound(candidate: Any, ctx: Any) -> Mapping[str, Any]:
+    """
+    Return a dict-like for inbound values.
+    Priority: ctx.temp["in_values"] → ctx.in_data → ctx.payload → ctx.data → ctx.body.
+    Accepts Pydantic v1/v2 models (model_dump()/dict()).
+    """
+    for name in ("in_values",):
+        if isinstance(candidate, Mapping):
+            return candidate
+    # fallbacks on ctx
+    for attr in ("in_data", "payload", "data", "body"):
+        val = getattr(ctx, attr, None)
+        if isinstance(val, Mapping):
+            return val
+        # Pydantic v2
+        if hasattr(val, "model_dump") and callable(getattr(val, "model_dump")):
+            try:
+                return dict(val.model_dump())
+            except Exception:
+                pass
+        # Pydantic v1
+        if hasattr(val, "dict") and callable(getattr(val, "dict")):
+            try:
+                return dict(val.dict())
+            except Exception:
+                pass
+    # default empty
+    return {}
+
+
+def _try_read_inbound(inbound: Mapping[str, Any], field: str) -> Tuple[bool, Any]:
+    """
+    Distinguish ABSENT vs present(None).
+    """
+    if field in inbound:
+        return True, inbound.get(field, None)
+    # Be tolerant to alias-style inputs (if present)
+    for alt in (field.lower(), field.upper()):
+        if alt in inbound:
+            return True, inbound.get(alt)
+    return False, None
+
+
+def _ctx_view(ctx: Any) -> Dict[str, Any]:
+    """
+    Provide a small read-only view for default_factory functions
+    without exposing the entire executor context.
+    """
+    view = {
+        "op": getattr(ctx, "op", None),
+        "persist": getattr(ctx, "persist", True),
+        "temp": getattr(ctx, "temp", None),
+        # optional hints the executor might set
+        "tenant": getattr(ctx, "tenant", None),
+        "user": getattr(ctx, "user", None),
+        "now": getattr(ctx, "now", None),
+    }
+    return view
+
+
+__all__ = ["ANCHOR", "run"]