stata-code 0.12.1__tar.gz → 0.12.2__tar.gz

{stata_code-0.12.1 → stata_code-0.12.2}/CHANGELOG.md

@@ -6,6 +6,63 @@ to semver-major.minor for the result schema (see `SCHEMA.md` §6).
 
 ## [Unreleased]
 
+## 0.12.2 — 2026-08-11
+
+Correctness release. `results.estimation` could report confidence intervals
+and p-values that disagreed with the Stata log printed beside them; if you
+read coefficients out of `results.estimation` rather than the log, upgrade.
+
+### Fixed
+
+- **`results.estimation` reported normal-approximation inference for `t` models
+  whenever `r(table)` had been cleared.** `r(table)` only survives until the
+  next command, so any block that runs something after its estimation —
+  `graph export`, `esttab`, a final `summarize` — fell back to rebuilding the
+  table from `e(b)` / `e(V)`, and that path hardcoded a normal approximation.
+  The result was a payload that quietly disagreed with the log beside it:
+
+  ```text
+  regress price_k mpg weight foreign
+  scatter price_k mpg          // clears r(table)
+
+  log:                mpg   95% CI  [-.1261758,  .169883]   P>|t| 0.769
+  results.estimation: mpg   95% CI  [-0.12362,   0.16732]   p     0.7684
+  ```
+
+  The fallback now follows Stata's own rule — a *t* table on `e(df_r)` degrees
+  of freedom when that scalar is set, *z* otherwise — so the rebuilt table
+  matches the printed one to the last digit. `ci_level` also honours `e(level)`
+  instead of assuming 95, so `regress, level(90)` is no longer mislabelled.
+  Agents told to prefer `structuredContent` over the log were the ones exposed
+  to this; the `r(table)` path was always correct.
+
+  A new `estimation_from_e_b_v` warning records when the rebuild happened. It
+  fires only for an estimation produced by the current run, since `e()` is
+  session-global and would otherwise re-warn on every later call.
+
+- **`include_results: "none"` hollowed out `results.estimation`.** `n_obs`,
+  `df_model`, `df_resid` and `model_stats` are all read from `e()` scalars, so
+  suppressing the `r()` / `e()` *echo* also removed the model-level numbers —
+  even though `include_estimation` is the documented knob for that block, and
+  SCHEMA.md §4 already promised `include_results` "never affects
+  `results.estimation`". The scalars are now always read when estimation is
+  wanted, and only withheld from the wire.
+
+- **A finished background run reported a duration that kept growing.**
+  `Job.elapsed_ms` recomputed `now - submitted` on every poll instead of
+  freezing at completion, so a 1.7 s bootstrap polled ten minutes later
+  reported ten minutes. Callers attributing wall-clock time to Stata were
+  reading their own polling delay. The value is now frozen before the terminal
+  status is published, on both the success and error paths.
+
+### Changed
+
+- **Macro values longer than 256 characters are elided on the wire** with an
+  explicit `… (N more chars elided)` marker. This is aimed at `e(rngstate)`,
+  roughly 2 KB of hex emitted on every `bootstrap` / `permute` / `simulate`
+  run that no consumer can act on. Names are always kept, and the estimation
+  contract is still built from the uncapped values.
+
 ## 0.12.1 — 2026-07-28
 
 ### Fixed

