From 867780f728d30abd28243d541f63b2b725a45eda Mon Sep 17 00:00:00 2001 From: Deathcharge Date: Tue, 11 Aug 2026 01:00:57 -0400 Subject: [PATCH 1/2] docs: record circuit breaker adoption --- README.md | 6 ++++- ROADMAP.md | 13 +++++++---- docs/ADOPTION.md | 53 +++++++++++++++++++++++++----------------- docs/PRODUCTIZATION.md | 15 ++++++------ 4 files changed, 54 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index d84d7a7..aae4815 100644 --- a/README.md +++ b/README.md @@ -138,7 +138,7 @@ progress and logging, bounded task retention, admission limits, and security bou ## Proven external consumer [Samsarix Integration Examples](https://github.com/Deathcharge/samsarix-integration-examples) -version 0.2.11 pins Core commit `6492495a426b1ae9856bf27f331d7cfec67006e6` +version 0.2.12 pins Core commit `2744d69eb58aef8412d15fbee9485b6d22eb30a5` and uses only the public API to expose a privacy-first, resumable redaction workflow over MCP. Its consumer-owned tests exercise initialization, discovery, stdio invocation, @@ -164,6 +164,10 @@ The same adapter can opt into a Core token bucket for that exact registration. I consumer-owned test proves one policy-gated redaction succeeds, an immediate second call returns a safe retryable `rate_limited` result, no second artifact is created, and the content-free success and rate-limit metrics each increment exactly once. +The adapter independently accepts a host-owned circuit breaker. Its consumer-owned +test injects one private downstream failure, proves the next call fails fast without +tool execution, artifact creation, or private protocol content, then completes one +real half-open recovery redaction and closes the circuit with exact aggregate metrics. The preceding v0.2.6 contract was also discovered and invoked through official MCP Inspector 0.21.2; a portable VS Code workspace is configuration-discovered, with signed-in trust and tool approval still awaiting operator acceptance. diff --git a/ROADMAP.md b/ROADMAP.md index 4e98a64..4770e80 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -43,8 +43,8 @@ remain separate decisions. - Strict `TypedDict` input and output contracts now preserve named nested fields, descriptions, and required/optional key semantics in JSON Schema and runtime validation. -- External consumer: `samsarix-integration-examples` version 0.2.11 pins Core - commit `6492495a426b1ae9856bf27f331d7cfec67006e6` and proves a confined, +- External consumer: `samsarix-integration-examples` version 0.2.12 pins Core + commit `2744d69eb58aef8412d15fbee9485b6d22eb30a5` and proves a confined, privacy-first redaction workflow, exact typed result discovery, and response-free asynchronous cancellation through the public MCP API. It also proves progress-token correlation, monotonic content-free updates, notification @@ -64,6 +64,9 @@ remain separate decisions. It now also proves a policy-gated real redaction succeeds under an opt-in per-tool token bucket while an immediate second call is safely rate limited without execution, a second artifact, private-input retention, or incorrect aggregate metrics. + It now also proves that a host-owned per-tool circuit opens after a private downstream + failure, rejects the next request without execution or an artifact, and closes after + one successful real redaction recovery probe without leaking private protocol content. - Next: complete the signed-in Visual Studio Code trust/tool-approval journey and rerun the consumer matrix after GitHub Actions billing is restored. Use observed demand and confirmed contract gaps—not framework parity—to prioritize broader @@ -88,8 +91,10 @@ remain separate decisions. evidence. - [x] Publish immutable GitHub prerelease `v2.0.0a6` with per-tool rate limiting, independent consumer, clean-install, checksum, and SLSA provenance evidence. -- [ ] Prove independent consumer adoption and publish an immutable prerelease for the - per-tool circuit-breaker contract after exact-head review and clean-wheel evidence. +- [x] Prove independent consumer adoption for the per-tool circuit-breaker contract + after exact-head review and clean-wheel evidence. +- [ ] Publish immutable GitHub prerelease `v2.0.0a7` with per-tool circuit breaking, + independent consumer, clean-install, checksum, and SLSA provenance evidence. ## Samsarix adoption diff --git a/docs/ADOPTION.md b/docs/ADOPTION.md index 2e99e7f..7a46b54 100644 --- a/docs/ADOPTION.md +++ b/docs/ADOPTION.md @@ -7,9 +7,9 @@ volume, or service-level commitment. The latest published `2.0.0a6` prerelease has independently verified artifacts and installed-wheel rate-limit recovery behavior. The repository consumer below pins the -merged per-tool rate-limit commit immediately before the release metadata commits, so -its exact Git installation reports package metadata `2.0.0a5`. Release verification is -tracked separately and is not presented as consumer-adoption evidence. +merged per-tool circuit-breaker commit, so its exact Git installation reports package +metadata `2.0.0a6`. Release verification is tracked separately and is not presented as +consumer-adoption evidence. ## Privacy-first redaction MCP consumer @@ -18,11 +18,11 @@ Repository: | Evidence | Value | | --- | --- | -| Core contract commit | `6492495a426b1ae9856bf27f331d7cfec67006e6` | -| Core package metadata at pinned commit | `2.0.0a5` | -| Consumer merge commit | `a446c4a80295928e6161627a8c03cc2bca4a8f27` | -| Consumer pull request | [samsarix-integration-examples#14](https://github.com/Deathcharge/samsarix-integration-examples/pull/14) | -| Consumer package version | `0.2.11` | +| Core contract commit | `2744d69eb58aef8412d15fbee9485b6d22eb30a5` | +| Core package metadata at pinned commit | `2.0.0a6` | +| Consumer merge commit | `be56db8476454d6f241a5da7d5e846d92d1bcefb` | +| Consumer pull request | [samsarix-integration-examples#15](https://github.com/Deathcharge/samsarix-integration-examples/pull/15) | +| Consumer package version | `0.2.12` | | Integration Guard provenance | [`samsarix-integration-guard`](https://github.com/Deathcharge/samsarix-integration-guard) `0.2.0` at `1aa711d89eaedcc396f0cd6eb416fb4253da3f5e` | | Orchestration provenance | [`samsarix-agent-orchestration`](https://github.com/Deathcharge/samsarix-agent-orchestration) `0.1.0` at `0dfc050cf9a4582c9fa8d34d74b1ca97d43c9005` | | Declared consumer Python | 3.11-3.13 | @@ -71,6 +71,16 @@ and serialized results contain neither seeded private values nor the workspace p This proves one process-local tool quota boundary, not distributed coordination, per-tenant accounting, authorization, or a service-level quota. +The factory independently accepts an optional host-owned `ToolCircuitBreaker` for the +same exact registration. A consumer-owned test injects one private downstream failure, +observes safe `tool_failed` protocol output, and verifies the immediate next call returns +status `circuit_open` without pipeline execution or artifact creation. After the recovery +interval, one half-open probe completes a real redaction and closes the circuit. Exact +metrics report one failure, one trip, one open rejection, and one success. Seeded source +values, filenames, run identifiers, failure text, and workspace paths are absent from the +failed and blocked results. This proves process-local dependency protection, not retries, +cross-process coordination, per-tenant isolation, or durable health state. + The consumer adapter now installs a fail-closed host policy through Core's public `ToolPolicyContext` and `ToolPolicyDecision` API. It admits only the exact redaction name, version, tags, task mode, safety annotations, and default-filled argument set. @@ -120,10 +130,10 @@ was signed out of Copilot, so no trust prompt or VS Code tool call was accepted. desktop configuration-discovery evidence, not a completed desktop-agent journey. The consumer's merged -[`pyproject.toml`](https://github.com/Deathcharge/samsarix-integration-examples/blob/a446c4a80295928e6161627a8c03cc2bca4a8f27/pyproject.toml) +[`pyproject.toml`](https://github.com/Deathcharge/samsarix-integration-examples/blob/be56db8476454d6f241a5da7d5e846d92d1bcefb/pyproject.toml) is the dependency manifest. It declares -`samsarix-core @ git+https://github.com/Deathcharge/samsarix-core.git@6492495a426b1ae9856bf27f331d7cfec67006e6`; -the installed public package reports Core version `2.0.0a5`. The same manifest +`samsarix-core @ git+https://github.com/Deathcharge/samsarix-core.git@2744d69eb58aef8412d15fbee9485b6d22eb30a5`; +the installed public package reports Core version `2.0.0a6`. The same manifest records the Guard and Orchestration commits above, and the compatibility test asserts all three installed package versions. @@ -135,7 +145,7 @@ environment with Python 3.11.9: ```text python -m ruff check . -> passed python -m mypy -> passed, strict mode -python -m pytest -> 37 passed, 91.64% branch coverage +python -m pytest -> 38 passed, 91.64% branch coverage python -m bandit -q -r src -> passed ``` @@ -147,12 +157,13 @@ python -m twine check -> wheel and sdist passed ``` A fresh virtual environment installed the consumer wheel with dependencies resolved -from their exact public Git commits. Import metadata resolved to consumer `0.2.11` and -Core `2.0.0a5`; the consumer import resolved from the environment's `site-packages`. +from their exact public Git commits. Import metadata resolved to consumer `0.2.12` and +Core `2.0.0a6`; the consumer import resolved from the environment's `site-packages`. Outside the source checkout, both installed CLIs passed their help journeys and the -focused installed-wheel contract proved one real redaction succeeds while an immediate -second call is safely rate limited with no second artifact. `pip check` reported no -broken requirements. Python 3.12 and 3.13 remain declared consumer support, but their +public factory exposed the optional circuit-breaker dependency control. The exact-pin +test suite separately proved one private failure, fail-fast rejection, and a successful +real recovery redaction. `pip check` reported no broken requirements. Python 3.12 and +3.13 remain declared consumer support, but their hosted jobs did not execute in this record because the account billing gate stopped the matrix before checkout. @@ -160,14 +171,14 @@ Final local artifacts were: | Artifact | Bytes | SHA-256 | | --- | ---: | --- | -| `samsarix_integration_examples-0.2.11-py3-none-any.whl` | 19,194 | `2a3f1b5be02b67eff2878e26e90471feddd931cf580f8f9e362e35ab3bfe1da8` | -| `samsarix_integration_examples-0.2.11.tar.gz` | 40,795 | `ed86462aa5c5bb2569554453709f2ceebe43581fcd9e0cf8a1eec0c78f138a46` | +| `samsarix_integration_examples-0.2.12-py3-none-any.whl` | 19,450 | `b72d61cc67132cdbb7df63be41fdd077a29e3fe9bbbc3673fa7a98c42c74608a` | +| `samsarix_integration_examples-0.2.12.tar.gz` | 42,116 | `8a32e0b79a6bcb4abb593af10562f8cc32d65931a6962edd4532e3cac370b1c4` | CodeRabbit attached a green high-level status, but its free-plan notice says the pass provides only a summary and walkthrough; it is not counted as independent line-level review evidence. The consumer's -[pull-request run](https://github.com/Deathcharge/samsarix-integration-examples/actions/runs/31447006222) -and [post-merge run](https://github.com/Deathcharge/samsarix-integration-examples/actions/runs/31448580817) +[pull-request run](https://github.com/Deathcharge/samsarix-integration-examples/actions/runs/31460008990) +and [post-merge run](https://github.com/Deathcharge/samsarix-integration-examples/actions/runs/31460072311) did not start their jobs: GitHub attached an account billing/spending-limit failure before checkout, leaving zero executed steps and no job logs. That infrastructure failure is not represented as hosted test diff --git a/docs/PRODUCTIZATION.md b/docs/PRODUCTIZATION.md index 6f64d16..53b8dc7 100644 --- a/docs/PRODUCTIZATION.md +++ b/docs/PRODUCTIZATION.md @@ -281,12 +281,13 @@ All baseline commands were run on Windows with Python 3.11.9 at commit asynchronous cancellation, bounded content-free progress, and client-filtered operational logging, retained sync-worker capacity after timeout, and bounded shutdown quiescence, official MCP Inspector invocation, and Visual Studio Code - configuration discovery from `samsarix-integration-examples`; version 0.2.11 at merge - commit `a446c4a80295928e6161627a8c03cc2bca4a8f27` pins Core commit - `6492495a426b1ae9856bf27f331d7cfec67006e6` and additionally proves the bounded + configuration discovery from `samsarix-integration-examples`; version 0.2.12 at merge + commit `be56db8476454d6f241a5da7d5e846d92d1bcefb` pins Core commit + `2744d69eb58aef8412d15fbee9485b6d22eb30a5` and additionally proves the bounded experimental task lifecycle, allow/deny invocation policy, fail-fast runtime admission, paired content-free lifecycle observation, and process-local per-tool - rate limiting on the real redaction adapter. + rate limiting and per-tool circuit failure, fail-fast rejection, and successful + half-open recovery on the real redaction adapter. ## Deferred work and rationale @@ -296,12 +297,12 @@ tasks retain bounded results only inside one server process and do not satisfy d persistence or restart recovery. Those features are not required for the first useful release. One independent repository now proves the stable MCP boundary, experimental task lifecycle, bounded policy gate, fail-fast runtime admission, and privacy-safe -lifecycle observation. Core now also supplies the process-local per-tool rate control -required by its supported MCP tool boundary. Subsequent surface +lifecycle observation. Core now also supplies the process-local per-tool rate and +circuit controls required by its supported MCP tool boundary. Subsequent surface area should follow concrete consumer demand. Core's per-tool rate-limit pull request [Python 3.10-3.14 hosted matrix](https://github.com/Deathcharge/samsarix-core/actions/runs/31241493059) is green. The consumer's separate Python 3.11-3.13 jobs could not start because GitHub -reported an account billing/spending-limit problem, so its local 37-test exact-pin and +reported an account billing/spending-limit problem, so its local 38-test exact-pin and clean-wheel behavioral evidence is recorded separately in `docs/ADOPTION.md`. ## Owner-, credential-, or production-blocked tasks From 30118b647894687b7a810db3cfed79ac152b9c3e Mon Sep 17 00:00:00 2001 From: Deathcharge Date: Tue, 11 Aug 2026 01:00:57 -0400 Subject: [PATCH 2/2] chore: prepare 2.0.0a7 prerelease --- CHANGELOG.md | 8 ++++++-- CITATION.cff | 4 ++-- pyproject.toml | 2 +- src/samsarix_core/_version.py | 2 +- 4 files changed, 10 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 12f279e..e767dc9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ ## Unreleased +## 2.0.0a7 - 2026-08-11 + ### Added - opt-in process-local per-tool consecutive-failure circuit breakers with safe @@ -11,8 +13,10 @@ ### Changed -- recorded immutable `v2.0.0a6` release checksums, provenance, and clean installed-wheel - rate-limit recovery evidence. +- recorded independent consumer `0.2.12` adoption evidence for the process-local + per-tool circuit-breaker contract. +- recorded immutable `v2.0.0a6` release checksums, provenance, and clean + installed-wheel rate-limit recovery evidence. ## 2.0.0a6 - 2026-08-10 diff --git a/CITATION.cff b/CITATION.cff index 526c443..6adae3b 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -4,8 +4,8 @@ title: "Samsarix Core" type: software authors: - name: "Samsarix LLC" -version: "2.0.0a6" -date-released: "2026-08-10" +version: "2.0.0a7" +date-released: "2026-08-11" repository-code: "https://github.com/Deathcharge/samsarix-core" url: "https://samsarix.com" license: "MPL-2.0" diff --git a/pyproject.toml b/pyproject.toml index dccd804..7c63fb5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "samsarix-core" -version = "2.0.0a6" +version = "2.0.0a7" description = "A small, dependency-free runtime for typed local Python tools" readme = "README.md" requires-python = ">=3.10" diff --git a/src/samsarix_core/_version.py b/src/samsarix_core/_version.py index d6d24f1..fecec5e 100644 --- a/src/samsarix_core/_version.py +++ b/src/samsarix_core/_version.py @@ -3,4 +3,4 @@ """Single source of truth for the distribution version.""" -__version__ = "2.0.0a6" +__version__ = "2.0.0a7"