petfishframework 0.4.2__tar.gz → 0.5.0__tar.gz

petfishframework-0.5.0/.sisyphus/plans/v0.5.0-plan.md

@@ -0,0 +1,327 @@
+# petfishFramework v0.5.0 开发计划
+
+> 基于 v0.4.5 状态 + production readiness roadmap + 全部 deferred 项
+> 目标：Tool / MCP Governance — 把工具和 MCP 作为企业能力资产治理
+> 原则：**TDD 先行，pre_release.py 门禁，文档同步作为完成条件**
+
+## v0.5.0 使命
+
+> 每个工具有验证过的输入、有界的执行（timeout/retry/rate）、分类的风险与默认策略。
+> MCP server 被 allowlist 管理、health-checked、schema-pinned。
+> 没有工具在 ungoverned 状态下执行。
+
+## v0.4.5 基线（代码核实）
+
+| 能力 | 状态 | 位置 |
+|---|---|---|
+| `TimeoutPolicy` / `with_timeout` | 独立工具 — **未接入 tool calls** | `reliability/timeout.py:28` |
+| `RetryPolicy` / `with_retry` | 独立工具 — 仅 `RetryModelAdapter` 用于 models | `reliability/retry.py:39` |
+| `BaseTool` metadata | 字段存在但**不强制** | `tools/base.py:16` |
+| `input_schema` | 每个工具都有 — **从未验证** | `tools/base.py:24` |
+| `RuntimeEnvironment.call()` | 权限门 ✓ budget ✓ audit ✓ — **无 schema/timeout/retry/ratelimit** | `core/environment.py:115` |
+| `RiskLevel` enum | LOW/MEDIUM/HIGH/CRITICAL — **纯 metadata，无默认策略** | `core/contracts.py:31` |
+| MCP client | `connect_stdio` + `MCPToolWrapper` 可用 | `mcp/client.py:59` |
+| `serve_as_mcp` | `NotImplementedError` stub | `mcp/server.py:7` |
+| CredentialBroker + ScopedToken | 工作模式（max_uses, TTL） | `credentials/broker.py`, `token.py` |
+| 测试 | 308 tests, `asyncio_mode=auto` | `pyproject.toml:55` |
+
+## 设计决策
+
+### D1 — Schema validation 位置与 PARTIAL_ALLOW 交互
+
+新建 `ToolSchemaValidator` 类，接入 `RuntimeEnvironment.call()`，位于权限门之后、PARTIAL_ALLOW arg-filtering 之后、credential injection 之前。
+
+- 验证失败 → `ToolResult(error="schema_violation: <detail>")`，工具不执行，发出 `tool.schema_violation` 事件。
+- **无硬依赖**：内置轻量 validator 覆盖 type/required/properties/enum/additionalProperties。`jsonschema` 作为可选 extra（`pip install petfishframework[schema]`），按 OTel/Vault 模式优雅降级。
+- PARTIAL_ALLOW 交互：验证在字段过滤**之后**运行，验证的是实际将执行的缩减参数集。
+- **默认 opt-in（lenient）**：不破坏现有 308 测试和用户代码。
+
+### D2 — Rate limiting 粒度与计数器位置
+
+`RateLimitPolicy` dataclass（per-tool `max_calls` + `window_s`）+ `RateLimiter` 类，**session-scoped** 滑动窗口计数器（keyed by `(session_id, tool_name)` → deque of timestamps）。RuntimeEnvironment 可选字段。
+
+- 超限 → `ToolResult(error="rate_limited")`，发出 `tool.rate_limited` 事件，工具不执行。
+- Session-scoped（非全局），匹配现有 `session_id` 字段。Per-tenant → v0.6。
+
+### D3 — Risk classification 默认行为
+
+新建 `RiskClassificationPolicy`（implements `PermissionPolicy`）。映射 `RiskLevel` → 默认 `DecisionEffect`：
+- CRITICAL/HIGH → REQUIRE_APPROVAL
+- MEDIUM/LOW → ALLOW
+
+可组合（deny-overrides）。**不改 RiskLevel enum 或现有工具。Opt-in。**
+
+### D4 — Sandbox 隔离方案
+
+**v0.5 不实现 sandbox execution。** 推迟到 v0.6+。
+
+理由：subprocess 隔离在 Alpha 框架中暗示安全边界，无法充分支持。Phase A-D 交付 ~90% 治理价值且风险低。sandbox 作为独立 Phase E 可选，但默认 deferred。
+
+### D5 — MCP 治理范围
+
+聚焦 **MCP client governance**。MCP server mode（`serve_as_mcp`）推迟到 v0.6+。
+
+v0.5 交付：allowlist、schema pinning、risk mapping、health check、lifecycle management。
+
+### D6 — Commit 粒度
+
+Per-feature commit（14 个 commit），每个独立通过 pytest + ruff。
+
+---
+
+## Phase A — Tool Schema Validation & Metadata Foundation
+
+### A1: Tool Schema Strict Validation
+
+**TDD tests** (`tests/test_tool_schema.py`, 5 tests):
+```
+test_valid_args_pass_validation          — args 匹配 schema → 正常执行
+test_missing_required_field_rejected     — required 字段缺失 → schema_violation error，不执行
+test_wrong_type_rejected                 — string 给 int 字段 → 拒绝
+test_additional_properties_rejected      — additionalProperties:false 时多余字段 → 拒绝
+test_validation_after_partial_allow      — PARTIAL_ALLOW 剥离字段后验证缩减集
+```
+
+**Implementation**:
+- `src/petfishframework/tools/schema_validator.py` — `ToolSchemaValidator.validate(schema, args) -> list[str]`
+- 内置 validator: type/required/properties/enum/additionalProperties；`jsonschema` 可选委托
+- `pyproject.toml`: `schema = ["jsonschema>=4.0"]`
+- 接入 `RuntimeEnvironment.call()` / `call_async()`，位于 PARTIAL_ALLOW filter 和 credential injection 之间
+- 新事件: `tool.schema_violation`
+
+**Files**: `tools/schema_validator.py` (new), `tests/test_tool_schema.py` (new), `core/environment.py` (modify), `tools/__init__.py` (modify), `pyproject.toml` (modify)
+
+### A2: Tool Metadata Required (strict/lenient mode)
+
+**TDD tests** (`tests/test_tool_metadata.py`, 3 tests):
+```
+test_tool_with_full_metadata_passes_strict    — 全 metadata → OK
+test_tool_missing_metadata_rejected_in_strict — strict + 缺 risk_level → 注册时拒绝
+test_lenient_mode_warns_not_blocks            — lenient + 缺 side_effect → warning，继续
+```
+
+**Implementation**:
+- `ToolMetadataPolicy` dataclass: `mode: Literal["strict","lenient"] = "lenient"`
+- 在 `RuntimeEnvironment` 构造时验证（非每次调用）
+- 默认 lenient（向后兼容）
+
+**Files**: `tools/metadata_policy.py` (new), `tests/test_tool_metadata.py` (new), `core/environment.py` (modify), `tools/__init__.py` (modify)
+
+---
+
+## Phase B — Execution Hardening
+
+### B1: Wire TimeoutPolicy into tool calls
+
+**TDD tests** (`tests/test_tool_timeout.py`, 3 tests):
+```
+test_tool_timeout_enforced            — 慢工具 + timeout → OperationTimedOut → ToolResult(error)
+test_no_timeout_default               — 无 timeout policy → 正常执行
+test_timeout_returns_error_not_raise  — timeout 被捕获，返回 ToolResult，session 继续
+```
+
+**Implementation**:
+- `RuntimeEnvironment.call()` 用 `with_timeout` 包装 `tool.execute(args)`
+- 捕获 `OperationTimedOut` → `ToolResult(error="timeout after Xs")` + `tool.timeout` 事件
+- `call_async()` 用 `asyncio.wait_for`
+- `RuntimeEnvironment` 新字段: `timeout_policy: TimeoutPolicy | None = None`
+
+**Files**: `core/environment.py` (modify), `tests/test_tool_timeout.py` (new)
+
+### B2: Wire RetryPolicy into tool calls
+
+**TDD tests** (`tests/test_tool_retry.py`, 3 tests):
+```
+test_tool_retry_succeeds_on_retry   — flaky tool 失败一次后成功 → retry，返回值
+test_tool_no_retry_by_default       — retry_policy=None → 不重试
+test_tool_retry_exhausted           — 持续失败 + max_retries → RetryableError → ToolResult(error)
+```
+
+**Implementation**:
+- 可选 `retry_policy: RetryPolicy | None` per-tool（`BaseTool.retry_policy` 字段）或 env 级别
+- **硬门控**: 仅当 `tool.idempotent == True` 时才重试（非幂等工具重试会导致副作用重复）
+- 用 `with_retry` 包装 `tool.execute`
+
+**Files**: `core/environment.py` (modify), `tools/base.py` (modify), `tests/test_tool_retry.py` (new)
+
+### B3: Idempotency Key Support
+
+**TDD tests** (`tests/test_tool_idempotency.py`, 3 tests):
+```
+test_same_idempotency_key_returns_cached      — 相同 key → 缓存结果，不重复执行
+test_different_idempotency_key_executes       — 不同 key → 再次执行
+test_idempotent_tool_without_key_executes_each — 无 key → 正常执行（不 dedup）
+```
+
+**Implementation**:
+- `IdempotencyStore`: `dict[idempotency_key, ToolResult]` + TTL，session-scoped
+- 执行前检查 `args.get("_idempotency_key")`，命中缓存则返回，发出 `tool.idempotent_cache_hit`
+- `BaseTool` 新字段: `supports_idempotency_key: bool = False`
+
+**Files**: `tools/idempotency.py` (new), `tests/test_tool_idempotency.py` (new), `core/environment.py` (modify), `tools/base.py` (modify)
+
+---
+
+## Phase C — Rate Limiting & Risk Classification
+
+### C1: RateLimiter
+
+**TDD tests** (`tests/test_rate_limiter.py`, 4 tests):
+```
+test_under_limit_executes        — 3/5 → 全部执行
+test_at_limit_executes           — 5/5 → 全部执行（边界）
+test_over_limit_blocked          — 第6次在窗口内 → rate_limited error，不执行
+test_window_reset_allows_again   — window_s 过后 → 计数器重置，调用成功
+```
+
+**Implementation**:
+- `tools/rate_limiter.py` — `RateLimitPolicy` (frozen dataclass) + `RateLimiter` (sliding window via `collections.deque`)
+- `RuntimeEnvironment` 字段: `rate_limiter: RateLimiter | None = None`
+- Per-tool 限制 via `BaseTool.rate_limit: RateLimitPolicy | None`
+- 发出 `tool.rate_limited` 事件
+
+**Files**: `tools/rate_limiter.py` (new), `tests/test_rate_limiter.py` (new), `core/environment.py` (modify), `tools/base.py` (modify), `tools/__init__.py` (modify)
+
+### C2: Risk Classification Policy
+
+**TDD tests** (`tests/test_risk_classification.py`, 3 tests):
+```
+test_high_risk_defaults_to_require_approval  — HIGH tool + 无显式规则 → REQUIRE_APPROVAL
+test_explicit_allow_overrides_default        — YamlPolicy ALLOW 规则对 HIGH tool 生效
+test_compose_with_yaml_deny_overrides        — risk policy ALLOW + yaml DENY → DENY
+```
+
+**Implementation**:
+- `permissions/risk_policy.py` — `RiskClassificationPolicy(PermissionPolicy)`
+- 可配置映射: `defaults: dict[RiskLevel, DecisionEffect]`
+- 可组合: deny-overrides via `CompositePolicy` wrapper
+
+**Files**: `permissions/risk_policy.py` (new), `tests/test_risk_classification.py` (new), `permissions/__init__.py` (modify)
+
+---
+
+## Phase D — MCP Client Governance
+
+### D1: MCP Server Allowlist
+
+**TDD tests** (`tests/test_mcp_allowlist.py`, 3 tests):
+```
+test_allowed_server_connects      — allowlist 中的 server → 连接成功
+test_blocked_server_rejected      — 不在 allowlist → ConnectionRefused
+test_empty_allowlist_denies_all   — 空 allowlist + strict → 全部拒绝
+```
+
+**Files**: `mcp/allowlist.py` (new), `tests/test_mcp_allowlist.py` (new), `mcp/client.py` (modify), `mcp/__init__.py` (modify)
+
+### D2: MCP Tool Schema Pinning *(depends on A1)*
+
+**TDD tests** (`tests/test_mcp_schema_pin.py`, 3 tests):
+```
+test_pin_freezes_schema        — pin 发现的 schemas → 快照存储
+test_drift_detected_on_change  — server 改变 schema → drift 报告
+test_repin_updates_snapshot    — 显式 repin → 新快照替换旧
+```
+
+**Files**: `mcp/schema_pin.py` (new), `tests/test_mcp_schema_pin.py` (new), `mcp/client.py` (modify), `mcp/__init__.py` (modify)
+
+### D3: MCP Tool Risk Mapping
+
+**TDD tests** (`tests/test_mcp_risk_mapping.py`, 2 tests):
+```
+test_auto_classify_by_capabilities  — MCP tool 有 "fs:write" → HIGH risk
+test_custom_mapping_overrides       — 显式 risk map → 覆盖自动分类
+```
+
+**Files**: `mcp/risk_mapper.py` (new), `tests/test_mcp_risk_mapping.py` (new), `mcp/client.py` (modify), `mcp/wrapper.py` (modify)
+
+### D4: MCP Server Health Check + Lifecycle
+
+**TDD tests** (`tests/test_mcp_lifecycle.py`, 4 tests):
+```
+test_health_check_ok            — 活 server → health() 返回 True
+test_health_check_fail          — 死 server → health() 返回 False
+test_disconnect_terminates_proc — close() → subprocess 终止，无 zombie
+test_reconnect_after_drop       — server drop → reconnect() 重建连接
+```
+
+**Files**: `tests/test_mcp_lifecycle.py` (new), `mcp/client.py` (modify), `mcp/stdio_transport.py` (modify), `mcp/__init__.py` (modify)
+
+---
+
+## Phase E — Sandbox Execution (DEFERRED to v0.6+)
+
+v0.5 不实现 sandbox。理由见设计决策 D4。
+
+---
+
+## 依赖图与并行化
+
+```
+Wave 1 (完全独立，可并行):
+  A1 (schema)  A2 (metadata)  B1 (timeout)  B2 (retry)  B3 (idempotency)
+  C1 (rate)    C2 (risk)
+
+Wave 2 (依赖 Wave 1):
+  D2 (schema pin) ───── depends on A1
+
+Wave 3 (MCP governance cluster):
+  D1 (allowlist)   D3 (risk mapping)   D4 (health/lifecycle)
+```
+
+Wave 1 的 7 个 feature 完全独立 — 可并行 7 个 sub-agent。
+Wave 2 的 1 个 feature 可在 Wave 1 后并行。
+Wave 3 的 3 个 feature 可在 Wave 2 后并行。
+
+## 测试预估
+
+| Phase | Feature | 新测试 |
+|---|---|---|
+| A | A1 schema validation | 5 |
+| A | A2 metadata policy | 3 |
+| B | B1 timeout wiring | 3 |
+| B | B2 retry wiring | 3 |
+| B | B3 idempotency | 3 |
+| C | C1 rate limit | 4 |
+| C | C2 risk classification | 3 |
+| D | D1 MCP allowlist | 3 |
+| D | D2 schema pinning | 3 |
+| D | D3 risk mapping | 2 |
+| D | D4 health/lifecycle | 4 |
+| **Total** | | **~36 new tests** |
+
+**预计: 308 → ~344 tests。** 现有 308 必须保持 green。
+
+## Scope 边界
+
+### IN scope (v0.5.0)
+- Tool schema strict validation（内置 + 可选 jsonschema）
+- Tool metadata strict/lenient enforcement
+- TimeoutPolicy + RetryPolicy 接入 tool 执行路径
+- Idempotency key deduplication
+- Per-tool, session-scoped rate limiting
+- RiskLevel → DecisionEffect default policy
+- MCP server allowlist
+- MCP tool schema pinning + drift detection
+- MCP tool risk auto-mapping
+- MCP health check + lifecycle（connect/disconnect/reconnect）
+
+### OUT of scope (deferred to v0.6+)
+- ❌ MCP server mode（`serve_as_mcp` 保持 stub）
+- ❌ Sandbox execution（subprocess/container isolation）
+- ❌ Per-tenant / per-user rate limiting
+- ❌ Tool rollback / compensation
+- ❌ MCP transport security（TLS, auth tokens）
+- ❌ Prompt injection defense for MCP tool descriptions
+- ❌ Policy hot-reload
+- ❌ Multi-tenant policy namespaces
+
+## 风险评估
+
+| Phase | 风险 | 缓解 |
+|---|---|---|
+| A1 | 内置 validator 与 jsonschema 边缘差异 | 提供 jsonschema extra；文档覆盖范围；两条路径集成测试 |
+| B1 | `with_timeout` 用 ThreadPoolExecutor，无法中断 CPU-bound 工具 | 文档限制；async 路径用 asyncio.wait_for（真正取消） |
+| B2 | 重试非幂等工具导致副作用重复 | **硬门控**: 仅 `tool.idempotent == True` 时重试。显式测试。 |
+| C1 | 滑动窗口在分布式环境有时钟偏移 | v0.5 单进程；文档限制 |
+| D2 | Schema drift 因无害 description 变化误报 | 仅 pin `input_schema`（结构），不含 description |
+| D4 | Windows 上 subprocess zombie | `atexit` + context manager；跨平台测试 |

