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

{stata_code-0.9.0 → 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.9.0 → stata_code-0.9.1}/CHANGELOG.md

@@ -4,6 +4,152 @@ 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
@@ -226,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`.
@@ -668,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
@@ -750,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.9.0 → stata_code-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stata-code
-Version: 0.9.0
+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:
 
@@ -565,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.9.0 → 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.9.0 → 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:
 
@@ -526,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.9.0 → stata_code-0.9.1}/SCHEMA.md

@@ -360,6 +360,7 @@ Stata's `r()` and `e()` return dictionaries, structurally separated. Each follow
 | 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)`. |
@@ -369,6 +370,7 @@ Stata's `r()` and `e()` return dictionaries, structurally separated. Each follow
 | `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:**
 
@@ -693,7 +695,7 @@ This section tracks how much of the schema is wired up in code. Not normative
   `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

{stata_code-0.9.0 → stata_code-0.9.1}/docs/competitive-landscape.md

@@ -144,8 +144,8 @@ remaining · ⬜ not started.
   with structured results + MCP" converged across StatsPAI and rmcp. Defend by
   positioning on **authoritative Stata-runtime fidelity**, not breadth.
 - **Generic code-exec substitution.** A Jupyter-MCP + statsmodels sandbox can
-  "do econometrics" with zero domain tooling. Defense: *mandated Stata commands
-  + verifiable typed `e()` contracts* a generic sandbox cannot provide.
+  "do econometrics" with zero domain tooling. Defense: *mandated Stata commands +
+  verifiable typed `e()` contracts* a generic sandbox cannot provide.
 - **License contagion.** The two structured/MCP-native competitors (tmonk,
   SepineTam) are AGPL; the kernels are GPL. To preserve our MIT clean-room
   wedge we must never vendor their code paths (see `LICENSE-POLICY.md`).

{stata_code-0.9.0 → stata_code-0.9.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stata-code"
-version = "0.9.0"
+version = "0.9.1"
 description = "Agent-native Stata bridge — one core, multiple frontends (MCP, Jupyter, VSCode)"
 readme = "README.md"
 license = "MIT"

{stata_code-0.9.0 → stata_code-0.9.1}/stata_code/__init__.py

@@ -195,7 +195,7 @@ def is_available() -> bool:
     return True
 
 
-__version__ = "0.9.0"
+__version__ = "0.9.1"
 
 __all__ = [
     # Primary entry points