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

tigrbl/runtime/labels.py

@@ -0,0 +1,353 @@
+# tigrbl/v3/runtime/labels.py
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Dict, Optional, Tuple, Literal, Iterable, Set
+import re as _re
+
+from . import events as _ev
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Grammar
+#   Canonical (display) form:
+#     - secdep: <name>                      → "secdep:<name>"
+#     - dep:    <name>                      → "dep:<name>"
+#     - sys:    <subject>@<PHASE>           → "sys:txn:begin@START_TX"
+#     - atom:   <domain>:<subject>@<anchor>[#field]
+#     - hook:   <domain>:<subject>@<anchor>[#field]
+#
+#   Notes:
+#   - step_kind ∈ {secdep, dep, sys, atom, hook}
+#   - domains are restricted to: {emit, out, refresh, resolve, response, schema, storage, wire}
+#   - anchors for atom/hook MUST be canonical events from runtime/events.py
+#   - sys anchors MUST be one of PHASES (typically START_TX, HANDLER, END_TX)
+# ──────────────────────────────────────────────────────────────────────────────
+
+STEP_KINDS: Tuple[str, ...] = ("secdep", "dep", "sys", "atom", "hook")
+StepKind = Literal["secdep", "dep", "sys", "atom", "hook"]
+DOMAINS: Tuple[str, ...] = (
+    "emit",
+    "out",
+    "refresh",
+    "resolve",
+    "response",
+    "schema",
+    "storage",
+    "wire",
+    "sys",
+)
+
+# minimal token rules (tight but readable)
+# - domain/subject: letters, digits, underscore, dash; subject may contain colon to support composite subjects like "txn:begin"
+# - field: letters, digits, underscore, dash, dot
+
+_RE_NAME = _re.compile(r"^[A-Za-z0-9_.:-]+$")  # secdep/dep name (tolerant)
+_RE_SUBJECT = _re.compile(
+    r"^[A-Za-z0-9_:-]+$"
+)  # allow ":" inside subject (e.g., "txn:begin")
+_RE_FIELD = _re.compile(r"^[A-Za-z0-9_.-]+$")  # instance suffix
+
+
+@dataclass(frozen=True)
+class Label:
+    kind: StepKind
+    subject: str
+    domain: Optional[str] = None
+    anchor: Optional[str] = None
+    field: Optional[str] = None
+
+    # ── renderers ──────────────────────────────────────────────────────────────
+    def render(self, *, pretty: bool = True) -> str:
+        """
+        Pretty = human-facing (short secdep/dep). False = always canonicalized shape when possible.
+        """
+        if self.kind in ("secdep", "dep"):
+            return f"{self.kind}:{self.subject}"
+        if self.kind == "sys":
+            return f"sys:{self.subject}@{self.anchor}"
+        # atom / hook
+        base = f"{self.kind}:{self.domain}:{self.subject}@{self.anchor}"
+        return f"{base}#{self.field}" if self.field else base
+
+    __str__ = render
+
+    # ── convenience ───────────────────────────────────────────────────────────
+    def with_field(self, field: Optional[str]) -> "Label":
+        _validate_field(field)
+        return replace(self, field=field)
+
+    def clear_field(self) -> "Label":
+        return replace(self, field=None)
+
+    # ── predicates ────────────────────────────────────────────────────────────
+    @property
+    def is_secdep(self) -> bool:
+        return self.kind == "secdep"
+
+    @property
+    def is_dep(self) -> bool:
+        return self.kind == "dep"
+
+    @property
+    def is_sys(self) -> bool:
+        return self.kind == "sys"
+
+    @property
+    def is_atom(self) -> bool:
+        return self.kind == "atom"
+
+    @property
+    def is_hook(self) -> bool:
+        return self.kind == "hook"
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Builders (typed helpers)
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def make_dep(name: str) -> Label:
+    _require(_RE_NAME.match(name), f"Invalid dep name {name!r}")
+    return Label(kind="dep", subject=name)
+
+
+def make_secdep(name: str) -> Label:
+    _require(_RE_NAME.match(name), f"Invalid secdep name {name!r}")
+    return Label(kind="secdep", subject=name)
+
+
+def make_sys(subject: str, phase: _ev.Phase) -> Label:
+    _require(subject and _RE_SUBJECT.match(subject), f"Invalid sys subject {subject!r}")
+    _require(phase in _ev.PHASES, f"Invalid sys phase {phase!r}")
+    return Label(kind="sys", subject=subject, anchor=phase)
+
+
+def make_atom(
+    domain: str, subject: str, anchor: str, field: Optional[str] = None
+) -> Label:
+    _validate_domain(domain)
+    _validate_subject(subject)
+    _validate_anchor(anchor)
+    _validate_field(field)
+    return Label(
+        kind="atom", domain=domain, subject=subject, anchor=anchor, field=field
+    )
+
+
+def make_hook(
+    domain: str, subject: str, anchor: str, field: Optional[str] = None
+) -> Label:
+    _validate_domain(domain)
+    _validate_subject(subject)
+    _validate_anchor(anchor)
+    _validate_field(field)
+    return Label(
+        kind="hook", domain=domain, subject=subject, anchor=anchor, field=field
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Parse / validate
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def parse(s: str) -> Label:
+    """
+    Parse a label string into a Label object. Raises ValueError on any mismatch.
+    Accepts the canonical display forms described in the header.
+    """
+    if not isinstance(s, str) or ":" not in s:
+        raise ValueError(f"Not a label: {s!r}")
+
+    # secdep:name / dep:name
+    if s.startswith("secdep:"):
+        name = s[len("secdep:") :]
+        _require(_RE_NAME.match(name), f"Invalid secdep name {name!r}")
+        return Label(kind="secdep", subject=name)
+    if s.startswith("dep:"):
+        name = s[len("dep:") :]
+        _require(_RE_NAME.match(name), f"Invalid dep name {name!r}")
+        return Label(kind="dep", subject=name)
+
+    # sys:subject@PHASE
+    if s.startswith("sys:"):
+        rest = s[len("sys:") :]
+        try:
+            subject, phase = rest.split("@", 1)
+        except ValueError as e:
+            raise ValueError("System label must be 'sys:<subject>@<PHASE>'") from e
+        _require(_RE_SUBJECT.match(subject), f"Invalid sys subject {subject!r}")
+        _require(phase in _ev.PHASES, f"Invalid sys phase {phase!r}")
+        return Label(kind="sys", subject=subject, anchor=phase)
+
+    # atom:/hook:
+    if s.startswith("atom:") or s.startswith("hook:"):
+        kind: StepKind = "atom" if s.startswith("atom:") else "hook"
+        rest = s[len("atom:") :] if kind == "atom" else s[len("hook:") :]
+
+        # Split domain:subject@anchor[#field]
+        try:
+            dom, rest2 = rest.split(":", 1)
+        except ValueError as e:
+            raise ValueError(f"{kind} label must start with '<domain>:...'") from e
+
+        try:
+            subj, rest3 = rest2.split("@", 1)
+        except ValueError as e:
+            raise ValueError(f"{kind} label must include '@<anchor>'") from e
+
+        anchor, field = _split_anchor_field(rest3)
+
+        _validate_domain(dom)
+
+        _validate_subject(subj)
+        _validate_anchor(anchor)
+        _validate_field(field)
+
+        return Label(kind=kind, domain=dom, subject=subj, anchor=anchor, field=field)
+
+    raise ValueError(f"Unknown step kind in label {s!r}")
+
+
+def validate(label: Label) -> None:
+    """Raise ValueError if the label violates the grammar or constraints."""
+    k = label.kind
+    if k in ("secdep", "dep"):
+        _require(
+            label.subject and _RE_NAME.match(label.subject),
+            f"Invalid {k} name {label.subject!r}",
+        )
+        _require(
+            label.domain is None and label.anchor is None,
+            f"{k} cannot carry domain/anchor",
+        )
+        _validate_field(label.field)
+        return
+
+    if k == "sys":
+        _require(
+            label.subject and _RE_SUBJECT.match(label.subject),
+            f"Invalid sys subject {label.subject!r}",
+        )
+        _require(label.anchor in _ev.PHASES, f"Invalid sys phase {label.anchor!r}")
+        _require(label.domain is None, "sys cannot carry a domain")
+        _validate_field(label.field)
+        return
+
+    if k == "atom":
+        _validate_domain(label.domain)
+        _validate_subject(label.subject)
+        _validate_anchor(label.anchor)
+        _validate_field(label.field)
+        return
+
+    if k == "hook":
+        _validate_domain(label.domain)
+        _validate_subject(label.subject)
+        _validate_anchor(label.anchor)
+        _validate_field(label.field)
+        return
+
+    raise ValueError(f"Unknown label kind {k!r}")
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Helpers / Legend
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _split_anchor_field(s: str) -> Tuple[str, Optional[str]]:
+    """Split 'anchor[#field]' into (anchor, field?)."""
+    if "#" in s:
+        anchor, field = s.split("#", 1)
+        return anchor, (field or None)
+    return s, None
+
+
+def _validate_domain(domain: Optional[str]) -> None:
+    _require(
+        domain is not None and domain in DOMAINS,
+        f"Invalid domain {domain!r}; expected one of {list(DOMAINS)}",
+    )
+
+
+def _validate_subject(subj: Optional[str]) -> None:
+    _require(subj is not None and _RE_SUBJECT.match(subj), f"Invalid subject {subj!r}")
+
+
+def _validate_anchor(anchor: Optional[str]) -> None:
+    _require(
+        anchor is not None and (_ev.is_valid_event(anchor) or anchor in _ev.PHASES),
+        f"Invalid or unknown anchor {anchor!r}",
+    )
+
+
+def _validate_field(field: Optional[str]) -> None:
+    if field is None:
+        return
+    _require(_RE_FIELD.match(field), f"Invalid field instance suffix {field!r}")
+
+
+def _require(cond: bool, msg: str) -> None:
+    if not cond:
+        raise ValueError(msg)
+
+
+def legend() -> Dict[str, object]:
+    """
+    Return a stable dictionary suitable for a /diagnostics/labels/legend endpoint.
+    Includes step kinds, atom domains, sys phases, and ordered anchors.
+    """
+    return {
+        "step_kinds": STEP_KINDS,
+        "atom_domains": DOMAINS,
+        "sys_phases": _ev.PHASES,
+        "anchors": _ev.all_events_ordered(),
+        "notes": {
+            "secdep/dep": "Run before any anchor; shape is 'secdep:<name>' / 'dep:<name>'.",
+            "sys": "Subject describes the system op; anchor is a PHASE.",
+            "atom/hook": "Use '<domain>:<subject>@<anchor>#field' (field optional).",
+        },
+    }
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Bulk utilities (nice-to-haves for planner/trace)
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def ensure_all_valid(labels: Iterable[Label]) -> None:
+    for lbl in labels:
+        validate(lbl)
+
+
+def only_atoms(labels: Iterable[Label]) -> Tuple[Label, ...]:
+    return tuple(label for label in labels if label.kind == "atom")
+
+
+def only_hooks(labels: Iterable[Label]) -> Tuple[Label, ...]:
+    return tuple(label for label in labels if label.kind == "hook")
+
+
+def fields_used(labels: Iterable[Label]) -> Set[str]:
+    return {label.field for label in labels if label.field}
+
+
+__all__ = [
+    "STEP_KINDS",
+    "StepKind",
+    "DOMAINS",
+    "Label",
+    "make_dep",
+    "make_secdep",
+    "make_sys",
+    "make_atom",
+    "make_hook",
+    "parse",
+    "validate",
+    "legend",
+    "ensure_all_valid",
+    "only_atoms",
+    "only_hooks",
+    "fields_used",
+]

tigrbl/runtime/opview.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+from typing import Any, Mapping, Dict
+from types import SimpleNamespace
+
+from . import kernel as _kernel  # single, app-scoped kernel
+
+
+def _ensure_temp(ctx: Any) -> Dict[str, Any]:
+    tmp = getattr(ctx, "temp", None)
+    if not isinstance(tmp, dict):
+        tmp = {}
+        setattr(ctx, "temp", tmp)
+    return tmp
+
+
+def opview_from_ctx(ctx: Any):
+    """
+    Resolve the ``OpView`` for this request context or raise a runtime error.
+
+    Preferred resolution path is via ``ctx.opview`` which should be attached by
+    the caller.  Falling back to kernel lookups requires ``ctx.app`` (or
+    ``ctx.api``), ``ctx.model`` (or derivable from ``ctx.obj``), and ``ctx.op``
+    (or ``ctx.method``).
+    """
+    ov = getattr(ctx, "opview", None)
+    if ov is not None:
+        return ov
+
+    app = getattr(ctx, "app", None) or getattr(ctx, "api", None)
+    model = getattr(ctx, "model", None)
+    if model is None:
+        obj = getattr(ctx, "obj", None)
+        if obj is not None:
+            model = type(obj)
+    alias = getattr(ctx, "op", None) or getattr(ctx, "method", None)
+
+    if app and model and alias:
+        # One-kernel-per-app, prime once; raises if not compiled
+        return _kernel._default_kernel.get_opview(app, model, alias)
+
+    if alias:
+        specs = getattr(ctx, "specs", None)
+        if specs is not None:
+            return _kernel._default_kernel._compile_opview_from_specs(
+                specs, SimpleNamespace(alias=alias)
+            )
+
+    missing = []
+    if not alias:
+        missing.append("op")
+    if not app:
+        missing.append("app")
+    if not model:
+        missing.append("model")
+    # runtime-error policy: eject loudly; no skip
+    raise RuntimeError(f"ctx_missing:{','.join(missing)}")
+
+
+def ensure_schema_in(ctx: Any, ov) -> Mapping[str, Any]:
+    """
+    Load precompiled inbound schema from OpView into ctx.temp['schema_in'] if absent.
+    """
+    temp = _ensure_temp(ctx)
+    if "schema_in" not in temp:
+        bf = ov.schema_in.by_field
+        req = tuple(n for n, e in bf.items() if e.get("required"))
+        temp["schema_in"] = {
+            "fields": ov.schema_in.fields,
+            "by_field": bf,
+            "required": req,
+        }
+    return temp["schema_in"]
+
+
+def ensure_schema_out(ctx: Any, ov) -> Mapping[str, Any]:
+    """
+    Load precompiled outbound schema from OpView into ctx.temp['schema_out'] if absent.
+    """
+    temp = _ensure_temp(ctx)
+    if "schema_out" not in temp:
+        temp["schema_out"] = {
+            "fields": ov.schema_out.fields,
+            "by_field": ov.schema_out.by_field,
+            "expose": ov.schema_out.expose,
+        }
+    return temp["schema_out"]
+
+
+__all__ = ["opview_from_ctx", "ensure_schema_in", "ensure_schema_out", "_ensure_temp"]

tigrbl/runtime/ordering.py

@@ -0,0 +1,256 @@
+# tigrbl/v3/runtime/ordering.py
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import Dict, Iterable, List, Mapping, Optional, Sequence, Tuple
+
+from . import events as _ev
+from .labels import Label
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Default in-anchor preferences (safe, minimal)
+#   - Each entry is a list of "domain:subject" tokens in desired order.
+#   - DEFAULT_EDGES are derived from these (u -> v).
+# ──────────────────────────────────────────────────────────────────────────────
+
+# tokens: "domain:subject"
+_PREF: Dict[str, Tuple[str, ...]] = {
+    _ev.SCHEMA_COLLECT_IN: ("schema:collect_in",),
+    _ev.IN_VALIDATE: ("wire:build_in", "wire:validate_in"),
+    _ev.RESOLVE_VALUES: ("resolve:assemble", "resolve:paired_gen"),
+    _ev.PRE_FLUSH: ("storage:to_stored",),
+    _ev.EMIT_ALIASES_PRE: ("emit:paired_pre",),
+    _ev.POST_FLUSH: ("refresh:demand",),
+    _ev.EMIT_ALIASES_POST: ("emit:paired_post",),
+    _ev.SCHEMA_COLLECT_OUT: ("schema:collect_out",),
+    _ev.OUT_BUILD: ("wire:build_out",),
+    _ev.EMIT_ALIASES_READ: ("emit:readtime_alias",),
+    _ev.OUT_DUMP: (
+        "wire:dump",
+        "out:masking",
+        "response:negotiate",
+        "response:render",
+        "response:template",
+    ),
+}
+
+
+def _derive_edges(
+    pref: Mapping[str, Sequence[str]],
+) -> Dict[str, Tuple[Tuple[str, str], ...]]:
+    out: Dict[str, Tuple[Tuple[str, str], ...]] = {}
+    for anchor, seq in pref.items():
+        edges: List[Tuple[str, str]] = []
+        for i in range(len(seq) - 1):
+            edges.append((seq[i], seq[i + 1]))
+        out[anchor] = tuple(edges)
+    return out
+
+
+_DEFAULT_EDGES: Dict[str, Tuple[Tuple[str, str], ...]] = _derive_edges(_PREF)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Public API
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class AnchorPolicy:
+    """
+    Extra ordering rules for a specific anchor.
+    - edges: (u, v) means "u before v" where u/v are "domain:subject" tokens.
+    - prefer: stable tie-break priority list of tokens.
+    """
+
+    edges: Tuple[Tuple[str, str], ...] = ()
+    prefer: Tuple[str, ...] = ()
+
+
+def flatten(
+    labels: Iterable[Label],
+    *,
+    persist: bool,
+    anchor_policies: Optional[Mapping[str, AnchorPolicy]] = None,
+) -> List[Label]:
+    """
+    Produce a flattened order of labels across all anchors.
+
+    Rules:
+    - secdep → dep → PRE_HANDLER anchors → POST_HANDLER anchors → POST_RESPONSE anchors
+    - persist-tied anchors are pruned when persist=False (see events.is_persist_tied).
+    - Within each anchor, perform a topo sort using DEFAULT_EDGES + anchor_policies[anchor].edges,
+      with stable tie-breaks using preferences + (kind, domain, subject, field).
+    """
+    # Partition by kind/anchor
+    secdeps: List[Label] = []
+    deps: List[Label] = []
+    by_anchor: Dict[str, List[Label]] = defaultdict(list)
+
+    for lbl in labels:
+        if lbl.kind == "secdep":
+            secdeps.append(lbl)
+        elif lbl.kind == "dep":
+            deps.append(lbl)
+        else:
+            if not lbl.anchor:
+                raise ValueError(f"Label missing anchor: {lbl}")
+            by_anchor[lbl.anchor].append(lbl)
+
+    anchors_present = tuple(by_anchor.keys())
+    anchors = _ev.order_events(anchors_present)
+    if not persist:
+        anchors = _ev.prune_events_for_persist(anchors, persist=False)
+
+    out: List[Label] = []
+
+    out.extend(secdeps)
+    out.extend(deps)
+
+    _append_anchor_block(
+        out,
+        by_anchor,
+        anchors,
+        target_phase="PRE_HANDLER",
+        anchor_policies=anchor_policies,
+        persist=persist,
+    )
+    _append_anchor_block(
+        out,
+        by_anchor,
+        anchors,
+        target_phase="POST_HANDLER",
+        anchor_policies=anchor_policies,
+        persist=persist,
+    )
+    _append_anchor_block(
+        out,
+        by_anchor,
+        anchors,
+        target_phase="POST_RESPONSE",
+        anchor_policies=anchor_policies,
+        persist=persist,
+    )
+
+    return out
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Anchor block assembly
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _append_anchor_block(
+    out: List[Label],
+    by_anchor: Mapping[str, Sequence[Label]],
+    anchors: Sequence[str],
+    *,
+    target_phase: _ev.Phase,
+    anchor_policies: Optional[Mapping[str, AnchorPolicy]],
+    persist: bool,
+) -> None:
+    """Append all labels for anchors in a given phase in canonical anchor order."""
+    for anchor in anchors:
+        if _ev.phase_for_event(anchor) != target_phase:
+            continue
+        if not persist and _ev.is_persist_tied(anchor):
+            continue
+        group = list(by_anchor.get(anchor, ()))
+        if not group:
+            continue
+        policy = anchor_policies.get(anchor) if anchor_policies else None
+        ordered = order_within_anchor(anchor, group, policy)
+        out.extend(ordered)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# In-anchor ordering (topological, deterministic)
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def order_within_anchor(
+    anchor: str,
+    labels: Sequence[Label],
+    policy: Optional[AnchorPolicy] = None,
+) -> List[Label]:
+    """
+    Topologically sort labels within an anchor.
+
+    Nodes are individual labels; edges are lifted from token-level rules where
+    token = "domain:subject". If multiple labels share the same token (e.g., per-field),
+    edges fan-out to all matching nodes.
+    """
+    # Build token index
+    tokens: Dict[Label, str] = {}
+    by_token: Dict[str, List[Label]] = defaultdict(list)
+    for label in labels:
+        if not label.domain:
+            # hooks always have domain; atoms must have domain by grammar
+            raise ValueError(f"In-anchor item missing domain: {label}")
+        t = f"{label.domain}:{label.subject}"
+        tokens[label] = t
+        by_token[t].append(label)
+
+    # Collect edges: defaults + policy
+    edges = list(_DEFAULT_EDGES.get(anchor, ()))
+    if policy and policy.edges:
+        edges.extend(policy.edges)
+
+    # Build adjacency on label nodes (fan-out pairwise where tokens exist)
+    adj: Dict[Label, List[Label]] = {label: [] for label in labels}
+    indeg: Dict[Label, int] = {label: 0 for label in labels}
+
+    def _present(tok: str) -> bool:
+        return tok in by_token
+
+    for u_tok, v_tok in edges:
+        if not (_present(u_tok) and _present(v_tok)):
+            continue
+        for u in by_token[u_tok]:
+            for v in by_token[v_tok]:
+                if v not in adj[u]:
+                    adj[u].append(v)
+                    indeg[v] += 1
+
+    # Kahn topo with deterministic tie-breaks
+    # Priority: policy.prefer index → DEFAULT preference index → kind (atom<hook) → domain → subject → field
+    prefer = tuple(policy.prefer) if policy and policy.prefer else ()
+    pref_index: Dict[str, int] = {t: i for i, t in enumerate(prefer)}
+    def_pref = _PREF.get(anchor, ())
+    def_index: Dict[str, int] = {t: i for i, t in enumerate(def_pref)}
+
+    def _rank(label: Label) -> Tuple[int, int, int, str, str, str]:
+        t = tokens[label]
+        p1 = pref_index.get(t, 10_000)
+        p2 = def_index.get(t, 10_000)
+        k = 0 if label.kind == "atom" else 1  # atoms before hooks by default
+        return (p1, p2, k, label.domain or "", label.subject, label.field or "")
+
+    q: List[Label] = [n for n, d in indeg.items() if d == 0]
+    q.sort(key=_rank)
+
+    out: List[Label] = []
+    while q:
+        n = q.pop(0)
+        out.append(n)
+        for v in adj[n]:
+            indeg[v] -= 1
+            if indeg[v] == 0:
+                q.append(v)
+        q.sort(key=_rank)  # keep deterministic
+
+    if len(out) != len(labels):
+        # Cycle detected — fall back to total order by rank for remaining nodes
+        remaining = [n for n in labels if n not in out]
+        remaining.sort(key=_rank)
+        out.extend(remaining)
+
+    return out
+
+
+__all__ = [
+    "AnchorPolicy",
+    "flatten",
+    "order_within_anchor",
+]