{petfishframework-0.4.2 → petfishframework-0.5.0}/CHANGELOG.md

@@ -2,6 +2,77 @@
 
 All notable changes to petfishFramework will be documented in this file.
 
+## [0.5.0] — 2026-07-08
+
+### Tool / MCP Governance
+
+#### Phase A: Tool Schema & Metadata
+- **ToolSchemaValidator** — JSON schema validation on tool args before execution. Built-in validator covers type/required/properties/enum/additionalProperties. Optional `jsonschema` extra for full draft-2020 compliance. Wired into `RuntimeEnvironment.call()` after PARTIAL_ALLOW filter.
+- **ToolMetadataPolicy** — strict/lenient enforcement of tool metadata fields (risk_level, side_effect, idempotent, etc.). Validation at RuntimeEnvironment construction time. Default lenient (backward compatible).
+
+#### Phase B: Execution Hardening
+- **TimeoutPolicy wiring** — `with_timeout` wraps `tool.execute()` in `call()`. Timeout caught internally, returns `ToolResult(error="timeout")`, never raises to caller. Async path uses `asyncio.wait_for`.
+- **RetryPolicy wiring** — `with_retry` wraps idempotent tool execution. **Hard gate: only retries when `tool.idempotent == True`** (non-idempotent tools never retried — prevents duplicate side effects).
+- **IdempotencyStore** — session-scoped dedup via `_idempotency_key` in args. TTL-based cache. Cache hit returns early without executing tool.
+
+#### Phase C: Rate Limiting & Risk Classification
+- **RateLimiter** — per-tool, session-scoped sliding-window rate limiting. `RateLimitPolicy(max_calls, window_s)` configurable per-tool via `BaseTool.rate_limit` or env-level. Over-limit → `ToolResult(error="rate_limited")`.
+- **RiskClassificationPolicy** — maps `RiskLevel` → default `DecisionEffect` (CRITICAL/HIGH → REQUIRE_APPROVAL, MEDIUM/LOW → ALLOW). Opt-in via `permission_policy=`. **CompositePolicy** combines multiple policies with deny-overrides semantics.
+
+#### Phase D: MCP Client Governance
+- **MCPAllowlist** — governs which MCP servers can connect. Strict mode rejects unlisted servers before subprocess spawn. Lenient default (backward compatible).
+- **SchemaPin** — freezes discovered MCP tool `input_schema` hashes for drift detection. Description-only changes do NOT trigger drift (structural pinning only). `MCPClient.pin_schemas()` + `verify_schemas()`.
+- **MCPRiskMapper** — auto-classifies MCP tools by capability → RiskLevel (write/exec/network → HIGH, read → LOW). Applied during `discover_tools()`.
+- **Health check + lifecycle** — `MCPClient.health()`, `close()`, `reconnect()`, context manager (`__enter__`/`__exit__`). No zombie subprocesses.
+
+#### New BaseTool Fields (all optional, backward compatible)
+- `rate_limit: RateLimitPolicy | None = None`
+- `retry_policy: RetryPolicy | None = None`
+- `supports_idempotency_key: bool = False`
+
+#### New RuntimeEnvironment Fields (all optional, None = no-op)
+- `timeout_policy: TimeoutPolicy | None = None`
+- `rate_limiter: RateLimiter | None = None`
+- `idempotency_store: IdempotencyStore | None = None`
+- `schema_validator: ToolSchemaValidator | None = None`
+
+#### Test Growth
+- v0.4.5: 308 tests → v0.5.0: 352 tests (+44)
+- All existing tests unmodified (backward compatible)
+
+#### Deferred to v0.6+
+- ❌ MCP server mode (`serve_as_mcp`)
+- ❌ Sandbox execution (subprocess/container isolation)
+- ❌ Per-tenant rate limiting
+- ❌ Policy hot-reload
+
+## [0.4.5] — 2026-07-08
+
+### v0.5 Readiness: API Documentation + Technical Debt Cleanup
+
+#### API Reference Overhaul (28 APIs documented)
+- `docs/api.md` expanded from 1471 to 2203 lines (+50%)
+- All 28 previously-undocumented public APIs now have full signatures, parameters, and examples:
+  - **Observability**: OTelSink, SIEMSink (with redact_keys boundary note)
+  - **Reliability**: RetryPolicy, with_retry, with_retry_async, RetryableError, RetryModelAdapter, retry_model_adapter, TimeoutPolicy, with_timeout, OperationTimedOut, RerunEnvironment, RerunResult, CostReport
+  - **Configuration**: FrameworkConfig (from_env, from_dict)
+  - **Conversation Memory**: ConversationStore, InMemoryConversationStore
+  - **Structured Output**: StructuredResult, parse_json, parse_structured
+  - **Tools**: AgentAsTool, WordSorter
+  - **Models**: AnthropicModel, AsyncFakeModel
+  - **Policies**: PolicyRule, load_policy
+  - **MCP**: serve_as_mcp (marked as v0.5 stub)
+
+#### API Stability Policy
+- New `docs/api-stability.md` classifies all public APIs into Stable / Experimental / Internal tiers
+- Documents deprecation process and v1.0 freeze criteria
+
+#### Code Cleanup (stale markers removed)
+- `permissions/__init__.py`: docstring updated — CredentialBroker is implemented, not TODO
+- `permissions/model.py`: DefaultAllowPolicy comment clarified (allow-all by design, not a skeleton TODO)
+- `core/environment.py`: DEGRADE docstring fixed — tool switching IS implemented (was incorrectly marked "future work"); visibility gate clarified as v0.5 planned
+- `docs/skeleton-completeness-checklist.md`: comprehensively updated to reflect v0.4.5 state (RESUME/RERUN, Pass^k, CredentialBroker, OTel/SIEM, retry/timeout all marked ✅)
+
 ## [0.4.2] — 2026-07-08
 
 ### CI & Deployment Hardening

