From fcd57da8cd660e2bf2eafaad2e1219ed48336eff Mon Sep 17 00:00:00 2001 From: Deathcharge Date: Sat, 1 Aug 2026 19:52:31 -0400 Subject: [PATCH 1/2] docs: record external Core adoption evidence --- README.md | 15 +++++++- ROADMAP.md | 19 +++++++--- docs/ADOPTION.md | 83 ++++++++++++++++++++++++++++++++++++++++++ docs/PRODUCTIZATION.md | 24 ++++++++---- 4 files changed, 128 insertions(+), 13 deletions(-) create mode 100644 docs/ADOPTION.md diff --git a/README.md b/README.md index a6fd268..755ceb3 100644 --- a/README.md +++ b/README.md @@ -95,6 +95,19 @@ decorated tools. See the [MCP bridge guide](docs/MCP.md) for lifecycle support, read/write/destructive annotations, scalar-output wrapping, stdio requirements, and security boundaries. +## Proven external consumer + +[Samsarix Integration Examples](https://github.com/Deathcharge/samsarix-integration-examples) +pins Core commit `6f54bcdf428359f1eee654944b6abc8788575eab` 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, +structured results, privacy boundaries, path traversal and linked-file refusal, +artifact conflict handling, package installation, and CLI entry points. + +This is compatibility evidence, not a claim of third-party production adoption. +See the [adoption record](docs/ADOPTION.md) for exact commits, commands, artifact +digests, limitations, and rollback. + The distribution name is `samsarix-core`. The former `helix_core` import, `helix_tool` decorator, and `HelixError` base class remain compatibility aliases for existing prototypes; new code should use the Samsarix names above. @@ -147,7 +160,7 @@ them to the host's actual workload. See [Getting started](docs/GETTING_STARTED.md), the [API reference](docs/API_REFERENCE.md), [architecture](docs/ARCHITECTURE.md), [MCP bridge](docs/MCP.md), [best practices](docs/BEST_PRACTICES.md), [benchmark guide](docs/BENCHMARKS.md), -and the [productization +the [adoption record](docs/ADOPTION.md), and the [productization record](docs/PRODUCTIZATION.md). ## Quality status diff --git a/ROADMAP.md b/ROADMAP.md index 09127a0..7169521 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -6,7 +6,10 @@ This roadmap separates four gates: merge, release, publication, and flagship ado Portfolio role: **reusable library or sdk**. Keep this as a small, independently versioned package. Samsarix Unified should consume it only through a public API adapter; private monorepo imports and copied implementations are out of scope. -Current disposition: Merge the productization branch after exact-head verification and rollback-ref creation; release and adoption remain separate decisions. +Current disposition: The productized runtime, MCP bridge, resource bounds, and +sync-quiescence work are merged. An independent repository now provides exact-pin +compatibility evidence; release, publication, and third-party production adoption +remain separate decisions. ## Stabilize the productized default @@ -21,8 +24,11 @@ Current disposition: Merge the productization branch after exact-head verificati by adversarial tests. - Timed-out sync work now retains its real concurrency slot and in-flight gauge; callers can inspect, wait for, and require bounded shutdown quiescence. -- Next: prove adoption from one external consumer, then prioritize richer nested - schema types from that integration evidence. +- External consumer: `samsarix-integration-examples` version 0.2.0 pins Core + commit `6f54bcdf428359f1eee654944b6abc8788575eab` and proves a confined, + privacy-first redaction workflow through the public MCP API. +- Next: rerun the consumer matrix after GitHub Actions billing is restored, then + use its contract evidence to prioritize richer nested schema types. - Review priority: Capture all 101 dirty/untracked paths. - Review priority: split legacy relocation. - Review priority: resolve license identity. @@ -32,13 +38,16 @@ Current disposition: Merge the productization branch after exact-head verificati ## Release candidate - Build and install the wheel in a clean environment. -- Prove one real consumer and a versioned compatibility fixture. +- [x] Prove one real repository consumer and a versioned compatibility fixture. - Publish only after package-name ownership, licensing, provenance, and rollback are recorded. ## Samsarix adoption - Define a public API, event, schema, artifact, or deployment contract before connecting to Samsarix Unified. -- Add a consumer-owned contract fixture covering authentication, privacy, limits, errors, and version compatibility. +- [x] Add a consumer-owned local-process contract fixture covering privacy, + limits, safe errors, filesystem confinement, and version compatibility. +- Add authentication evidence only when an authenticated network transport is in + scope; the supported stdio bridge delegates trust to the process launcher. - Make one implementation canonical; remove or freeze duplicate behavior only after parity and rollback are proven. - Record an owner, support level, compatibility window, and measurable adoption signal. diff --git a/docs/ADOPTION.md b/docs/ADOPTION.md new file mode 100644 index 0000000..f8dc0b5 --- /dev/null +++ b/docs/ADOPTION.md @@ -0,0 +1,83 @@ +# Adoption evidence + +This record separates package compatibility evidence from production-adoption +claims. Samsarix Core has a merged independent repository consumer; it does not +yet have a documented third-party production deployment, paid customer, usage +volume, or service-level commitment. + +## Privacy-first redaction MCP consumer + +Repository: +[Deathcharge/samsarix-integration-examples](https://github.com/Deathcharge/samsarix-integration-examples) + +| Evidence | Value | +| --- | --- | +| Core contract commit | `6f54bcdf428359f1eee654944b6abc8788575eab` | +| Consumer merge commit | `7bd7fe4bf75de2c88db723be67e17f9ca7f5fc87` | +| Consumer pull request | [samsarix-integration-examples#3](https://github.com/Deathcharge/samsarix-integration-examples/pull/3) | +| Consumer package version | `0.2.0` | +| Supported consumer Python | 3.11-3.13 | +| Compatibility owner | Samsarix LLC | +| Support level | Best effort; no SLA | + +The consumer composes three independently packaged projects through public APIs: +Core provides the bounded MCP runtime, Integration Guard redacts sensitive JSON, +and Orchestration provides checkpointed recovery and idempotency. A client may +name one JSON file in a configured inbox and one artifact filename. It cannot +supply an absolute path or path separator, linked files are rejected, conflicting +artifacts are not replaced, and successful MCP results contain metadata rather +than document content or local paths. + +## Verified contract + +The consumer suite completed locally on Windows with Python 3.11.9: + +```text +python -m ruff check . -> passed +python -m mypy -> passed, strict mode +python -m pytest -q -> 28 passed, 90.91% branch coverage +python -m bandit -q -r src -> passed +python -m build --no-isolation +python -m twine check dist/* -> wheel and sdist passed +``` + +A fresh virtual environment installed the consumer wheel with dependencies +provided from their exact local commit worktrees. Import metadata resolved to +`0.2.0`, and both `samsarix-redaction-mcp --help` and +`samsarix-redaction-pipeline --help` completed successfully. + +Final local artifacts were: + +| Artifact | Bytes | SHA-256 | +| --- | ---: | --- | +| `samsarix_integration_examples-0.2.0-py3-none-any.whl` | 16,807 | `c8d36157a3f6eb28f812c7846926954d6f4ac937df047934bdbfd5f7335fce20` | +| `samsarix_integration_examples-0.2.0.tar.gz` | 25,729 | `39dd40955165b4e8632e6a9f2ca1d39e0df44e917769b277d7a07e13cca8be5a` | + +The consumer's GitHub Actions jobs did not start: 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 +evidence. The workflow should be rerun after the account's Billing & plans issue +is resolved. + +## Compatibility and rollback + +The consumer uses an exact Git commit dependency rather than a moving branch. +Updating Core requires a consumer pull request that reruns the same privacy, +filesystem, protocol, packaging, and version checks. Until Core declares a stable +release line, compatibility is commit-specific. + +Rollback is consumer-owned: stop the local MCP process, remove its client +registration, and revert the consumer dependency and adapter commit. Core itself +stores no remote state. After any required evidence retention, the operator may +remove the consumer workspace's generated artifacts and sanitized checkpoints. + +## Next adoption signals + +- Rerun the consumer Python 3.11-3.13 matrix after GitHub Actions billing is + restored. +- Exercise timeout and bounded quiescence through a consumer-owned deliberately + slow tool. +- Record an independently operated deployment or downstream repository before + claiming production adoption. +- Use consumer demand, not framework parity, to decide whether richer dataclass, + `TypedDict`, enum, or constrained-value schemas belong in Core. diff --git a/docs/PRODUCTIZATION.md b/docs/PRODUCTIZATION.md index d1251db..900293f 100644 --- a/docs/PRODUCTIZATION.md +++ b/docs/PRODUCTIZATION.md @@ -170,8 +170,10 @@ All baseline commands were run on Windows with Python 3.11.9 at commit ### P2 -- [ ] Add optional adapters for OpenAI-compatible, Anthropic, MCP, or agent-framework - tool schemas only after the core contract stabilizes. +- [x] Add a dependency-free MCP adapter after stabilizing the core tool contract; + prove it from an exact-pinned independent repository consumer. +- [ ] Add optional OpenAI-compatible, Anthropic, or agent-framework adapters only + after consumer demand establishes a concrete contract. - [ ] Add opt-in persistence for registry metadata and invocation summaries. - [ ] Add process isolation for untrusted tools as a separate package or explicit execution backend. @@ -231,15 +233,23 @@ All baseline commands were run on Windows with Python 3.11.9 at commit isolated wheel installation. - Completed the repository threat model and closed five conservative security candidates with no reportable or deferred finding in the final worktree. +- Added the stable MCP 2025-11-25 tool lifecycle, structured output, behavioral + annotations, and bounded local stdio transport without a runtime dependency. +- Added registry, batch, value-complexity, argument, and output resource budgets, + plus observable bounded shutdown quiescence for timed-out synchronous work. +- Proved the public MCP API from `samsarix-integration-examples` 0.2.0 at merge + commit `7bd7fe4bf75de2c88db723be67e17f9ca7f5fc87`; the consumer pins Core + commit `6f54bcdf428359f1eee654944b6abc8788575eab`. ## Deferred work and rationale P2 framework/provider adapters, registry persistence, process isolation, and richer -schema types are deliberately deferred. They are not required for the first useful -release and would add surface area before real adopter evidence establishes the -right contracts. Python-version CI is configured, but only Python 3.11 and an -additional Python 3.13 wheel smoke test were available locally; hosted matrix runs -will provide the remaining platform evidence. +schema types remain deliberately deferred. They are not required for the first useful +release. One independent repository now proves the MCP boundary without needing those +features; subsequent surface area should follow concrete consumer demand. Core's own +Python 3.10-3.14 hosted matrix is green. The consumer's Python 3.11-3.13 jobs could +not start because GitHub reported an account billing/spending-limit problem, so its +local 28-test and installed-wheel evidence is recorded separately in `docs/ADOPTION.md`. ## Owner-, credential-, or production-blocked tasks From 077aa4bfad72000eb89a1a23b49680665fbeaba1 Mon Sep 17 00:00:00 2001 From: Deathcharge Date: Sat, 1 Aug 2026 20:01:24 -0400 Subject: [PATCH 2/2] docs: tighten adoption provenance claims --- ROADMAP.md | 9 ++++++--- docs/ADOPTION.md | 11 +++++++++++ docs/PRODUCTIZATION.md | 8 +++++--- 3 files changed, 22 insertions(+), 6 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 7169521..5143dc5 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -27,8 +27,9 @@ remain separate decisions. - External consumer: `samsarix-integration-examples` version 0.2.0 pins Core commit `6f54bcdf428359f1eee654944b6abc8788575eab` and proves a confined, privacy-first redaction workflow through the public MCP API. -- Next: rerun the consumer matrix after GitHub Actions billing is restored, then - use its contract evidence to prioritize richer nested schema types. +- Next: rerun the consumer matrix after GitHub Actions billing is restored. Use + observed consumer demand and confirmed contract gaps—not framework parity—to + prioritize richer nested schema types. - Review priority: Capture all 101 dirty/untracked paths. - Review priority: split legacy relocation. - Review priority: resolve license identity. @@ -45,7 +46,9 @@ remain separate decisions. - Define a public API, event, schema, artifact, or deployment contract before connecting to Samsarix Unified. - [x] Add a consumer-owned local-process contract fixture covering privacy, - limits, safe errors, filesystem confinement, and version compatibility. + 1 MiB source ingestion, safe errors, filesystem confinement, and version + compatibility. Consumer-owned timeout and bounded-quiescence evidence remains + pending. - Add authentication evidence only when an authenticated network transport is in scope; the supported stdio bridge delegates trust to the process launcher. - Make one implementation canonical; remove or freeze duplicate behavior only after parity and rollback are proven. diff --git a/docs/ADOPTION.md b/docs/ADOPTION.md index f8dc0b5..d6a0c53 100644 --- a/docs/ADOPTION.md +++ b/docs/ADOPTION.md @@ -13,9 +13,12 @@ Repository: | Evidence | Value | | --- | --- | | Core contract commit | `6f54bcdf428359f1eee654944b6abc8788575eab` | +| Core package version | `2.0.0a1` | | Consumer merge commit | `7bd7fe4bf75de2c88db723be67e17f9ca7f5fc87` | | Consumer pull request | [samsarix-integration-examples#3](https://github.com/Deathcharge/samsarix-integration-examples/pull/3) | | Consumer package version | `0.2.0` | +| 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` | | Supported consumer Python | 3.11-3.13 | | Compatibility owner | Samsarix LLC | | Support level | Best effort; no SLA | @@ -28,6 +31,14 @@ supply an absolute path or path separator, linked files are rejected, conflictin artifacts are not replaced, and successful MCP results contain metadata rather than document content or local paths. +The consumer's merged +[`pyproject.toml`](https://github.com/Deathcharge/samsarix-integration-examples/blob/7bd7fe4bf75de2c88db723be67e17f9ca7f5fc87/pyproject.toml) +is the dependency manifest. It declares +`samsarix-core @ git+https://github.com/Deathcharge/samsarix-core.git@6f54bcdf428359f1eee654944b6abc8788575eab`; +the installed public package reports Core version `2.0.0a1`. The same manifest +records the Guard and Orchestration commits above, and the compatibility test +asserts all three installed package versions. + ## Verified contract The consumer suite completed locally on Windows with Python 3.11.9: diff --git a/docs/PRODUCTIZATION.md b/docs/PRODUCTIZATION.md index 900293f..f40f532 100644 --- a/docs/PRODUCTIZATION.md +++ b/docs/PRODUCTIZATION.md @@ -247,9 +247,11 @@ P2 framework/provider adapters, registry persistence, process isolation, and ric schema types remain deliberately deferred. They are not required for the first useful release. One independent repository now proves the MCP boundary without needing those features; subsequent surface area should follow concrete consumer demand. Core's own -Python 3.10-3.14 hosted matrix is green. The consumer's Python 3.11-3.13 jobs could -not start because GitHub reported an account billing/spending-limit problem, so its -local 28-test and installed-wheel evidence is recorded separately in `docs/ADOPTION.md`. +[Python 3.10-3.14 hosted matrix](https://github.com/Deathcharge/samsarix-core/actions/runs/30724220457) +is green; Core's local suite has 59 tests and 94.08% branch coverage. 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 28-test and installed-wheel evidence is +recorded separately in `docs/ADOPTION.md`. ## Owner-, credential-, or production-blocked tasks