docs: record external Core adoption evidence

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

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.
 

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.

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