stata-code 0.8.1__tar.gz → 0.9.1__tar.gz

{stata_code-0.8.1 → stata_code-0.9.1}/.gitignore

@@ -238,3 +238,5 @@ stata_code_test_export.png
 
 # Demo / scratch notebooks (real tests live under tests/)
 demo-tests/*.ipynb
+
+社媒文件/

{stata_code-0.8.1 → stata_code-0.9.1}/CHANGELOG.md

@@ -4,6 +4,218 @@ All notable changes to `stata-code` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project adheres
 to semver-major.minor for the result schema (see `SCHEMA.md` §6).
 
+## [Unreleased]
+
+## 0.9.1 — 2026-07-22
+
+Quality-hardening pass: correctness fixes from an adversarial code review,
+a large offline test expansion, and a documentation accuracy audit. No new
+features, no API or schema changes.
+
+A second review round found that three of the first round's fixes were
+incomplete or had introduced a regression of their own; those are the first
+four entries below. The common failure was testing a fix in isolation while
+the real call path stayed uncovered — the new tests go through `SessionPool`
+rather than `WorkerProcess` wherever the pool is what carries the bug, and
+each was confirmed to fail against the pre-fix source.
+
+### Fixed
+
+- **A read-only status query no longer kills a healthy mid-run worker.**
+  Once `send_simple_op` learned to bail out rather than block on the worker
+  lock, that bail-out surfaced as a `_WorkerTimeout` — and
+  `SessionPool.stata_info` treated "busy" and "dead" identically: it
+  SIGTERMed the worker and dropped it from the pool. Calling the
+  `stata_info` tool during a long `bootstrap`/`reghdfe` therefore returned
+  the user's run as `adapter_crash` and wiped the session's loaded data, and
+  because the MCP layer swallows the exception the kill was invisible in the
+  tool response. Busy is now a distinct `_WorkerBusy` signal (a
+  `_WorkerTimeout` subclass, so warn-only callers are unaffected) that never
+  kills.
+- **A timed-out read no longer steals the next request's response.** Each
+  request spawned its own `readline()` thread and abandoned it on deadline
+  overrun; the orphan stayed blocked on the pipe and consumed the *following*
+  response. The next `execute()` then burned its entire timeout (default
+  600 s) waiting for a reply that had already been eaten, after which the
+  pool killed a perfectly healthy worker. Reads now come off one long-lived
+  pump thread per worker, which cannot orphan, and responses carrying a
+  stale request id are discarded rather than mis-matched.
+- **`send_simple_op` honors its full timeout budget.** The read deadline was
+  computed *after* acquiring the worker lock, so a call that spent most of
+  its budget waiting for the lock got a second full budget for the read —
+  worst case 2x `timeout_ms`, and `list_session_info_detailed` iterates
+  workers serially, so N busy workers stalled the status tool for
+  `2 * timeout * N`. The deadline is now fixed up front.
+- **Repeated identical notes are no longer double-counted.** The previous
+  de-dup short-circuited before recording the matched span, so the second and
+  later copies of an identical `note:` line went unclaimed and were picked up
+  again by the generic-note pass — the exact double-count the fix was meant
+  to remove, reachable from any `foreach` loop re-running the same
+  regression.
+- **`stata_info`'s worker eviction is identity-checked.** It popped the
+  session's worker unconditionally, so a concurrent `execute()` that had
+  already noticed the death and registered a replacement got *its* worker
+  evicted — leaking a live pystata subprocess that `request_cancel` /
+  `kill_session` / `shutdown` could no longer reach.
+- **`kill()`'s already-dead fast path is identity-checked** too, matching its
+  own slow path: it could otherwise clear a handle a concurrent `execute()`
+  had just respawned into, stranding a live subprocess mid-request.
+- **`TypeError` is no longer blanket-classified as a caller error.** The
+  guard wrapped the whole `execute()` call, not just argument binding, so a
+  `TypeError` raised deep inside result collection told the agent its
+  arguments were wrong when nothing was — and routed the failure out of the
+  `adapter_crash` path that would have recycled the wedged worker. Malformed
+  options are now caught by signature binding before the call; deeper
+  `TypeError`s stay in the `worker_error` bucket.
+- **Session ids longer than Stata's 32-character name cap are mapped.** They
+  were passed through verbatim as a frame name, so `frame create` failed with
+  rc 198; they now route through the hashed mapped-frame path.
+
+- **Worker stderr pipe is now drained continuously.** The subprocess pool
+  only read a worker's stderr after death, so a worker whose cumulative
+  stderr output (pystata banners, Stata C-side messages, warnings) exceeded
+  the ~64 KB OS pipe buffer blocked mid-write and never responded — the
+  parent then misreported the healthy worker as a `timeout` and killed it
+  (or hung forever with `timeout_ms=None`). A per-worker daemon thread now
+  drains stderr into a bounded tail buffer, which also enriches crash
+  messages.
+- **A worker-reported failure no longer destroys the session.** A live
+  worker answering `{ok:false, error_kind:"worker_error"}` was handled like
+  a dead process: killed and dropped from the pool, wiping the session's
+  loaded dataset and `r()`/`e()` state — reachable from a mere argument
+  type typo. Such failures now surface as structured errors while the
+  worker (and the session's data) survives; the worker also classifies
+  `TypeError` as `invalid_request`.
+- **LRU eviction skips busy workers.** `last_used` is stale for a mid-run
+  worker, so capacity pressure from an unrelated new session preferred the
+  longest-running request as its eviction victim (SIGTERM mid-run →
+  `adapter_crash`, session data lost). Eviction now skips in-flight
+  workers, bumps `last_used` at request start, and kills victims outside
+  the pool lock; timeout/error cleanup no longer removes a newer worker
+  handle registered in the interim.
+- **Status queries no longer hang behind a long run.** `send_simple_op`
+  blocked unboundedly on the worker lock held by an in-flight `execute()`;
+  lock acquisition now counts against the same timeout budget and surfaces
+  as a per-session "busy" warning.
+- **`rc` is taken from the last `r(NNN);` in a failure transcript.** An
+  earlier successful command echoing a literal `r(NNN);` (display string,
+  help output) previously hijacked the return code — and therefore the
+  `ErrorKind` classification, suggestions, and recovery contract.
+- **Indented notes are no longer double-counted as warnings.** An indented
+  `note: … omitted because of collinearity` line produced both an
+  `omitted_collinear` and a generic `note` warning.
+- **A session literally named `"default"` no longer aliases `"main"`.** In
+  in-process mode it silently shared `main`'s Stata frame (one dataset for
+  two nominally distinct sessions); it now routes through the private
+  mapped-frame path.
+- **Matrices with missing sfi row/col names are no longer dropped.**
+  Positional names (`r1…`/`c1…`) are synthesized instead of letting the
+  shape validator silently discard successfully read values.
+- **`get_graph(format=…)` is no longer a silent no-op.** Requesting a
+  format different from the stored one now returns `invalid_request`
+  instead of returning mismatched bytes.
+- **Post-run file snapshots survive escaping symlinks.** A symlink inside
+  the working dir pointing outside it crashed `changed_output_files` with
+  an uncaught `ValueError`; it is now skipped.
+
+### Added
+
+- **≈300 new offline tests** (467 → 724 passing without Stata); coverage
+  73% → 90% overall (`mcp/server` 74→99%, `kernel` 73→98%, `_pool` 68→96%,
+  `_refs` 68→100%, `log_artifacts` 76→96%, `runner` 29→72%). The package is
+  now fully mypy-clean, including the previously unchecked top-level
+  modules.
+- **Community health files**: `CONTRIBUTING.md` (dev setup + the exact CI
+  gates), `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1), `SECURITY.md`,
+  and GitHub issue templates that ask for `stata-code doctor` output.
+- **Second-round regression tests** for the eight fixes listed above, each
+  verified to fail against the pre-fix source (823 passing locally with
+  Stata). They drive real subprocess workers through `SessionPool` — a
+  status query racing a live run, a worker that drops its first request, a
+  worker that releases the lock partway — rather than asserting on a mocked
+  seam, which is what let the first round's regressions through.
+
+### Docs
+
+- Regenerated the skill's `rc → kind` reference from `errors.py` — it still
+  documented the pre-0.9.0 mappings the taxonomy audit had corrected; fixed
+  the "32 kinds" claims (the enum has 31).
+- `plugin.json` install verify no longer uses `stata-code-mcp --help`
+  (which hangs); it runs `stata-code doctor --no-stata-probe`.
+- PUBLISHING.md / AGENTS.md version-bump lists now cover all eight version
+  literals the release gate checks; removed the stale claim that a built
+  `.vsix` ships in the repo.
+- SCHEMA.md documents `EstimationResult.command_family` and `.diagnostics`;
+  status lines updated v0.8 → v0.9; README.zh.md re-synced with the English
+  README (plugin-marketplace install, per-client MCP config table, Open VSX
+  and first-activation notes, cell/section conventions).
+
+## 0.9.0 — 2026-06-23
+
+### Fixed
+
+- **Error-taxonomy correctness.** Audited the `_rc` → `ErrorKind` table against
+  StataCorp's `[P] error` manual (Stata 19) and corrected several
+  misclassifications: `not_sorted` is now `r(5)` (was the unrelated `r(119)`
+  "statement out of context" / `r(459)` "data is not…"); numlist errors
+  `r(122)`/`r(123)` are now `syntax` (were `invalid_name`); `r(322)` and
+  `r(1400)` map to `estimation_failure` (was `file_not_found` /
+  `estimation_sample_empty`); `r(480)` maps to `infeasible` (was
+  `out_of_memory`); local I/O `r(691)`–`r(693)` map to `file_io` (were
+  `network`). Misleading mappings for `r(9)`/`r(604)`/`r(615)`/`r(616)` were
+  removed (they fall through to `unknown` rather than assert a wrong kind).
+- **Command "did you mean?" now fires.** The `command_not_found` (rc 199) name
+  extractor expected `"<X> unrecognized command"`, but Stata's actual message is
+  `"command <X> is unrecognized"` — so the fuzzy suggestion never matched in
+  practice (synthetic unit tests passed the name in directly and hid it). Fixed
+  the regex and added a real-Stata integration test so a typo like `regresss`
+  now surfaces "Did you mean `regress`?".
+
+### Added
+
+- **Typed estimation contract.** `RunResult.results.estimation` now exposes a
+  frontend-neutral coefficient table derived from verified `r(table)` when
+  possible, or from inline `e(b)` / `e(V)` as a clearly marked fallback. New
+  public helpers `build_estimation_result()` and
+  `build_estimation_from_returns()` keep the contract unit-testable without
+  Stata. The contract also carries a coarse `command_family`
+  (ols/iv/gmm/panel/count/did/…) and command-aware `diagnostics` — identification
+  and specification tests surfaced from `e()` for the commands economists must
+  report (`ivreg2`/`ivreghdfe` weak-ID F and Hansen J, `xtabond2` AR(2)/Hansen,
+  `reghdfe` within-R²/absorbed FE, `xtreg` rho). Only scalars actually present in
+  `e()` are surfaced — never fabricated.
+- **Machine-readable recovery contract.** `error.recovery` now classifies each
+  `ErrorKind` by failure domain and tells agents whether an unchanged retry,
+  code edit, or user/out-of-band action is likely needed. Synthetic timeout,
+  cancellation, and adapter-crash errors carry the same recovery metadata as
+  ordinary Stata errors.
+- **Reproducibility provenance helpers.** New `Provenance`,
+  `build_provenance()`, and `build_reproducible_do()` helpers turn a completed
+  `RunResult` plus original code into a runtime provenance envelope and a
+  re-runnable `.do` script preamble with Stata `version`, `set more off`, and an
+  optional `set seed`. Provenance now also records **per-package dependencies**
+  parsed from the script (`extract_package_installs()` →
+  `Provenance.packages`: `ssc`/`net install` name, source, and `from()` URL),
+  and `build_submission_package()` assembles a self-contained
+  replication/journal-submission bundle (`analysis.do` + `PROVENANCE.json` +
+  a `README.md` manifest listing runtime, seed, and required community packages).
+- **Data-MCP handoff verifier.** New `verify_dataset()` and `DatasetCheck`
+  helpers validate imported datasets against provider metadata such as expected
+  row count, variable count, observation bounds, and required variables.
+- **`error.rc_label` is now populated for real Stata errors.** New
+  `RC_LABEL` table and `label_for_rc()` (public API) supply Stata's canonical
+  short message (e.g. `r(111)` → "variable not found") so agents have a stable,
+  transcript-independent descriptor to branch and group on. Unverified codes
+  yield an empty label rather than a guess.
+- **More return codes classified** (shrinking `unknown`): real network codes
+  `r(2)`/`r(631)`/`r(672)`/`r(677)` → `network`; `r(688)` → `file_corrupt`;
+  `r(907)` → `stata_limit`; `r(950)` → `out_of_memory`; numlist `r(124)`–`r(127)`
+  → `syntax`.
+- **Remediation suggestions for more error kinds.** `suggestions_for()` now
+  emits actionable hints for `network`, `infeasible`, `type_mismatch`,
+  `file_io`, `file_corrupt`, `permission`, `estimation_failure`, and
+  `matrix_missing`, so nearly every common failure ships a recovery hint.
+
 ## 0.8.1 — 2026-06-20
 
 ### Changed
@@ -160,8 +372,8 @@ to semver-major.minor for the result schema (see `SCHEMA.md` §6).
 
 ### Added
 
-- **Claude Code plugin marketplace manifest.** `.claude-plugin/marketplace.json`
-  + `.claude-plugin/plugin.json` expose the repo as a single-plugin
+- **Claude Code plugin marketplace manifest.** `.claude-plugin/marketplace.json` +
+  `.claude-plugin/plugin.json` expose the repo as a single-plugin
   marketplace, so users can install everything (MCP server config + agent
   skill) with `claude plugin marketplace add brycewang-stanford/stata-code`
   followed by `claude plugin install stata-code`.
@@ -602,6 +814,9 @@ Aggregated from the prior `Unreleased` section; covers 0.6.1 and 0.6.2.
   `vscode/package.json`, and the VSCode MCP-client handshake all
   declare `0.3.0`.
 
+- **MCP server tool count is now 8** (added `get_matrix`,
+  `cancel_session`).
+
 ### Added
 
 - **VSCode extension v0.3 — full UI surface** (`vscode/`). Beyond the
@@ -684,11 +899,6 @@ Aggregated from the prior `Unreleased` section; covers 0.6.1 and 0.6.2.
   in-process and has no clean cancel primitive). Hard interruption
   remains deferred to the subprocess-based runtime planned for v0.3+.
 
-### Changed
-
-- **MCP server tool count is now 8** (added `get_matrix`,
-  `cancel_session`).
-
 ## [0.2.0] — 2026-05-07
 
 The first release that actually ships an end-to-end Stata pipeline. The v1.0

{stata_code-0.8.1 → stata_code-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stata-code
-Version: 0.8.1
+Version: 0.9.1
 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
@@ -118,7 +118,7 @@ Then just ask:
               └─────────────┘  └────────────┘  └─────────────────┘
 ```
 
-**Status: v0.8 (June 2026)** — the core, MCP server, Jupyter kernel, and VS Code extension work end-to-end against Stata 18 MP. The test suite covers schema, runner, MCP, kernel, notebook, run-index, subprocess-pool, and VS Code modules; CI also checks linting, type safety, schema generation, package metadata, and VSIX packaging. License: **MIT**.
+**Status: v0.9 (June 2026)** — the core, MCP server, Jupyter kernel, and VS Code extension work end-to-end against Stata 18 MP. The test suite covers schema, runner, MCP, kernel, notebook, run-index, subprocess-pool, and VS Code modules; CI also checks linting, type safety, schema generation, package metadata, and VSIX packaging. License: **MIT**.
 
 Three workflows the current tree explicitly supports for end users and agents:
 
@@ -184,12 +184,14 @@ Verify the local setup with the read-only doctor:
 stata-code doctor
 stata-code doctor --json          # machine-readable output
 stata-code doctor --no-stata-probe # skip live Stata initialization
+stata-code doctor --workspace /path/to/project --no-user-config-scan
 ```
 
 The doctor reports the package/Python version, MCP and Jupyter extras, `pystata`
-discovery, console scripts on `PATH`, client/VS Code configuration hints, and a
-best-effort Stata version/edition probe. It never edits shell, Stata, Claude, or
-VS Code config.
+discovery, console scripts on `PATH`, common project/user MCP client config
+files, client/VS Code configuration hints, and a best-effort Stata
+version/edition probe. It never edits shell, Stata, Claude, Cursor, or VS Code
+config.
 
 ---
 
@@ -418,7 +420,9 @@ If the extension or an MCP client cannot find the server, run
 `stata-code doctor --no-stata-probe` in the same Python environment. It reports
 whether `stata-code-mcp` is on `PATH` and suggests absolute-path or
 `python -m stata_code.mcp` fallbacks for GUI clients whose `PATH` differs from
-your shell.
+your shell. It also reads common MCP config files in the current workspace and
+user config directories so you can see whether a client is already wired to
+`stata-code`.
 
 #### Cell and section conventions
 
@@ -561,10 +565,17 @@ The `stata_required` marker tags the real-Stata integration tests. CI uses `pyte
 
 ## Contributing
 
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the
+development setup, the checks CI runs, and PR guidelines. In short:
+
 - Read [LICENSE-POLICY.md](LICENSE-POLICY.md) before opening a PR.
 - Add a one-line acknowledgement to your first PR description; the template is in the policy file.
 - Tests are required for any new schema field or runner behavior.
 
+Bug reports and support questions go through
+[GitHub issues](https://github.com/brycewang-stanford/stata-code/issues);
+security reports go through [SECURITY.md](SECURITY.md).
+
 ---
 
 ## License

{stata_code-0.8.1 → stata_code-0.9.1}/PUBLISHING.md

@@ -20,12 +20,12 @@ Trusted Publishing has two modes:
 - **Pending publisher** (preferred for the first release of a brand-new
   project): you configure the trusted publisher *before* the project exists
   on PyPI, and the first successful publish creates it. Go to
-  https://pypi.org/manage/account/publishing/ and add a "pending publisher"
+  <https://pypi.org/manage/account/publishing/> and add a "pending publisher"
   with the values listed in step 2.
 - **Existing project**: if you already pushed an initial release manually
   (e.g. via `twine upload` with a one-off API token), configure trusted
   publishing on the project page at
-  https://pypi.org/manage/project/stata-code/settings/publishing/.
+  <https://pypi.org/manage/project/stata-code/settings/publishing/>.
 
 Either path lands you in the same place after the first run.
 
@@ -76,30 +76,39 @@ The environment doesn't need any secrets — Trusted Publishing handles auth.
 
 Once the one-time setup above is done, every release is just:
 
-1. **Bump the version everywhere**:
+1. **Bump the version everywhere** (eight literals across six files —
+   `scripts/check_versions.py` gates the release build on all of them):
    - `pyproject.toml` → `[project] version`
    - `stata_code/__init__.py` → `__version__`
    - `stata_code/mcp/server.py` → `__version__`
    - `vscode/package.json` → `version`
-   - `vscode/package-lock.json` → root package `version`
+   - `vscode/package-lock.json` → top-level `version` **and** `packages[""].version`
+   - `.claude-plugin/plugin.json` → `version`
+   - `.claude-plugin/marketplace.json` → `metadata.version` **and** each `plugins[*].version`
 2. **Run the version guard** before tagging:
+
    ```bash
    python scripts/check_versions.py
    ```
+
 3. **Update `CHANGELOG.md`**: move the `[Unreleased]` entries under a new
    `## [X.Y.Z] - YYYY-MM-DD` heading, leaving an empty `[Unreleased]` shell
    on top.
 4. **Commit** the bump:
+
    ```bash
    git add pyproject.toml stata_code/__init__.py stata_code/mcp/server.py vscode/package.json vscode/package-lock.json CHANGELOG.md
    git commit -m "release: vX.Y.Z"
    ```
+
 5. **Tag and push**:
+
    ```bash
    git tag vX.Y.Z
    git push origin main
    git push origin vX.Y.Z
    ```
+
 6. Watch the **`release` workflow** under the Actions tab. It will:
    - build the sdist + wheel
    - run `twine check` on the artifacts
@@ -127,14 +136,14 @@ version if a publish has already succeeded under that number.
 
 ## Manual / emergency publish
 
-`release.yml` also accepts `workflow_dispatch`, so you can trigger a build
-+ publish from the Actions UI without pushing a tag. The `github-release`
+`release.yml` also accepts `workflow_dispatch`, so you can trigger a build +
+publish from the Actions UI without pushing a tag. The `github-release`
 job will fail in that mode (no tag to attach to) — that's fine; the PyPI
 publish itself will have already happened in `publish-pypi`.
 
 If Trusted Publishing is broken for some reason and you need an emergency
 release, generate a short-lived API token at
-https://pypi.org/manage/account/token/ and run locally:
+<https://pypi.org/manage/account/token/> and run locally:
 
 ```bash
 python -m build

{stata_code-0.8.1 → stata_code-0.9.1}/README.md

@@ -79,7 +79,7 @@ Then just ask:
               └─────────────┘  └────────────┘  └─────────────────┘
 ```
 
-**Status: v0.8 (June 2026)** — the core, MCP server, Jupyter kernel, and VS Code extension work end-to-end against Stata 18 MP. The test suite covers schema, runner, MCP, kernel, notebook, run-index, subprocess-pool, and VS Code modules; CI also checks linting, type safety, schema generation, package metadata, and VSIX packaging. License: **MIT**.
+**Status: v0.9 (June 2026)** — the core, MCP server, Jupyter kernel, and VS Code extension work end-to-end against Stata 18 MP. The test suite covers schema, runner, MCP, kernel, notebook, run-index, subprocess-pool, and VS Code modules; CI also checks linting, type safety, schema generation, package metadata, and VSIX packaging. License: **MIT**.
 
 Three workflows the current tree explicitly supports for end users and agents:
 
@@ -145,12 +145,14 @@ Verify the local setup with the read-only doctor:
 stata-code doctor
 stata-code doctor --json          # machine-readable output
 stata-code doctor --no-stata-probe # skip live Stata initialization
+stata-code doctor --workspace /path/to/project --no-user-config-scan
 ```
 
 The doctor reports the package/Python version, MCP and Jupyter extras, `pystata`
-discovery, console scripts on `PATH`, client/VS Code configuration hints, and a
-best-effort Stata version/edition probe. It never edits shell, Stata, Claude, or
-VS Code config.
+discovery, console scripts on `PATH`, common project/user MCP client config
+files, client/VS Code configuration hints, and a best-effort Stata
+version/edition probe. It never edits shell, Stata, Claude, Cursor, or VS Code
+config.
 
 ---
 
@@ -379,7 +381,9 @@ If the extension or an MCP client cannot find the server, run
 `stata-code doctor --no-stata-probe` in the same Python environment. It reports
 whether `stata-code-mcp` is on `PATH` and suggests absolute-path or
 `python -m stata_code.mcp` fallbacks for GUI clients whose `PATH` differs from
-your shell.
+your shell. It also reads common MCP config files in the current workspace and
+user config directories so you can see whether a client is already wired to
+`stata-code`.
 
 #### Cell and section conventions
 
@@ -522,10 +526,17 @@ The `stata_required` marker tags the real-Stata integration tests. CI uses `pyte
 
 ## Contributing
 
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the
+development setup, the checks CI runs, and PR guidelines. In short:
+
 - Read [LICENSE-POLICY.md](LICENSE-POLICY.md) before opening a PR.
 - Add a one-line acknowledgement to your first PR description; the template is in the policy file.
 - Tests are required for any new schema field or runner behavior.
 
+Bug reports and support questions go through
+[GitHub issues](https://github.com/brycewang-stanford/stata-code/issues);
+security reports go through [SECURITY.md](SECURITY.md).
+
 ---
 
 ## License

{stata_code-0.8.1 → stata_code-0.9.1}/SCHEMA.md

@@ -77,7 +77,38 @@ Every successful or failed Stata execution returns one result object:
         }
       }
     },
-    "last_estimation_cmd": "regress"
+    "last_estimation_cmd": "regress",
+    "estimation": {
+      "command": "regress",
+      "depvar": "mpg",
+      "n_obs": 74,
+      "df_model": 1,
+      "df_resid": null,
+      "statistic_kind": "z",
+      "source": "e_b_v",
+      "ci_level": 95.0,
+      "coefficients": [
+        {
+          "term": "weight",
+          "b": -0.006,
+          "se": null,
+          "statistic": null,
+          "p_value": null,
+          "ci_low": null,
+          "ci_high": null
+        },
+        {
+          "term": "_cons",
+          "b": 39.44,
+          "se": null,
+          "statistic": null,
+          "p_value": null,
+          "ci_low": null,
+          "ci_high": null
+        }
+      ],
+      "model_stats": {"N": 74, "df_m": 1, "r2": 0.219}
+    }
   },
 
   "dataset": {
@@ -140,7 +171,8 @@ A failed execution sets `ok: false`, `rc != 0`, and populates `error`:
 
   "results": { "r": {"scalars": {}, "macros": {}, "matrices": {}},
                "e": {"scalars": {}, "macros": {}, "matrices": {}},
-               "last_estimation_cmd": null },
+               "last_estimation_cmd": null,
+               "estimation": null },
 
   "dataset": { "frame": "default", "n_obs": 74, "n_vars": 12, "changed": false,
                "filename": "auto.dta", "variables": null },
@@ -167,7 +199,13 @@ A failed execution sets `ok: false`, `rc != 0`, and populates `error`:
     "suggestions": [
       {"action": "Check the variable name. Did you mean `mpg`?",
        "command": "describe"}
-    ]
+    ],
+    "recovery": {
+      "category": "user_code",
+      "retriable": false,
+      "needs_code_change": true,
+      "needs_user_input": false
+    }
   },
 
   "schema_version": "1.0",
@@ -315,6 +353,36 @@ Stata's `r()` and `e()` return dictionaries, structurally separated. Each follow
 | Field | Type | Notes |
 | --- | --- | --- |
 | `last_estimation_cmd` | `string \| null` | Mirrors `e(cmd)` for callers who don't want to dig into `e.macros`. After multi-command code, this reflects the *last* command that wrote to `e()`. `null` if no estimation has been performed. |
+| `estimation` | `EstimationResult \| null` | Typed coefficient table derived from `r(table)` or `e(b)` / `e(V)`. `null` when no inline `e(b)` is available. |
+
+**`EstimationResult` shape:**
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `command` | `string \| null` | Mirrors `e(cmd)` when available; falls back to `last_estimation_cmd`. |
+| `command_family` | `string \| null` | Coarse estimator family derived from the command name (`ols` / `iv` / `gmm` / `panel` / `count` / `did` / …); `null` when the command is unrecognized. |
+| `depvar` | `string \| null` | Mirrors `e(depvar)`. |
+| `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. |
+| `ci_level` | `number` | Confidence level used for `ci_low` / `ci_high`; currently `95.0`. |
+| `coefficients` | `array<Coefficient>` | One row per term in `e(b)`. |
+| `model_stats` | `dict<str, number \| null>` | High-signal subset of `e()` scalars such as `N`, `df_m`, `df_r`, `r2`, `F`, `chi2`, `ll`, and `rmse`. Full scalars remain under `results.e.scalars`. |
+| `diagnostics` | `dict<str, number \| null>` | Command-aware identification/specification statistics surfaced from `e()` (e.g. weak-ID F and Hansen J for `ivreg2`/`ivreghdfe`, AR(2)/Hansen for `xtabond2`, within-R² for `reghdfe`, `rho` for `xtreg`). Only scalars actually present in `e()` appear — never fabricated. |
+
+**`Coefficient` shape:**
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `term` | `string` | Term / coefficient column name. |
+| `b` | `number \| null` | Point estimate. |
+| `se` | `number \| null` | Standard error when available. |
+| `statistic` | `number \| null` | `t` or `z`, per `EstimationResult.statistic_kind`. |
+| `p_value` | `number \| null` | Two-sided p-value when available. |
+| `ci_low` | `number \| null` | Lower confidence interval bound when available. |
+| `ci_high` | `number \| null` | Upper confidence interval bound when available. |
 
 **Empty is empty.** Sub-dicts are `{}` when Stata returned nothing — never absent, never `null`.
 
@@ -377,6 +445,7 @@ Populated iff `ok: false`. The schema's most important contribution to agent UX:
 | `varname` | `string \| null` | For `varname_not_found` and related, the variable name at issue. |
 | `name` | `string \| null` | For `name_conflict` and `invalid_name`, the conflicting/invalid name. |
 | `suggestions` | `array<Suggestion>` | Producer-supplied remediation hints. Empty when none apply. See below. |
+| `recovery` | `Recovery \| null` | Machine-readable recovery contract for agents. Present on current producers; old or third-party producers may omit it, so consumers should handle `null`. |
 
 **`context` shape:**
 
@@ -399,36 +468,47 @@ Populated iff `ok: false`. The schema's most important contribution to agent UX:
 
 Suggestions are best-effort; agents should treat them as hints, not directives. A suggestion is not consent to mutate source files or silently retry changed code; consumers should apply fixes automatically only in workflows where the user requested repair or approved iteration. The `kind` enum below documents what suggestions are typically populated.
 
+**`Recovery` shape:**
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `category` | `"user_code" \| "data" \| "model" \| "resource" \| "environment" \| "internal" \| "unknown"` | Broad failure domain for routing. |
+| `retriable` | `bool` | Whether re-running the exact same code may succeed. True mainly for transient environment or producer-side failures. |
+| `needs_code_change` | `bool` | Whether the submitted Stata code must change to succeed. |
+| `needs_user_input` | `bool` | Whether resolution likely requires a human or out-of-band action such as permissions, license/edition limits, or re-acquiring a corrupt file. |
+
 **`kind` enum (v1.0):**
 
+rc(s) below cite StataCorp `[P] error` (Stata 19, 2025). The code is authoritative; this table is a readable mirror.
+
 | `kind` | Typical rc(s) | Notes / suggestion seed |
 | --- | --- | --- |
-| `syntax` | 9, 100, 101, 102, 103, 121, 130, 132, 197, 198 | Generic parser failure. No automatic suggestion. |
+| `syntax` | 100, 101, 102, 103, 121–127, 130, 132, 197, 198 | Generic parser failure (incl. numlist errors 121–127). No automatic suggestion. |
 | `command_not_found` | 199 | Often resolved by `ssc install` or `net install`; suggestions populated when Stata reports a likely package name. |
 | `varname_not_found` | 111 | `varname` populated. Suggestions may include similar varnames from `dataset.variables`. |
-| `invalid_name` | 122, 123 | `name` populated. |
-| `type_mismatch` | 109, 408 | |
+| `invalid_name` | (no dedicated rc) | Stata folds "invalid name" into r(198). `name` populated when constructed by a producer. |
+| `type_mismatch` | 109, 408 | Suggestion: `destring`/`tostring`. |
 | `name_conflict` | 110 | `name` populated. Suggestion typically: `replace`. |
-| `not_sorted` | 119, 459 | Suggestion: `sort <varlist>`. |
+| `not_sorted` | 5 | Suggestion: `sort <varlist>`. |
 | `convergence` | 430 | |
-| `infeasible` | 491 | Distinct from convergence: starting values not feasible. |
-| `estimation_sample_empty` | 1400, 2000 (in estimation context) | |
-| `estimation_failure` | 1401, 1402 | |
+| `infeasible` | 480, 491 | Distinct from convergence: starting values not feasible (e.g. `nl`, `ml`). |
+| `estimation_sample_empty` | (no dedicated rc) | Empty estimation samples surface as r(2000); producer-set otherwise. |
+| `estimation_failure` | 322, 1400, 1401, 1402 | Postestimation/prefix saw an unexpected result, or numerical overflow. |
 | `no_estimation_results` | 301 | Common when calling `predict`/`margins` without prior estimation. |
 | `no_observations` | 2000, 2001 | |
 | `data_in_memory` | 4 | Suggestion: `clear`. |
 | `matrix_singular` | 506, 508 | Matrix not positive definite / not invertible. |
-| `matrix_conformability` | 503, 507 | Dimension mismatch. |
+| `matrix_conformability` | 503, 507 | Dimension mismatch; 507 is a `matrix post` row/col name conflict kept in the matrix bucket. |
 | `matrix_missing` | 504 | Matrix has missing values. |
-| `file_not_found` | 322, 601 | `path` populated. |
+| `file_not_found` | 601 | `path` populated. |
 | `file_exists` | 602 | `path` populated. Suggestion: pass `replace` option. |
-| `file_corrupt` | 604, 610 | `path` populated. Often "not a Stata file." |
-| `file_io` | 603, 691 (local) | `path` populated. Catch-all for open/read/write failures not otherwise classified. |
-| `network` | 691 (network), 692, 693 | URL fetches, network reads. |
-| `permission` | 608 | `path` populated. Includes Stata-license-limit errors (615/616 family that surface as permission denials). |
-| `encoding` | 615, 616 | Unicode / encoding-conversion failures. |
-| `stata_limit` | 901, 902, 903 | Edition / matsize / similar Stata-imposed caps. Distinct from OS OOM. Suggestion: `set maxvar` or upgrade edition. |
-| `out_of_memory` | 480, 909 | OS-level memory exhaustion. |
+| `file_corrupt` | 610, 688 | `path` populated. "Not a Stata file" (610) or genuinely corrupt (688). |
+| `file_io` | 603, 691, 692, 693 | `path` populated. Catch-all for open/read/write failures (691–693 are local filesystem I/O). |
+| `network` | 2, 631, 672, 677 | Connection timed out / host not found / server refused / remote connection failed. |
+| `permission` | 608 | `path` populated. File is read-only / not writable. |
+| `encoding` | (no dedicated rc) | Unicode / encoding-conversion failures; producer-set. |
+| `stata_limit` | 901, 902, 903, 907 | Edition / maxvar / width caps. Distinct from OS OOM. Suggestion: `set maxvar` or upgrade edition. |
+| `out_of_memory` | 909, 950 | OS-level memory exhaustion. Suggestion: `compress`. |
 | `interrupt` | 1 | User Break / Ctrl-C from a frontend. |
 | `cancelled` | (synthetic `rc: -3`) | Cancellation was requested. Subprocess-backed producers may terminate an in-flight worker; the direct in-process runner only short-circuits before Stata receives code. |
 | `timeout` | (synthetic `rc: -2`) | Adapter-imposed time limit exceeded. |
@@ -607,17 +687,20 @@ This section tracks how much of the schema is wired up in code. Not normative
   emit a `matrix://<request_id>/<r|e>/<name>` ref instead, retrievable
   via `get_matrix(ref)`.
 - `results.last_estimation_cmd` (mirrors `e(cmd)`).
+- `results.estimation` typed coefficient table, copied from verified
+  `r(table)` when possible and otherwise derived from inline `e(b)` / `e(V)`.
 - `dataset` block — `n_obs`, `n_vars`, `frame`, `changed`, `filename`,
   and `variables` (capped at 200 entries).
 - `graphs[]` with `ref` + on-disk capture pipeline; format restricted to
   `png` / `svg` / `pdf`; PNG `width` / `height` parsed from IHDR;
   best-effort `source_command` / `source_line` attribution from the
   submitted code. `inline` populated when `include_graphs="inline"`.
-- Structured `error` — 32-kind enum, `varname` / `path` / `name`
+- Structured `error` — 31-kind enum, `varname` / `path` / `name`
   extracted from Stata's English error text by regex, structured
   `context` (`{before, failing, after}`), `commands_executed` parsed
   from pystata's multi-line transcript, `suggestions` generated by
-  `core.errors.suggestions_for`.
+  `core.errors.suggestions_for`, and `recovery` generated by
+  `core.errors.recovery_for`.
 - `request_id` (uuid4 hex), `started_at` (ISO 8601 UTC ms),
   `stata_elapsed_ms`, `capabilities`.
 - Multi-session via Stata frames — `session_id="main"` ↔ `default`