{stata_code-0.12.1 → stata_code-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stata-code
-Version: 0.12.1
+Version: 0.12.2
 Summary: Agent-native Stata bridge — one core, multiple frontends (MCP, Jupyter, VSCode)
 Project-URL: Homepage, https://github.com/brycewang-stanford/stata-code
 Project-URL: Repository, https://github.com/brycewang-stanford/stata-code

{stata_code-0.12.1 → stata_code-0.12.2}/SCHEMA.md

@@ -343,7 +343,7 @@ Stata's `r()` and `e()` return dictionaries, structurally separated. Each follow
 | Sub-field | Type | Notes |
 | --- | --- | --- |
 | `scalars` | `dict<str, number \| null>` | Native floats / ints. Stata's system missing (`.`) → JSON `null`. Extended missings (`.a`–`.z`) → `null` with information loss. |
-| `macros` | `dict<str, string>` | Stata macro values verbatim. |
+| `macros` | `dict<str, string>` | Stata macro values verbatim, except that a value longer than 256 characters is truncated and suffixed with `… (N more chars elided)`. The cap exists for macros like `e(rngstate)`, which is ~2 KB of hex on every `bootstrap` / `permute` / `simulate` run and carries nothing a consumer can act on. The name is always kept, and `results.estimation` is derived from the uncapped values. |
 | `matrices` | `dict<str, Matrix>` | See `Matrix` below. |
 
 **`Matrix` shape:**
@@ -383,9 +383,9 @@ Stata's `r()` and `e()` return dictionaries, structurally separated. Each follow
 | `n_obs` | `int \| null` | Integer form of `e(N)` when available. |
 | `df_model` | `number \| null` | Mirrors `e(df_m)`. |
 | `df_resid` | `number \| null` | Mirrors `e(df_r)`. |
-| `statistic_kind` | `"t" \| "z"` | Which statistic fills each coefficient's `statistic` field. |
-| `source` | `"r_table" \| "e_b_v"` | `r_table` means values were copied from Stata's displayed `r(table)` after verifying its columns and `b` row match `e(b)`; `e_b_v` means point estimates come from `e(b)` and inference, when present, is computed from `e(V)` with a normal approximation. A matrix returned by `ref` is resolved before use, so a deferred `e(V)` still yields standard errors. |
-| `ci_level` | `number` | Confidence level used for `ci_low` / `ci_high`; currently `95.0`. |
+| `statistic_kind` | `"t" \| "z"` | Which statistic fills each coefficient's `statistic` field, and which distribution produced `p_value` / `ci_low` / `ci_high`. On the `e_b_v` path this follows Stata's own rule — `t` on `df_resid` degrees of freedom when `e(df_r)` is set, `z` otherwise — so a rebuilt table agrees with the printed log rather than reporting a normal-approximation interval next to a `P>\|t\|` column. |
+| `source` | `"r_table" \| "e_b_v"` | `r_table` means values were copied from Stata's displayed `r(table)` after verifying its columns and `b` row match `e(b)`; `e_b_v` means point estimates come from `e(b)` and inference, when present, is computed from `e(V)`. A matrix returned by `ref` is resolved before use, so a deferred `e(V)` still yields standard errors. |
+| `ci_level` | `number` | Confidence level used for `ci_low` / `ci_high`. Mirrors `e(level)` when the command stored it, so `regress, level(90)` reports `90.0`; defaults to `95.0` otherwise. |
 | `coefficients` | `array<Coefficient>` | One row per term in `e(b)`, subject to the caller's `include_estimation` / `max_coefficients` budget. |
 | `n_coefficients` | `int` | The model's true term count. Equals `coefficients.length` unless the caller trimmed the table, so `12` rows out of `n_coefficients: 141` is never mistaken for a 12-term model. |
 | `coefficients_truncated` | `bool` | `true` when rows were dropped to satisfy the budget. |
@@ -564,11 +564,21 @@ The rc-to-kind table is approximate and lives in code (`stata_code.core.errors`)
 
 | Field | Type | Notes |
 | --- | --- | --- |
-| `kind` | `string` | Open enum. Common values: `convergence`, `singular`, `boundary`, `omitted_collinear`, `non_finite`, `dataset_variables_truncated`, `unknown`. |
+| `kind` | `string` | Open enum. Common values: `convergence`, `singular`, `boundary`, `omitted_collinear`, `non_finite`, `dataset_variables_truncated`, `log_closed`, `output_tracking_skipped`, `estimation_from_e_b_v`, `unknown`. |
 | `message` | `string` | Human-readable, single line. Truncated to 1,024 characters. |
 
 Warnings are de-duplicated by `(kind, message)`.
 
+`estimation_from_e_b_v` reports that this run performed an estimation whose
+`r(table)` was already gone by the time results were read — a later command in
+the same submission cleared it — so `results.estimation` was rebuilt from
+`e(b)` / `e(V)`. The rebuilt numbers still match the printed log (see
+`statistic_kind` in §3.5), so this is provenance rather than a correctness
+alarm; putting the estimation last in the block restores the `r_table` path.
+It is emitted only when the estimation was produced by *this* run: `e()` is
+session-global, so a later `summarize` in the same session keeps reporting the
+inherited table through the same fallback without re-warning.
+
 ### 3.9 `origin`
 
 ```json
@@ -607,7 +617,7 @@ The schema also dictates what callers may *ask for*. Every frontend exposes the
 | `include_graphs` | `"ref" \| "inline" \| "none"` | `"ref"` | `"none"` skips graph capture entirely (cheapest); `"ref"` captures and returns refs; `"inline"` base64-encodes bytes into `inline`. |
 | `graph_format` | `"png" \| "svg" \| "pdf"` | `"png"` | Render format. |
 | `include_dataset_variables` | `bool` | `true` | Set `false` to omit `dataset.variables`. |
-| `include_results` | `"none" \| "scalars" \| "full"` | `"scalars"` | Payload budget for `results.r` / `results.e`. `"scalars"` inlines scalars and macros and emits every matrix as a stub (§3.4); `"full"` inlines matrix values up to the ~10,000-cell cap; `"none"` omits `r()` / `e()` entirely. Never affects `results.estimation`. |
+| `include_results` | `"none" \| "scalars" \| "full"` | `"scalars"` | Payload budget for `results.r` / `results.e`. `"scalars"` inlines scalars and macros and emits every matrix as a stub (§3.4); `"full"` inlines matrix values up to the ~10,000-cell cap; `"none"` omits `r()` / `e()` entirely. Never affects `results.estimation`: the model-level fields (`n_obs`, `df_model`, `df_resid`, `model_stats`, `depvar`) are read from `e()` regardless of this setting and merely withheld from the wire, so `"none"` does not hollow out the estimation contract. Use `include_estimation` to trim that block. |
 | `include_estimation` | `"none" \| "summary" \| "full"` | `"full"` | Payload budget for `results.estimation`. `"summary"` keeps the model-level block and drops per-term rows. |
 | `max_coefficients` | `int \| null` | `null` | Cap on `estimation.coefficients` rows. `n_coefficients` still reports the true count. |
 | `timeout_ms` | `int \| null` | `600000` (10 min) | Hard timeout. `null` disables. On expiry, returns `ok: false`, `error.kind: "timeout"`, `rc: -2`. The budget covers **queueing**: a call waiting on a session whose Stata process is mid-run returns `rc: -5`, `error.kind: "session_busy"` rather than blocking past its deadline. Frontends MAY override the default if their use case demands. |

{stata_code-0.12.1 → stata_code-0.12.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stata-code"
-version = "0.12.1"
+version = "0.12.2"
 description = "Agent-native Stata bridge — one core, multiple frontends (MCP, Jupyter, VSCode)"
 # The repo default README (README.md) is Chinese; keep the PyPI long description
 # English by pointing at README.en.md.

{stata_code-0.12.1 → stata_code-0.12.2}/stata_code/__init__.py

@@ -260,7 +260,7 @@ def is_available() -> bool:
     return True
 
 
-__version__ = "0.12.1"
+__version__ = "0.12.2"
 
 __all__ = [
     # Primary entry points

{stata_code-0.12.1 → stata_code-0.12.2}/stata_code/core/estimation.py

@@ -9,8 +9,18 @@ parse from log prose:
   exactly what Stata printed, so we copy them verbatim.
 * ``e(b)`` / ``e(V)`` — the coefficient vector and its variance–covariance
   matrix. Always present after an estimation command. We use these as a
-  fallback, computing ``se`` from ``diag(V)`` and ``z``/``p``/CI under a normal
-  approximation (clearly flagged via ``source`` / ``statistic_kind``).
+  fallback, computing ``se`` from ``diag(V)`` and the statistic / p-value / CI
+  ourselves (flagged via ``source="e_b_v"``).
+
+The fallback matters more than "fallback" suggests: ``r(table)`` is wiped by
+the *next* command, so any block that ends in ``graph export`` / ``esttab`` /
+``summarize`` after its estimation lands here. It therefore has to reproduce
+what Stata displayed, not merely something defensible. Stata's own rule (see
+``_coef_table``) is distributional: when ``e(df_r)`` is set the table is a
+*t* table on that many residual degrees of freedom, and otherwise a *z* table.
+We follow exactly that rule, so the fallback CI agrees with the printed log
+digit for digit instead of quietly reporting a normal-approximation interval
+alongside a log that says ``P>|t|``.
 
 The result is :class:`EstimationResult`, attached to ``RunResult.results.
 estimation`` so every frontend (MCP, kernel, VS Code) gets the same typed
@@ -22,6 +32,7 @@ from __future__ import annotations
 
 import math
 from collections.abc import Callable
+from functools import lru_cache
 
 from stata_code.core.schema import (
     Coefficient,
@@ -162,6 +173,111 @@ def _two_sided_normal_p(z: float) -> float:
     return 2.0 * (1.0 - _normal_cdf(abs(z)))
 
 
+def _betacf(a: float, b: float, x: float) -> float:
+    """Continued fraction for the incomplete beta function (Lentz's method)."""
+    tiny = 1e-30
+    qab, qap, qam = a + b, a + 1.0, a - 1.0
+    c = 1.0
+    d = 1.0 - qab * x / qap
+    if abs(d) < tiny:
+        d = tiny
+    d = 1.0 / d
+    h = d
+    for m in range(1, 301):
+        m2 = 2 * m
+        aa = m * (b - m) * x / ((qam + m2) * (a + m2))
+        d = 1.0 + aa * d
+        if abs(d) < tiny:
+            d = tiny
+        c = 1.0 + aa / c
+        if abs(c) < tiny:
+            c = tiny
+        d = 1.0 / d
+        h *= d * c
+        aa = -(a + m) * (qab + m) * x / ((a + m2) * (qap + m2))
+        d = 1.0 + aa * d
+        if abs(d) < tiny:
+            d = tiny
+        c = 1.0 + aa / c
+        if abs(c) < tiny:
+            c = tiny
+        d = 1.0 / d
+        delta = d * c
+        h *= delta
+        if abs(delta - 1.0) < 1e-15:
+            break
+    return h
+
+
+def _betainc_reg(a: float, b: float, x: float) -> float:
+    """Regularized incomplete beta ``I_x(a, b)``, stdlib only."""
+    if x <= 0.0:
+        return 0.0
+    if x >= 1.0:
+        return 1.0
+    ln_front = (
+        math.lgamma(a + b) - math.lgamma(a) - math.lgamma(b) + a * math.log(x) + b * math.log1p(-x)
+    )
+    front = math.exp(ln_front)
+    if x < (a + 1.0) / (a + b + 2.0):
+        return front * _betacf(a, b, x) / a
+    return 1.0 - front * _betacf(b, a, 1.0 - x) / b
+
+
+def _two_sided_t_p(t: float, df: float) -> float:
+    """Two-sided p-value for a t statistic on ``df`` degrees of freedom.
+
+    ``P(|T| > |t|) = I_{df/(df+t²)}(df/2, 1/2)`` — exact, no table lookup.
+    """
+    if df <= 0.0:
+        return _two_sided_normal_p(t)
+    if math.isinf(t):
+        return 0.0
+    return _betainc_reg(df / 2.0, 0.5, df / (df + t * t))
+
+
+@lru_cache(maxsize=256)
+def _t_crit(df: float, level: float) -> float:
+    """Two-sided critical value of the t distribution for a CI ``level`` in %.
+
+    Found by bisection on :func:`_two_sided_t_p`, which is strictly decreasing
+    in ``|t|`` — robust for any ``df`` without shipping a quantile table.
+    """
+    alpha = 1.0 - level / 100.0
+    if df <= 0.0 or not (0.0 < alpha < 1.0):
+        return _z_crit(level)
+    lo, hi = 0.0, 1.0
+    while _two_sided_t_p(hi, df) > alpha and hi < 1e12:
+        hi *= 2.0
+    for _ in range(200):
+        mid = 0.5 * (lo + hi)
+        if _two_sided_t_p(mid, df) > alpha:
+            lo = mid
+        else:
+            hi = mid
+        if hi - lo < 1e-13 * max(1.0, hi):
+            break
+    return 0.5 * (lo + hi)
+
+
+@lru_cache(maxsize=64)
+def _z_crit(level: float) -> float:
+    """Two-sided standard-normal critical value for a CI ``level`` in %."""
+    alpha = 1.0 - level / 100.0
+    if not (0.0 < alpha < 1.0):
+        return _Z_CRIT_95
+    lo, hi = 0.0, 40.0
+    for _ in range(200):
+        mid = 0.5 * (lo + hi)
+        if _two_sided_normal_p(mid) > alpha:
+            lo = mid
+        else:
+            hi = mid
+        if hi - lo < 1e-14 * max(1.0, hi):
+            break
+    return 0.5 * (lo + hi)
+
+
 def _cell(row: list[float | None] | None, j: int) -> float | None:
     if row is None or j >= len(row):
         return None
@@ -284,13 +400,16 @@ def _from_b_v(
     v: Matrix | None,
     resolve: MatrixResolver | None = None,
     b_values: list[list[float | None]] | None = None,
-) -> list[Coefficient]:
+    df_resid: float | None = None,
+    level: float = 95.0,
+) -> tuple[list[Coefficient], str]:
     """Compute coefficient rows from e(b) (and e(V) when available).
 
     ``se``/``statistic``/``p_value``/CI are filled only when e(V) is
     obtainable — inline or through its ref; otherwise just the point estimates
-    are returned. Inference uses the normal approximation — callers flag this
-    via ``source="e_b_v"``.
+    are returned. Returns ``(coefficients, statistic_kind)``: a *t* table on
+    ``df_resid`` degrees of freedom when Stata set ``e(df_r)``, matching what
+    the command printed, and a *z* table otherwise.
     """
     if b_values is None:
         b_values = _values(b, resolve)
@@ -305,6 +424,10 @@ def _from_b_v(
     else:
         v_diag = [None] * len(terms)
 
+    df = float(df_resid) if df_resid is not None and df_resid > 0.0 else None
+    stat_kind = "t" if df is not None else "z"
+    crit = _t_crit(df, level) if df is not None else _z_crit(level)
+
     coeffs: list[Coefficient] = []
     for j, term in enumerate(terms):
         b_val = _cell(b_row, j)
@@ -316,9 +439,9 @@ def _from_b_v(
         ci_high: float | None = None
         if b_val is not None and se is not None and se > 0.0:
             stat = b_val / se
-            p_val = _two_sided_normal_p(stat)
-            ci_low = b_val - _Z_CRIT_95 * se
-            ci_high = b_val + _Z_CRIT_95 * se
+            p_val = _two_sided_t_p(stat, df) if df is not None else _two_sided_normal_p(stat)
+            ci_low = b_val - crit * se
+            ci_high = b_val + crit * se
         coeffs.append(
             Coefficient(
                 term=term,
@@ -330,7 +453,7 @@ def _from_b_v(
                 ci_high=ci_high,
             )
         )
-    return coeffs
+    return coeffs, stat_kind
 
 
 def _model_stats(scalars: dict[str, float | None]) -> dict[str, float | None]:
@@ -406,14 +529,30 @@ def build_estimation_from_returns(
     statistic_kind: str
     source: str
 
+    df_resid = e.scalars.get("df_r")
+    # e(level) is the CI level the command actually displayed; absent means the
+    # Stata default of 95. Both the critical value and the reported ci_level
+    # follow it, so `regress, level(90)` does not come back labelled 95.
+    level_raw = e.scalars.get("level")
+    ci_level = float(level_raw) if level_raw is not None else 95.0
+
     table = r.matrices.get("table")
     parsed = _from_r_table(table, resolve_matrix) if table is not None else None
     if parsed is not None and table is not None and _r_table_matches_b(table, b, resolve_matrix):
         coeffs, statistic_kind = parsed
         source = "r_table"
     else:
-        coeffs = _from_b_v(b, v, resolve_matrix, b_values)
-        statistic_kind = "z"
+        # r(table) is gone — cleared by whatever command ran after the
+        # estimation. Rebuild the table from e(b)/e(V) on the same
+        # distribution Stata used, so the numbers still match the log.
+        coeffs, statistic_kind = _from_b_v(
+            b,
+            v,
+            resolve_matrix,
+            b_values,
+            df_resid=float(df_resid) if df_resid is not None else None,
+            level=ci_level,
+        )
         source = "e_b_v"
 
     n_obs: int | None = None
@@ -430,9 +569,10 @@ def build_estimation_from_returns(
         depvar=depvar,
         n_obs=n_obs,
         df_model=e.scalars.get("df_m"),
-        df_resid=e.scalars.get("df_r"),
+        df_resid=df_resid,
         statistic_kind=statistic_kind,  # type: ignore[arg-type]
         source=source,  # type: ignore[arg-type]
+        ci_level=ci_level,
         coefficients=coeffs,
         model_stats=_model_stats(e.scalars),
         diagnostics=_command_diagnostics(command, e.scalars),

{stata_code-0.12.1 → stata_code-0.12.2}/stata_code/core/jobs.py

@@ -60,6 +60,7 @@ class Job:
         "error",
         "_done",
         "_started",
+        "_elapsed_ms",
     )
 
     def __init__(self, job_id: str, session_id: str, code: str) -> None:
@@ -73,6 +74,7 @@ class Job:
         self.error: str | None = None
         self._done = threading.Event()
         self._started = time.monotonic()
+        self._elapsed_ms: int | None = None
 
     @property
     def done(self) -> bool:
@@ -83,6 +85,15 @@ class Job:
         return self._done.wait(timeout=timeout_s)
 
     def elapsed_ms(self) -> int:
+        """How long the run took, or has been running so far.
+
+        Frozen once the job reaches a terminal state. Recomputing it on every
+        poll made a finished job's reported duration grow without bound — a
+        1.7s bootstrap polled ten minutes later reported ten minutes — so
+        callers attributing wall time to Stata were reading their own latency.
+        """
+        if self._elapsed_ms is not None:
+            return self._elapsed_ms
         return max(0, int((time.monotonic() - self._started) * 1000))
 
     def summary(self) -> dict[str, Any]:
@@ -140,6 +151,11 @@ class JobRegistry:
             # sees a terminal status is guaranteed to see the payload with it.
             job.result = result
             job.error = error
+            # Freeze the clock before publishing a terminal status, so no
+            # reader can observe "done" alongside a still-advancing duration.
+            job._elapsed_ms = max(  # noqa: SLF001 - same-module private handshake
+                0, int((time.monotonic() - job._started) * 1000)  # noqa: SLF001
+            )
             job.finished_at = _utc_iso_ms()
             job.status = status
             job._done.set()  # noqa: SLF001 - same-module private handshake

{stata_code-0.12.1 → stata_code-0.12.2}/stata_code/core/runner.py

@@ -140,6 +140,13 @@ _DATASET_VAR_CAP = 200
 # a matrix would inline more than ~10,000 cells."
 MATRIX_INLINE_CELL_CAP = 10_000
 
+# Longest macro value put on the wire verbatim. Stata macros are mostly short
+# (`e(cmd)`, `e(depvar)`, `e(vcetype)`), but a few are enormous and carry
+# nothing an agent can act on — `e(rngstate)` alone is ~2 KB of hex on every
+# bootstrap / permute / simulate run. Anything longer is elided with an
+# explicit marker rather than dropped, so the name still shows up.
+MACRO_INLINE_CHAR_CAP = 256
+
 # Stata's system missing `.` is exactly maxdouble (2**1023); the 26 extended
 # missings `.a`–`.z` occupy the next representable doubles above it. `sfi`
 # hands all of them back as ordinary Python floats, so any value at or above
@@ -659,7 +666,23 @@ def _project_returns(
             n_rows=n_rows,
             n_cols=n_cols,
         )
-    return StataReturns(scalars=rv.scalars, macros=rv.macros, matrices=matrices)
+    return StataReturns(
+        scalars=rv.scalars,
+        macros={name: _cap_macro(v) for name, v in rv.macros.items()},
+        matrices=matrices,
+    )
+
+
+def _cap_macro(value: str) -> str:
+    """Elide a macro value too long to be worth its tokens on the wire.
+
+    Applied only at projection time — the estimation contract is built from the
+    uncapped values, so nothing downstream loses precision.
+    """
+    if len(value) <= MACRO_INLINE_CHAR_CAP:
+        return value
+    dropped = len(value) - MACRO_INLINE_CHAR_CAP
+    return f"{value[:MACRO_INLINE_CHAR_CAP]}… ({dropped} more chars elided)"
 
 
 def _collect_dataset(rt: Any, include_variables: bool) -> DatasetInfo:
@@ -1329,6 +1352,17 @@ def execute(
         # Snapshot existing graph names before user code so we can take a delta
         # afterward.
         pre_graphs = _list_graph_names(rt) if include_graphs != "none" else []
+
+        # e() is session-global and outlives the run that set it, so
+        # `results.estimation` may describe an estimation from an earlier call.
+        # Fingerprint it now to tell "this run estimated something" from "this
+        # run inherited an estimation" — the difference decides whether an
+        # e(b)/e(V) rebuild is worth reporting.
+        pre_estimation = (
+            _estimation_fingerprint(rt)
+            if estimation_mode != IncludeEstimation.NONE
+            else None
+        )
     graph_source_hints, unnamed_graph_source_hints = (
         _graph_source_hints(code) if include_graphs != "none" else ({}, [])
     )
@@ -1437,6 +1471,34 @@ def execute(
     ok = error is None and rc == 0
     warnings = _extract_warnings(log_text)
 
+    # r(table) is cleared by the next command, so a block that runs anything
+    # after its estimation gets a table rebuilt from e(b)/e(V). The numbers
+    # follow Stata's own t-vs-z rule and so still match the log, but the
+    # provenance is worth stating: a caller comparing against `r(table)` rows
+    # it did not capture should know which path produced these.
+    #
+    # Gated on the estimation being *this run's*. e() outlives the call that
+    # set it, so every later `summarize` in the session re-reports the same
+    # inherited table through the same fallback — warning on those would be
+    # pure noise about a rebuild the caller did not ask for and cannot act on.
+    estimated_here = (
+        pre_estimation is not None and _estimation_fingerprint(rt) != pre_estimation
+    )
+    if estimated_here and estimation is not None and estimation.source == "e_b_v":
+        warnings.append(
+            StataWarning(
+                kind="estimation_from_e_b_v",
+                message=(
+                    "results.estimation was rebuilt from e(b)/e(V) because r(table) "
+                    "no longer described the current estimation — a later command "
+                    "cleared it. Inference uses "
+                    f"{estimation.statistic_kind!r} as Stata would "
+                    f"(df_r={estimation.df_resid!r}). Put the estimation last in the "
+                    "block, or re-run it alone, to get the r(table) values verbatim."
+                ),
+            )
+        )
+
     # A failed run may have left `log using` handles open. Close only the ones
     # this run opened: a log the caller opened in an earlier successful run is
     # theirs to manage and must survive.
@@ -1599,6 +1661,14 @@ def _collect_results(
     # With results suppressed but estimation wanted, read only the matrices the
     # contract is derived from rather than every matrix in scope.
     named = results_mode != IncludeResults.NONE
+    # e() scalars and macros are inputs to the estimation contract, not just
+    # payload: n_obs, df_model, df_resid, model_stats, the t-vs-z choice and
+    # depvar all come from them. Suppressing them for `include_results="none"`
+    # silently hollowed out `estimation` — a caller who asked only to stop
+    # *echoing* r()/e() lost the model-level numbers that `include_estimation`
+    # is the knob for. Read them whenever estimation is wanted; the wire
+    # projection below still drops them when the caller said "none".
+    e_named = named or want_estimation
     raw = ResultsInfo(
         r=_collect_returns(
             rt,
@@ -1609,7 +1679,7 @@ def _collect_results(
         e=_collect_returns(
             rt,
             "e",
-            want_named=named,
+            want_named=e_named,
             matrix_names=None if named else _ESTIMATION_MATRICES["e"],
         ),
         last_estimation_cmd=_last_estimation_cmd(rt),
@@ -1655,6 +1725,27 @@ def _last_estimation_cmd(rt: Any) -> str | None:
         return None
 
 
+def _estimation_fingerprint(rt: Any) -> tuple[str | None, str | None, float | None]:
+    """Cheap identity for the estimation currently in e-scope.
+
+    Three reads, no matrices: enough to tell one estimation from the next
+    without paying to fetch e(b). Used only to compare before/after a run.
+    """
+    sfi = rt.sfi
+
+    def _macro(name: str) -> str | None:
+        try:
+            return sfi.Macro.getGlobal(name) or None
+        except Exception:  # noqa: BLE001
+            return None
+
+    try:
+        n = sfi.Scalar.getValue("e(N)")
+    except Exception:  # noqa: BLE001
+        n = None
+    return (_macro("e(cmd)"), _macro("e(cmdline)"), _norm_stata_number(n))
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # Multi-session via Stata frames (Module 4)
 # ─────────────────────────────────────────────────────────────────────────────

{stata_code-0.12.1 → stata_code-0.12.2}/stata_code/mcp/server.py

@@ -102,7 +102,7 @@ from stata_code.core.runner import (
 )
 from stata_code.core.schema import RunResult
 
-__version__ = "0.12.1"
+__version__ = "0.12.2"
 
 SERVER_INSTRUCTIONS = (
     "Use stata-code for running and inspecting Stata code. Prefer structuredContent "

{stata_code-0.12.1 → stata_code-0.12.2}/tests/test_agent_ergonomics.py

@@ -374,6 +374,49 @@ class TestJobRegistry:
         assert job.result == "RESULT"
         assert job.finished_at is not None
 
+    def test_elapsed_ms_freezes_when_the_job_finishes(self, monkeypatch):
+        # Recomputing elapsed on every poll made a finished job's duration
+        # grow with the caller's polling delay, so a 2s run polled a minute
+        # later reported a minute of Stata time.
+        from stata_code.core import jobs
+
+        monkeypatch.setattr(jobs, "pool_execute", lambda code, **kw: "RESULT")  # noqa: ARG005
+        registry = jobs.JobRegistry()
+        job = registry.submit("display 1")
+        assert job.wait(5) is True
+
+        first = job.elapsed_ms()
+        time.sleep(0.15)
+        assert job.elapsed_ms() == first
+        assert job.summary()["elapsed_ms"] == first
+
+    def test_elapsed_ms_still_advances_while_running(self, monkeypatch):
+        from stata_code.core import jobs
+
+        gate = threading.Event()
+        monkeypatch.setattr(jobs, "pool_execute", lambda code, **kw: gate.wait(10))  # noqa: ARG005
+        registry = jobs.JobRegistry()
+        job = registry.submit("display 1")
+        first = job.elapsed_ms()
+        time.sleep(0.05)
+        assert job.elapsed_ms() >= first
+        gate.set()
+        job.wait(5)
+
+    def test_elapsed_ms_is_frozen_on_the_error_path_too(self, monkeypatch):
+        from stata_code.core import jobs
+
+        def _boom(code, **kwargs):  # noqa: ARG001
+            raise ValueError("bad option")
+
+        monkeypatch.setattr(jobs, "pool_execute", _boom)
+        registry = jobs.JobRegistry()
+        job = registry.submit("display 1")
+        assert job.wait(5) is True
+        first = job.elapsed_ms()
+        time.sleep(0.15)
+        assert job.elapsed_ms() == first
+
     def test_failure_is_recorded_not_swallowed(self, monkeypatch):
         from stata_code.core import jobs
 

{stata_code-0.12.1 → stata_code-0.12.2}/tests/test_estimation.py

@@ -2,14 +2,20 @@
 
 Covers both extraction paths:
 * ``r(table)`` (referee-grade — values copied exactly as Stata displayed them)
-* ``e(b)`` / ``e(V)`` fallback (se/z/p/CI computed under a normal approximation)
+* ``e(b)`` / ``e(V)`` fallback (se / statistic / p / CI computed here, on the
+  same distribution Stata used: t when ``e(df_r)`` is set, z otherwise)
 """
 
 from __future__ import annotations
 
 import math
 
+import pytest
+
 from stata_code.core.estimation import (
+    _t_crit,
+    _two_sided_t_p,
+    _z_crit,
     build_estimation_from_returns,
     build_estimation_result,
 )
@@ -98,7 +104,56 @@ class TestRTablePath:
 
 
 # ─────────────────────────────────────────────────────────────────────────────
-# e(b)/e(V) fallback — computed se/z/p/CI
+# Distribution helpers — checked against published t-table values
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestDistributions:
+    @pytest.mark.parametrize(
+        ("df", "expected"),
+        [
+            (1, 12.706204736),
+            (5, 2.570581836),
+            (10, 2.228138852),
+            (30, 2.042272456),
+            (70, 1.994437112),
+            (120, 1.979930405),
+            (100000, 1.959987707),
+        ],
+    )
+    def test_t_crit_matches_published_two_sided_95pct_values(self, df, expected):
+        assert math.isclose(_t_crit(float(df), 95.0), expected, rel_tol=1e-8)
+
+    def test_t_crit_converges_to_the_normal_as_df_grows(self):
+        assert math.isclose(_t_crit(1e9, 95.0), _z_crit(95.0), rel_tol=1e-6)
+
+    @pytest.mark.parametrize(
+        ("t", "df", "expected"),
+        [
+            (2.042272456, 30, 0.05),
+            (1.0, 10, 0.340893),
+            (0.29443916691636146, 70, 0.769293740812962),
+            (5.493002930280353, 70, 5.991178e-7),
+        ],
+    )
+    def test_two_sided_t_p_matches_reference_values(self, t, df, expected):
+        assert math.isclose(_two_sided_t_p(t, float(df)), expected, rel_tol=1e-5)
+
+    def test_t_p_is_symmetric_and_bounded(self):
+        for t in (0.0, 0.5, 3.0, 40.0):
+            p = _two_sided_t_p(t, 12.0)
+            assert 0.0 <= p <= 1.0
+            assert math.isclose(p, _two_sided_t_p(-t, 12.0), rel_tol=1e-15)
+        assert math.isclose(_two_sided_t_p(0.0, 12.0), 1.0, rel_tol=1e-12)
+
+    def test_z_crit_matches_known_levels(self):
+        assert math.isclose(_z_crit(95.0), 1.959963984540054, rel_tol=1e-12)
+        assert math.isclose(_z_crit(99.0), 2.5758293035489004, rel_tol=1e-10)
+        assert math.isclose(_z_crit(90.0), 1.6448536269514722, rel_tol=1e-10)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# e(b)/e(V) fallback — computed se / statistic / p / CI
 # ─────────────────────────────────────────────────────────────────────────────
 
 
@@ -128,6 +183,63 @@ class TestBVFallback:
         assert math.isclose(c.ci_low, 10.0 - 1.959963984540054 * 2.0, rel_tol=1e-12)
         assert math.isclose(c.ci_high, 10.0 + 1.959963984540054 * 2.0, rel_tol=1e-12)
 
+    def test_df_r_switches_the_fallback_to_a_t_table(self):
+        # Stata prints a t table whenever e(df_r) is set, so the fallback must
+        # too — otherwise the rebuilt CI silently disagrees with the log.
+        cols = ["x"]
+        e = StataReturns(
+            scalars={"df_r": 70},
+            matrices={"b": _b([10.0], cols), "V": _v([4.0], cols)},
+        )
+        est = build_estimation_from_returns(e, StataReturns())
+        assert est.source == "e_b_v"
+        assert est.statistic_kind == "t"
+        # t(.975, 70) = 1.9944371... — wider than the 1.95996 normal interval.
+        c = est.coefficients[0]
+        assert math.isclose(c.ci_low, 10.0 - 1.9944371112999 * 2.0, rel_tol=1e-9)
+        assert math.isclose(c.ci_high, 10.0 + 1.9944371112999 * 2.0, rel_tol=1e-9)
+
+    def test_fallback_reproduces_statas_printed_regress_table(self):
+        # Values taken from a live `regress price_k mpg weight foreign` on
+        # sysuse auto (N=74, df_r=70). Before the t fix this path returned
+        # [-0.12362, 0.16732] against a log that printed [-.1261758, .169883].
+        cols = ["mpg"]
+        b, se = 0.02185360997213235, 0.07422113776846848
+        e = StataReturns(
+            scalars={"N": 74, "df_m": 3, "df_r": 70},
+            macros={"cmd": "regress", "depvar": "price_k"},
+            matrices={"b": _b([b], cols), "V": _v([se * se], cols)},
+        )
+        est = build_estimation_from_returns(e, StataReturns())
+        c = est.coefficients[0]
+        assert math.isclose(c.ci_low, -0.1261757816711833, rel_tol=1e-9)
+        assert math.isclose(c.ci_high, 0.16988300161544798, rel_tol=1e-9)
+        assert math.isclose(c.p_value, 0.769293740812962, rel_tol=1e-9)
+
+    def test_no_df_r_stays_on_the_normal_approximation(self):
+        # Commands that do not set e(df_r) (ml-family, bootstrap, ...) print a
+        # z table; the fallback must not invent residual degrees of freedom.
+        cols = ["x"]
+        e = StataReturns(
+            scalars={"N": 500},
+            macros={"cmd": "logit"},
+            matrices={"b": _b([10.0], cols), "V": _v([4.0], cols)},
+        )
+        est = build_estimation_from_returns(e, StataReturns())
+        assert est.statistic_kind == "z"
+        assert math.isclose(est.coefficients[0].ci_high, 10.0 + 1.959963984540054 * 2.0)
+
+    def test_e_level_drives_both_ci_level_and_the_critical_value(self):
+        cols = ["x"]
+        e = StataReturns(
+            scalars={"df_r": 70, "level": 90},
+            matrices={"b": _b([10.0], cols), "V": _v([4.0], cols)},
+        )
+        est = build_estimation_from_returns(e, StataReturns())
+        assert est.ci_level == 90.0
+        # t(.95, 70) = 1.6669145... — narrower than the 95% interval.
+        assert math.isclose(est.coefficients[0].ci_high, 10.0 + 1.6669145 * 2.0, rel_tol=1e-7)
+
     def test_no_vcov_yields_point_estimates_only(self):
         cols = ["x"]
         e = StataReturns(matrices={"b": _b([3.0], cols)})  # no V

{stata_code-0.12.1 → stata_code-0.12.2}/tests/test_real_stata.py

@@ -123,6 +123,80 @@ class TestEstimationContractReal:
         assert r.ok, r.error
         assert r.results.estimation is None
 
+    def test_fallback_table_agrees_with_r_table_to_the_last_digit(self):
+        # r(table) is cleared by whatever runs after the estimation, so a block
+        # ending in `graph export` / `esttab` / `summarize` lands on the
+        # e(b)/e(V) path. Both paths must describe the same regression: this
+        # once returned normal-approximation intervals against a log printing
+        # `P>|t|`, so structuredContent silently disagreed with the log.
+        setup = "sysuse auto, clear\ngen price_k = price/1000\n"
+        clean = _run(setup + "regress price_k mpg weight foreign", "rs_rt")
+        stale = _run(setup + "regress price_k mpg weight foreign\nsummarize mpg", "rs_bv")
+        assert clean.ok and stale.ok, (clean.error, stale.error)
+
+        assert clean.results.estimation.source == "r_table"
+        assert stale.results.estimation.source == "e_b_v"
+        assert stale.results.estimation.statistic_kind == "t"
+        assert stale.results.estimation.df_resid == 70
+
+        by_term = {c.term: c for c in clean.results.estimation.coefficients}
+        for c in stale.results.estimation.coefficients:
+            ref = by_term[c.term]
+            assert c.b == pytest.approx(ref.b, rel=1e-12)
+            assert c.se == pytest.approx(ref.se, rel=1e-12)
+            assert c.statistic == pytest.approx(ref.statistic, rel=1e-9)
+            assert c.p_value == pytest.approx(ref.p_value, rel=1e-6, abs=1e-12)
+            assert c.ci_low == pytest.approx(ref.ci_low, rel=1e-9)
+            assert c.ci_high == pytest.approx(ref.ci_high, rel=1e-9)
+
+    def test_rebuilt_table_is_flagged_in_warnings(self):
+        r = _run("sysuse auto, clear\nregress price mpg\nsummarize mpg", "rs_bvwarn")
+        assert r.ok, r.error
+        assert r.results.estimation.source == "e_b_v"
+        kinds = {w.kind for w in r.warnings}
+        assert "estimation_from_e_b_v" in kinds
+
+    def test_inherited_estimation_does_not_warn_on_later_runs(self):
+        # e() is session-global, so `estimation` keeps describing this regress
+        # on every subsequent call. Those runs rebuild from e(b)/e(V) too, but
+        # they estimated nothing — warning on them would be noise.
+        first = _run("sysuse auto, clear\nregress price mpg", "rs_bvquiet")
+        assert first.ok, first.error
+        later = _run("summarize mpg", "rs_bvquiet")
+        assert later.ok, later.error
+        assert later.results.estimation is not None  # inherited from e()
+        assert later.results.estimation.source == "e_b_v"
+        assert [w.kind for w in later.warnings] == []
+
+    def test_estimation_survives_include_results_none(self):
+        # include_results governs how much r()/e() is *echoed*; the model-level
+        # numbers in `estimation` are include_estimation's business. Reading
+        # e() scalars is what makes n_obs / df_resid / model_stats available.
+        r = run(
+            "sysuse auto, clear\nregress price mpg weight",
+            session_id="rs_noresults",
+            include_results="none",
+            include_full_log=False,
+        )
+        assert r.ok, r.error
+        # Nothing echoed on the wire...
+        assert r.results.e.scalars == {} and r.results.e.macros == {}
+        # ...but the contract is intact.
+        est = r.results.estimation
+        assert est is not None
+        assert est.n_obs == 74
+        assert est.df_resid == 71
+        assert est.model_stats.get("r2") == pytest.approx(0.2934, abs=1e-3)
+        assert len(est.coefficients) == 3
+
+    def test_rngstate_macro_is_elided_not_shipped_whole(self):
+        r = _run("sysuse auto, clear\nbootstrap r(mean), reps(20): summarize price", "rs_rng")
+        assert r.ok, r.error
+        rngstate = r.results.e.macros.get("rngstate")
+        assert rngstate is not None, "bootstrap should still report the macro name"
+        assert len(rngstate) < 400
+        assert "chars elided" in rngstate
+
 
 # ─────────────────────────────────────────────────────────────────────────────
 # Error taxonomy — real rc codes, labels, recovery, suggestions

{stata_code-0.12.1 → stata_code-0.12.2}/tests/test_runner_helpers.py

@@ -1040,6 +1040,34 @@ class TestProjectReturns:
         )
         assert out.scalars == {} and out.macros == {} and out.matrices == {}
 
+    def test_oversized_macro_is_elided_with_a_marker(self):
+        # e(rngstate) is ~2 KB of hex on every bootstrap / permute / simulate
+        # run and carries nothing an agent can branch on.
+        from stata_code.core.schema import IncludeResults, StataReturns
+
+        rngstate = "X" + "a1b2c3d4" * 260
+        collected = StataReturns(macros={"cmd": "bootstrap", "rngstate": rngstate})
+        out = runner._project_returns(
+            collected, prefix="e", request_id="req-m", mode=IncludeResults.SCALARS
+        )
+        assert out.macros["cmd"] == "bootstrap"  # short macros pass through
+        capped = out.macros["rngstate"]
+        assert len(capped) < len(rngstate)
+        assert capped.startswith(rngstate[: runner.MACRO_INLINE_CHAR_CAP])
+        assert "chars elided" in capped
+
+    def test_macro_exactly_at_the_cap_is_untouched(self):
+        from stata_code.core.schema import IncludeResults, StataReturns
+
+        exact = "z" * runner.MACRO_INLINE_CHAR_CAP
+        out = runner._project_returns(
+            StataReturns(macros={"m": exact}),
+            prefix="e",
+            request_id="req-e",
+            mode=IncludeResults.SCALARS,
+        )
+        assert out.macros["m"] == exact
+
 
 class TestCollectDataset:
     def test_full_metadata_with_variables(self):