{petfishframework-0.4.2 → petfishframework-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: petfishframework
-Version: 0.4.2
+Version: 0.5.0
 Summary: A lightweight runtime framework for reliable, auditable, budget-aware, and permission-aware AI agents.
 Project-URL: Homepage, https://github.com/kylecui/petfishFramework
 Project-URL: Documentation, https://github.com/kylecui/petfishFramework/tree/master/docs
@@ -39,7 +39,7 @@ Description-Content-Type: text/markdown
 
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kylecui/petfishFramework/blob/master/LICENSE)
-[![Tests: 305](https://img.shields.io/badge/tests-305-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
+[![Tests: 352](https://img.shields.io/badge/tests-352-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
 
 **Status: Alpha** — API may change. Core runtime works; see [Roadmap](#roadmap).
 
@@ -275,7 +275,7 @@ result = session.run()
 
 - **v0.2.x**: Core runtime, permission semantics, enterprise PoC, Trusted Publishing ✅
 - **v0.3.x**: YAML Policy Engine, CredentialBroker ✅
-- **v0.4.x** (current): Production hardening, deployment guides, Vault adapter, Docker, threat model ✅
+- **v0.5.x** (current): Tool/MCP governance — schema validation, rate limiting, risk classification, retry/timeout wiring, MCP allowlist/schema-pin/risk-map/lifecycledes, Vault adapter, Docker, threat model ✅
 
 ## Current Limitations
 
@@ -306,7 +306,7 @@ petfishFramework is **Alpha**. API may change before v1.0.
 git clone https://github.com/kylecui/petfishFramework.git
 cd petfishFramework
 uv sync --all-extras
-uv run pytest              # 305 tests
+uv run pytest              # 352 tests
 uv run ruff check src/ tests/
 ```
 

{petfishframework-0.4.2 → petfishframework-0.5.0}/README.md

@@ -4,7 +4,7 @@
 
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kylecui/petfishFramework/blob/master/LICENSE)
-[![Tests: 305](https://img.shields.io/badge/tests-305-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
+[![Tests: 352](https://img.shields.io/badge/tests-352-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
 
 **Status: Alpha** — API may change. Core runtime works; see [Roadmap](#roadmap).
 
@@ -240,7 +240,7 @@ result = session.run()
 
 - **v0.2.x**: Core runtime, permission semantics, enterprise PoC, Trusted Publishing ✅
 - **v0.3.x**: YAML Policy Engine, CredentialBroker ✅
-- **v0.4.x** (current): Production hardening, deployment guides, Vault adapter, Docker, threat model ✅
+- **v0.5.x** (current): Tool/MCP governance — schema validation, rate limiting, risk classification, retry/timeout wiring, MCP allowlist/schema-pin/risk-map/lifecycledes, Vault adapter, Docker, threat model ✅
 
 ## Current Limitations
 
@@ -271,7 +271,7 @@ petfishFramework is **Alpha**. API may change before v1.0.
 git clone https://github.com/kylecui/petfishFramework.git
 cd petfishFramework
 uv sync --all-extras
-uv run pytest              # 305 tests
+uv run pytest              # 352 tests
 uv run ruff check src/ tests/
 ```
 

petfishframework-0.5.0/docs/api-stability.md

@@ -0,0 +1,88 @@
+# API Stability Policy
+
+> Effective: v0.4.5
+> Goal: Help users understand which APIs are safe to depend on before v1.0.
+
+## Stability Tiers
+
+| Tier | Meaning | Breaking changes | Versioning |
+|---|---|---|---|
+| **Stable** | API signature and semantics will not change before v1.0 without a deprecation cycle (min 1 minor version). | Only for security fixes. | Patch (0.4.x) |
+| **Experimental** | API exists and works, but may change signature or semantics in the next minor version. | Allowed with CHANGELOG note. | Minor (0.x.0) |
+| **Internal** | Used by the framework internally. May change or be removed without notice. | No guarantees. | Any |
+
+## Classification
+
+### Stable
+
+These APIs have been validated by 300+ tests and are used in production-facing examples:
+
+- `Agent`, `Session` — core execution abstractions
+- `Budget`, `BudgetExceeded` — budget enforcement
+- `DecisionEffect` (all 6 values) — permission semantics
+- `Subject`, `Action`, `Resource`, `AccessContext`, `Decision` — SARC model
+- `PermissionPolicy` protocol — policy interface
+- `DefaultAllowPolicy`, `DenyByDefaultPolicy` — built-in policies
+- `Event`, `EventEmitter` — event infrastructure
+- `Result`, `Task`, `Step`, `Trajectory`, `Usage` — core types
+- `Tool` protocol, `BaseTool`, `@tool` decorator
+- `Calculator`, `WordSorter` — reference tools
+- `FakeModel` — testing model
+- `ReAct` — default reasoning strategy
+- `RuntimeEnvironment` — the chokepoint
+- `AuditReport`, `audit_report_from_session` — audit output
+- `CredentialBroker`, `ScopedToken` — credential governance
+- `YamlPolicy`, `PolicyRule` — YAML policy engine
+- `pass_at_k`, `pass_at_k_with_perturbations` — reliability metric
+
+### Experimental
+
+These APIs work and are tested, but their signatures or semantics may change:
+
+- `OTelSink`, `SIEMSink` — observability sinks (redaction API may evolve)
+- `RecordingEnvironment`, `ReplayEnvironment`, `RerunEnvironment`, `ResumableEnvironment` — replay wrappers
+- `RerunResult` — divergence detection output format may change
+- `RetryPolicy`, `with_retry`, `RetryModelAdapter` — retry infrastructure
+- `TimeoutPolicy`, `with_timeout` — timeout infrastructure
+- `VaultCredentialSource` — Vault adapter (needs real-world validation)
+- `OpenAIModel`, `AnthropicModel` — model adapters (provider API changes)
+- `LATS`, `LLMPlusP` — reasoning strategies (lightweight implementations)
+- `CRAGRetriever`, `AdaptiveRetriever`, `MemoryRetriever` — retrieval (lightweight)
+- `AgentAsTool` — multi-agent delegation
+- `ConversationStore`, `InMemoryConversationStore` — conversation memory
+- `StructuredResult`, `parse_json`, `parse_structured` — structured output
+- `FrameworkConfig` — configuration system
+- `CostReport` — cost reporting format
+- `connect_stdio`, `MCPClient` — MCP client
+- Policy condition matchers — YAML matcher set may expand/change
+- `SIEMSink.redact_keys` — redaction key set may change defaults
+
+### Internal
+
+These are implementation details that should not be directly imported:
+
+- `CostAccountant` — internal cost tracking (use `Result.usage` instead)
+- `CapabilityProjection` — visibility gate (not yet enforced)
+- `CapabilityGrant` — audit artifact type (not yet emitted)
+- `CompiledContext`, `TaskSpec`, `MemorySlice`, `EvidenceBundle`, `OutputContract` — compiled context types
+- `MemoryView` — memory protocol (empty stub)
+- `serve_as_mcp` — MCP server stub (raises NotImplementedError)
+- `pass_at_k` perturbation functions (`canonical`, `order_shuffled`, etc.) — stable interface but internal implementations
+
+## Deprecation Process
+
+When an API moves from Stable to deprecated:
+
+1. Add `DeprecationWarning` in the next minor version
+2. Document replacement in CHANGELOG
+3. Keep the API functional for at least 1 minor version
+4. Remove in the following minor version (or v1.0 if major)
+
+## v1.0 Freeze Criteria
+
+Before declaring v1.0:
+
+- All Stable APIs have been unchanged for 2+ minor versions
+- All Experimental APIs are reclassified as Stable or explicitly dropped
+- Breaking changes require semver-major version bump
+- Migration guide published for any dropped APIs