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..5143dc5 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,12 @@ 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. 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. @@ -32,13 +39,18 @@ 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, + 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. - 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..d6a0c53 --- /dev/null +++ b/docs/ADOPTION.md @@ -0,0 +1,94 @@ +# 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` | +| 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 | + +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. + +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: + +```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..f40f532 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,25 @@ 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](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