Samsarix Core Productization Record

August 31, 2026 · View on GitHub

Last updated: 2026-08-31

Current repository assessment

Completion audit after the a11 release

On 2026-08-31, main 3ba07ecd56af0dd45c207a314f5f9019cdb3d0b7 was clean and matched origin. Its CI run passed all 18 jobs. The preceding release/evidence increment was progress, not completion of the production/adoption goal. This audit corrected stale latest-release references and qualified a11 against the unchanged consumer; no runtime change or additional release is warranted by those findings.

Completion requirement	Evidence and remaining boundary
Independent product, installation and package shape	Public, dependency-free typed local-tool runtime; a11 downloaded wheel/archive and compatibility imports verified outside the checkout. No private consumer is required.
Useful complete workflow	Public persistent SQLite MCP example proves default write denial, approved host policy, atomic reservation, restart replay, conflict handling and stock/ledger state; raw and official-client checks pass.
Reliability, security boundaries and quality	Recorded 434 Core tests, 95.44% branch-aware coverage, formatting/lint/types/build checks and 18-job CI. Trusted in-process tools, cooperative thread cancellation and plaintext application storage remain explicit limitations.
Verifiable distribution	Immutable a11 assets, exact-source build provenance and installed-wheel checks pass. This is GitHub evaluation distribution, not PyPI or a stable API commitment.
README journey in under five minutes, entirely offline	Not fully accepted. Offline execution after artifacts are acquired is verified; an unassisted new user's timing and the entire onboarding experience are not. Downloads and build-tool acquisition require network access. Do not count CI runtime as user onboarding time.
Current consumer adoption	Open. Fresh a11 candidate override: 37 passed, one unchanged old-version assertion failed, 91.03% installed-consumer branch coverage. Original manifest still pins Core metadata a6; no consumer upgrade or fresh hosted matrix was performed.
Desktop acceptance	Open. Automation failed before window inspection even after reset; no current sign-in/trust state was observed. Operator consent and an actual approved tool journey are still required.
Production suitability and demand	Unproven. No independently operated production deployment, user acceptance, stable API promise or SLA is established by these tests.

For the original five-minute acceptance criterion, have an unfamiliar evaluator follow the README without coaching and record prerequisites, start/end time, commands, output and any confusion. Report artifact acquisition separately from offline execution. If the complete criterion fails, retain that result and make an explicit product decision or repair onboarding; do not silently redefine it. The criterion below remains unchanged and unchecked by this audit.

The a11 qualification and exact consumer-session handoff record the artifact identities, commands, sole failure and owner-controlled next steps. Recorded consumer CI jobs never started because of an account annotation; the present account state has not been inferred from that historical failure. No private repository, billing setting, desktop permission or immutable asset was changed. Highest-value next work is the consumer repin/CI and operator acceptance, then stabilization driven by observed usage. More framework features do not close these evidence gaps. The full goal remains open.

Local verification for this documentation increment on Python 3.11.9:

python -m pytest -> 434 passed; 95.44% branch-aware coverage
python -m black --check src tests examples benchmarks scripts -> 40 unchanged
python -m ruff check src tests examples benchmarks scripts -> passed
python -m mypy -> passed, 28 source files
git diff --check -> passed

2.0.0a11 verified distribution

Release preparation PR #54 merged at d9ae73cf09e17a6ed3a6d2f092645dcac4743e22. Branch CI 33408725720, PR CI 33408728731, exact-main CI 33408961403 and tag CI 33409205272 each passed all 18 jobs. Preparation changed version metadata/changelog/evidence only; the merge and tested branch trees were identical. The local preparation record below is historical; all publication gates listed there have now passed.

New annotated tag, clean exact main, enabled immutability and successful publication.
Fresh wheel/source/manifest downloads: release signature, all asset memberships, exact names/counts, sizes, hashes and two-entry checksum manifest.
Both build attestations constrained to the exact tag, source commit, Release workflow and GitHub-hosted runners, without relaxed verification flags.
Downloaded archive's own offline checker and examples passed against the downloaded wheel, including persistent MCP stock/ledger assertions.
Downloaded archive's official-client checker passed SDK 1.29.1 legacy, 2.1.1 legacy and 2.1.1 modern modes with SQLite business/replay and cancellation checks.
Main-ref and tag-ref manual dispatches stayed build-only with privileged steps skipped.

Published wheel SHA-256: dc694e104dcd979db1515b607ef3ee7e2e05d6af39bb159703351f64493d653f. Exact assets, run identities, commands and initial missing-extracted-script launch failures are recorded in the release evidence. Those initial failed launches were not counted as passes; the confirmed extracted paths subsequently passed unchanged verification. No old assets or private code changed.

Disposition: published evaluation alpha with independently runnable source examples, not a production/stable claim. Highest-value remaining gates are consumer-owned upgrade/CI, actual desktop consent/invocation and evidence-led stabilization. No PyPI publication, paid infrastructure, telemetry, new runtime dependency or private repository change was made. The full production/adoption goal remains open.

2.0.0a11 release preparation

The previous acceptance increment PR #53 merged at 565f4632ebcaa093239750b8876f48c3a60f9ba0. Exact-main run 33407985374 passed all 18 jobs; its logs contain nine successful persistent SQLite SDK records covering all three client/protocol modes on Linux, Windows and macOS. That turn was verified progress, not completion of the production/adoption goal.

The remaining distribution gap is concrete: a10's immutable source archive predates the persistent MCP launcher and SDK-driven business acceptance checks. Prepare 2.0.0a11 to distribute that public workflow through a versioned source archive, keeping Core's API/dependencies unchanged and retaining the alpha designation. This is not a rationale for adding another feature or changing private consumers.

Align package, runtime and citation versions; close the matching changelog entry.
Verify source suite, isolated build, strict metadata and the offline gate.
Verify all three official-client modes against the new-version wheel.
Require complete exact-head CI before merge, then exact-main CI and a build-only Release dry run with privileged tag steps skipped.
Publish a new immutable prerelease; verify fresh asset downloads, exact hashes, membership and source-constrained provenance before updating installation claims.

At preparation time a10 remains the latest published version. No existing tag or asset will be moved or replaced. GitHub prerelease distribution does not imply PyPI publication, a stable API, desktop consent or third-party production adoption.

Local preparation passed 434 tests with 95.44% branch-aware coverage, Black (40 files), Ruff, strict mypy (28 files), Core-source Bandit and the diff check. The isolated source-to-wheel build, strict Twine and offline gate passed against local wheel 2532193c94f05a8b9507fa94a916793b286a404e872163d886a9db6689309834. This local artifact is not the eventual published asset; exact release evidence will be recorded only after download and verification.

Official-client acceptance for persistent reservations

The previous turn made concrete progress: PR #52 merged at c798523ac9b1129a03e433208885a5c910bfc065; the exact-main run 33406144596 passed all 18 jobs. This continuation rechecked the clean worktree, merge identity and live CI result rather than inferring completion from that milestone.

P1 acceptance gap: raw subprocess tests proved real reservations, but the official client gate only exercised the read-only example and a cancellation fixture. Those checks did not prove SDK parsing/schema validation and host policy around actual persistent writes. Decision: extend the existing client gate, not the Core runtime. The official SDK documentation and modern tool contract were rechecked on 2026-08-31; the existing pins/protocol scope stay unchanged.

Four fresh SDK-owned client/server sessions on a host-owned temporary database: default denial, enabled write, restart replay, then saved-replay denial without opt-in.
Validate catalog schemas, real-write annotations, structured/text agreement, missing inventory, conflicts, ledger capacity, invalid input and quiet logging.
Inspect exact stock and request/SKU ledger rows independently after every session.
Keep SDK models/transports separate from Core's encoder/parser and server install; preserve the parent deadline and independent server watchdog.
Add negative controls for missing writes, misleading hints, duplicate tools, path fields, incorrect error handling, bad text, extra ledger rows and init cleanup.
All three real SDK modes passed against the published a10 wheel with unchanged digest e84b26935ab9f73a7c632085ec9401256ffb8be0d107ce456a2e6604fec9d638.
Complete local source/build verification; require exact-head CI before merge and record commit/run identities in the pull request.

Local verification passed 434 tests with 95.44% Core branch-aware coverage (25 new checker regressions), Black on 40 files, Ruff, strict mypy on 28 files including Linux/Darwin platform checks, Bandit on Core source and git diff --check. An isolated source-to-wheel build, strict Twine and the offline real-process gate passed. The local wheel digest is 057284248d594a54f8b8ce12201054bbf163b33d8c6fa620541f7fe4ad432236; this is local verification evidence, not a replacement published artifact.

The earlier raw-pipe-only evidence below remains historical. This addition proves an SDK-driven business workflow, not desktop consent, external adoption, power-loss recovery or production readiness. No Core API, dependency, example behavior, workflow configuration, private repository or immutable release asset is changed. The new checker is source-only until a later approved release; old assets remain immutable.

Public persistent MCP workflow and adoption revalidation

The previous release milestone merged in PR #51 at 0b9d978b3fe333443ad8e4a51f2d914dd4fa22b6; all 18 exact-main jobs passed in run 33402169288. The next audit found two evidence boundaries rather than reasons to claim completion: the desktop automation runtime could not initialize, including after session reset, and GitHub's API confirmed the linked consumer is private and owned by the same maintainer. No desktop sign-in/trust state was inferred, no security prompt was automated, and no private source or credentials were copied into this public project.

The unchanged consumer was nevertheless qualified locally against the actual a10 wheel in a fresh isolated environment: 37 tests passed and its old-version assertion failed. The failure was preserved and the original repository stayed untouched. Exact artifact/source identities and limits are in the adoption record. This is neither a consumer repin nor third-party adoption. The older cached wheel did not match its historical digest and was not reused; the diagnostic used a fresh build from the recorded consumer commit instead.

P1 usefulness/evidence gap: public adopters could run the raw SQLite write example, but the advertised inventory MCP server only previewed reservations, and the real cross-repository MCP workflow required private access. Decision: compose the existing public store and Core bridge into a complete public MCP journey. Keep the preview unchanged, preserve the temporary no-argument demo, and avoid a new database abstraction, network service, account, provider dependency or copy of the private consumer.

Add init / serve CLI modes with host-selected paths, refused overwrite, no automatic database recreation and startup checks for required tables/columns.
Deny reservation execution and saved-result replay by default; enable writes only with the host flag, and reject unexpected registrations through the host policy.
Reuse the existing typed read/write contracts, atomic ledger, parameterized SQL, execution bounds and request retention. Keep client approval separate from host opt-in; neither is authentication for a network service.
Support legacy and opt-in modern ordinary tools, without tasks or logging.
Verify eight actual server processes with independent persisted stock/ledger checks: denial, one write, replay after restart, conflicting key, full ledger, invalid input, empty lookup and EOF. Keep this in the offline installed-wheel gate.
Add CLI/policy/schema regression tests and negative controls that detect absent durable writes and missing default denial.
Exclude local SQLite files/sidecars from Git and distribution archives; document plaintext storage, initialization failures, replay retention and shutdown limitations.
Finish local source and artifact verification; require exact-head hosted checks before merge and record those run IDs in the pull request.

Local verification passed 409 tests with 95.44% Core branch-aware coverage, Black (40 files), Ruff, strict mypy including Linux/Darwin platform checks (28 files), Bandit and git diff --check. An isolated build, strict Twine, the expanded offline gate and all three existing official-client journeys passed. The locally built wheel SHA-256 was bca3c0d3251319701950a567dc3fe06455deedcf9b50aafa477e8307bce5772d; it is not a replacement published asset. The expanded gate also passed against the actual published a10 wheel, confirming the new launcher composes its public runtime. Official-client checks still use the separate read-only protocol example; the new SQLite journey is independently checked through raw subprocess pipes and actual disk state, not represented as a signed-in or SDK-driven business acceptance test. Initial checker mistakes (matching the generic word "database" in schema descriptions and requiring a particular JSON key order) were corrected without weakening path-field or structured/text agreement checks. Tests also require cleanup after transport failure and nonzero interruption handling. SQLite data/sidecars were confirmed ignored by Git and absent from the built source archive.

Initial branch CI 33404782348 passed 17 jobs but the pre-existing concurrent-store test failed on Python 3.12 at its all-success assertion; its original assertion did not retain the failing result. The same commit's PR CI 33404788751 passed all 18. The exact original error is therefore not established. The atomicity test had coupled its success requirement to the demo's 250 ms SQLite wait and two-second invocation deadline, even though safe busy/timeout rejection is an allowed outcome. The test now uses explicit five-second lock waits and ten-second invocation limits, while keeping every success, replay, no-oversell and exact-ledger assertion unchanged and including failed results in diagnostics. Separate controlled lock/deadline tests retain short bounds. No exception is swallowed, no retry is added, and production/example defaults are unchanged. This is test timing isolation, not a claimed fix for a demonstrated Core runtime defect; new exact-head CI must pass before merge.

After the timing/diagnostic change, the complete local suite again passed all 409 tests (95.44% branch-aware coverage). Twelve local repetitions before that change had also passed; they did not reproduce or explain the original CI failure. The included external review completed for feature commit 92623134ab81f8302fe873241ada63132f64828b with no actionable code comments. Its docstring-coverage warning (20.93% across touched functions, including tests) is retained as non-blocking documentation polish, not described as a passed check. The host-facing entry points document their contracts; named regression tests and assertions carry the test intent. Its local-trust warning agrees with the documented single-host boundary. That review does not cover the later test-only timing change.

The launcher is an unreleased example change in the current checkout and uses the already published a10 runtime. It is not retroactively inserted into a10's immutable source archive. No Core public export, runtime dependency or server-side persistence layer was added. Desktop acceptance needs working automation and an actual operator consent flow; consumer upgrades remain in that repository's own task. These gaps do not justify weakening release claims or adding speculative platform features.

2.0.0a10 verified distribution

Release preparation PR #50 merged at e4d0ed3a85a65a2f3e11a02e2f744f42ca0e5c4a. Branch CI 33400702245, PR CI 33400707843 and exact-main CI 33400936385 each passed all 18 jobs; the tested branch and merge file trees were identical. Local release preparation passed 385 tests with 95.41% branch-aware coverage, Black (40 files), Ruff, strict mypy (28 files), Bandit, an isolated source-to-wheel build, strict Twine and all offline/official-client gates. Preparation changed version metadata and documentation only; its skipped CodeRabbit status is not an external review.

Exact-main build-only Release dry run, with privileged tag steps skipped.
Clean current main, enabled release immutability and a new annotated tag.
Published immutable prerelease with wheel, source archive and checksum manifest.
Fresh download: release signature, all three asset memberships, asset sizes and digests, and the exact two-distribution manifest.
Both provenance attestations constrained to the expected source commit, tag, release workflow and GitHub-hosted runners; no relaxed verification flags.
Offline installed-wheel runtime, MCP subprocess and SQLite transaction/replay gate.
Official SDK 1.29.1 legacy, 2.1.1 legacy and 2.1.1 modern journeys against the same downloaded wheel, including repeated cancellation and execution-slot recovery.
Manual Release dispatch on the published tag remains build-only.

Published wheel SHA-256: e84b26935ab9f73a7c632085ec9401256ffb8be0d107ce456a2e6604fec9d638. The source-archive attestation verifier initially failed public-good initialization; an unchanged retry passed. That transient is not suppressed or called a code fix. Exact assets, commands and workflow evidence are in the release record.

Disposition: published, independently installable evaluation alpha. No runtime dependency, account, telemetry, paid service or production deployment was added. The highest-value next gates are separate-consumer upgrade and signed-in desktop-client acceptance; neither can be inferred from SDK tests. Consumer changes belong in that repository's own task, and desktop acceptance needs an actual client consent flow. Stable API commitments, PyPI publication and production adoption remain separate decisions/evidence. Modern HTTP/authentication, MRTR, subscriptions and the redesigned task extension remain unsupported.

2.0.0a10 release preparation

Modern MCP support merged in PR #49 at 36da789cb82850f7378ef98abeeb1d8c9caaa613. All 18 exact-main jobs passed in run 33399732204, including both legacy SDK pins and the additional SDK 2.1.1 modern step on Linux, Windows and macOS. The final tested branch and merge have identical file trees. The resolved review comment and exact verification results are recorded in the PR evidence.

That increment aligned package, runtime and citation versions at 2.0.0a10 and closed the matching changelog entry. At that point it was preparation, not publication: a9 remained the documented download until a10 had verified assets. Source/package checks, three official-client journeys, complete exact-head CI, a default-branch dry run, immutable publication and fresh download/provenance checks were required before changing that claim. Those results are recorded above. No stable designation, PyPI upload or separate-consumer upgrade was implied by preparing a new alpha.

Opt-in 2026 MCP ordinary-tool compatibility

The previous cancellation milestone merged in PR #48 at 6da104f7923840f26686a742ed7036f27607d714; all 18 exact-main CI jobs passed in run 33396263775. The next gap was modern clients having to fall back to legacy initialization. Current primary-source research identified MCP 2026-07-28 as a substantial protocol change, not just a version-number addition: stateless request metadata, discovery, complete-result discriminators, cache hints and per-request logs are required or relevant to Core's tool surface; task execution moved to a redesigned extension. Sources and precise boundaries are in the MCP guide.

Decision: provide enable_modern=True while leaving the default 2025 contract and public result wrapping unchanged. Preserve ordinary tools and the existing runtime's validation, host policy, concurrency/rate/circuit controls and cancellation. Do not interpret the previous experimental tasks as the new extension or silently execute unsupported continuation requests. This is a protocol adapter, not a new framework, network service, SaaS frontend or reason to modify another repository.

Validate required metadata before execution and return supported-version errors.
Supply discovery, server identity, complete results, stable catalog order and conservative private zero-TTL cache hints without authentication assumptions.
Keep logging per-request, including concurrent calls; absent logLevel is silent.
Preserve legacy initialization when selected first; prevent cross-era state reuse.
Omit/reject legacy-task-required tools and reject task/MRTR call parameters.
Extend the real installed-wheel SDK 2.1.1 gate with modern discovery, ordinary calls, safe errors, progress, empty results and repeated cancellation/recovery.
Finish local regression, package and official-client verification; require exact-head CI before merge and record the hosted run evidence in the pull request.

The first real SDK 2.x modern and legacy runs passed against a locally built wheel. A concurrent SDK 1.x run exposed an existing checker scheduling assumption. A targeted repeat reproduced exact counters active=0, cancelled=1, completed=0, runtime_cancelled=0, runtime_timed_out=0, in_flight=1, pending=2: the worker had stopped and released execution capacity before the enclosing invocation finished terminal accounting/admission cleanup. The gate now tolerates only this bounded transient and still requires exact final counters within five seconds and at most 100 observations. Deterministic tests cover convergence and a permanently stuck counter state; missing remote cancellation remains a failure. No runtime accounting was changed to manufacture an atomic observation.

Final local verification: 385 tests passed with 95.41% branch-aware coverage, including 31 modern protocol cases and 43 checker tests. Black checked 40 files; Ruff, strict mypy (28 files), Bandit and git diff --check passed. An isolated source-to-wheel build, strict Twine checks and the offline runtime/MCP/SQLite gate passed. The final locally built wheel SHA-256 was b4e1037df0136da143a7c5ab584e2164d2efc32fe38d8dc3c3e5e50b22ae348f. All three official-client runs passed against that exact wheel: SDK 1.29.1 legacy, SDK 2.1.1 legacy, and SDK 2.1.1 modern. Separately, the source-backed reproducer passed 12 successive real SDK 1.x cancellation sessions (24 cancellations) after the checker correction. This repeated diagnostic is distinct from wheel evidence. Final example review also caught a backward-artifact compatibility issue: passing enable_modern=False to the old published constructor would fail even in legacy mode. The examples now pass the new keyword only when explicitly enabled; four regressions cover both launchers and modes. Both SDK pins then passed the updated legacy checker against the actual immutable a9 wheel, SHA-256 52ec76698f71584b29291e6b497ae94d8646721cafa38a49fed3ed7bf8e55e35. CodeRabbit completed a full review of implementation commit 737ecbfc69b76fb47613ee70cdecfafa52a9cf33 and found one functional compatibility issue: a legacy pre-initialize ping was routed to modern metadata validation. The follow-up preserves that ping without choosing an era and adds regressions for both subsequent protocol choices; a versioned modern ping still fails. Final verification above includes that correction. This is not a claim that the follow-up commits received a second full external review.

At implementation merge this was an unreleased opt-in API, absent from the immutable a9 wheel; a10 publication is verified separately above. No new dependency or external service. HTTP/authentication, subscriptions, MRTR and redesigned tasks are explicitly unsupported; signed-in desktop acceptance and separate-consumer upgrade remain separate gates. Modern support does not claim broader schema adoption or forced termination/rollback of arbitrary tool effects.

Official-client cancellation and recovery

PR #47 merged at 84c305a9e98b4841ff3b231ebd4ab8bad01a3299, with all 18 exact-main CI jobs passing in run 33394265552. That established ordinary-call interoperability; it did not prove official-client cancellation. Inspection of the pinned SDKs found an important host distinction: 1.29.1 abandons local waiting without notifying the server, whereas 2.1.1 sends a courtesy cancellation notification. The checker now exercises both honest paths.

Add an in-memory fixture with one execution slot and public tool/runtime cleanup counters; wait for actual start progress rather than an arbitrary delay.
For 1.x, observe the exact ID in the SDK's typed outgoing request and send a typed cancellation notification before stopping the local waiter. No private SDK state or assumed progress-token/request-ID equality is used.
For 2.x, cancel only the local waiting task and require the SDK to send its notification. No injected cancellation can mask a broken automatic path.
Require two cancellation/recovery cycles with no active/completed waiters, exact cancellation counts, zero runtime timeouts and the same sole execution slot acquired by a follow-up tool. Bound start and recovery checks to five seconds.
Add negative controls for absent remote cancellation, leaked capacity, missing start, early completion, swallowed cancellation, timeout substitution and private progress; directly test the fixture and transparent request-ID observer.

Both real SDK versions passed against the unchanged published a9 wheel on Windows/Python 3.11.9, SHA-256 52ec76698f71584b29291e6b497ae94d8646721cafa38a49fed3ed7bf8e55e35. A real SDK 1.x negative control omitted only the explicit notification: after observed start and local cancellation, the recovery call remained blocked and hit its 0.5-second test bound. That expected failure confirms local cancellation alone does not establish remote cleanup; it was not suppressed in the passing journey. Local verification passed 340 tests with 95.23% branch-aware coverage, including 29 official-checker tests. Black checked 39 files, strict mypy checked 28 files, Ruff and Bandit passed, and a fresh source-to-wheel build, strict Twine checks and the existing offline runtime/MCP/SQLite gate passed. Hosted exact-head evidence belongs to the pull request. No Core runtime or public export change was needed; the existing six SDK CI jobs now include this additional session. The independent server watchdog still bounds failed cleanup. This is cooperative async cancellation evidence, not sync-thread termination, durable rollback, task cancellation or signed-in user consent. Reproduction uses the unchanged official-client command in the MCP guide.

Official-client interoperability follow-up

After the a9 release, current upstream metadata identified official MCP Python SDK 2.1.1 as released on 2026-08-25 and maintained 1.29.1 on 2026-08-24. Core's description of 2025-11-25 as the current stable protocol was stale. This increment keeps the supported revisions explicit instead of silently claiming newer features or widening the runtime. The SDK's current auto client can negotiate backward; that behavior needed actual external-client evidence, not just Core's own parser.

Add scripts/verify_mcp_client.py using official SDK transport, sessions and models; normalize v1/v2 Python naming through public wire aliases.
Run the server from an exact wheel in a fresh offline Core-only environment, outside the source checkout with isolated Python imports; reject SDK pin drift.
Verify discovery, schema validity, Unicode/newlines, output/text agreement, safe invalid-input results, synthetic private-input redaction, filtered logging, progress, empty results, error recovery and client-context shutdown.
Exercise SDK 2.x's default discovery-to-handshake fallback; assert the negotiated revision rather than treating current SDK support as modern MCP support.
Add independent client jobs for both SDK pins on Linux, Windows and macOS, leaving SDK dependencies out of Core's runtime and normal development install.
Bound session/checker/setup time, terminate a stuck checker and independently bound the server lifetime even when the SDK starts a separate process group; add checker negative controls for incorrect results, missing progress, private logs, version drift, ambiguous wheels, process failure and timeout cleanup.

Both pins passed on Windows/Python 3.11.9 against the actual downloaded a9 wheel, SHA-256 52ec76698f71584b29291e6b497ae94d8646721cafa38a49fed3ed7bf8e55e35. The initial checker run exposed a misspelled metadata-key assertion; that checker defect was corrected before the passing runs. No Core runtime change was required. SDK 2.x's expected logging deprecation warning remains visible because the journey intentionally exercises a negotiated 2025 revision. The final full local suite passed 329 tests with 95.23% branch-aware coverage, including 18 checker regressions. Black checked 38 files; Ruff, strict mypy (27 files) and Bandit passed. An isolated source-to-wheel build, strict Twine checks and the existing offline runtime/MCP/SQLite gate also passed. The SDK pins passed against the published artifact, not only a rebuild. Final process-boundary review found that the SDK isolates its server's process group; a stdlib-only 55-second server watchdog and normal-exit/forced-exit regression tests were added before merge. A watchdog exit is a failed check, not a passing shutdown. Hosted exact-head matrix/build evidence is recorded in the pull request; this is not a claim that the separate repository consumer has upgraded.

At that milestone, the client checks did not cover tasks, cancellation, desktop-client trust, HTTP/authentication or newer protocol features. Task APIs removed upstream in SDK 2.x are not silently emulated or advertised as compatible. Newer protocol semantics and official-client cancellation were next priorities, separately from that verified backward-compatible journey. The SDK pins are exact but their transitive dependencies resolve at installation time. No production service, credentials, telemetry or external tool invocation is added. Reproduction commands and primary upstream references are in the MCP guide.

2.0.0a9 verified distribution

The boundary fixes merged in PR #44 at bc1fe2b2a6c9a215b37a698056c633795072fbd0. CodeRabbit completed a full review of c4712d80bae085789ad4fadb2f74272f7e16f60f; its sole actionable checksum-glob comment was fixed in 5198a8abae98cc98df170480cf8640c4eb9440dc and the thread resolved. That follow-up added an explicit -- option terminator and a regression assertion; it was not represented as a second full review. All 12 exact-main CI jobs passed in run 33390409997.

Release preparation PR #45 merged at 8957b208db4ee08a32e9c66cf0cf50b7dc7422a4. All 12 exact-main CI jobs and the build-only dry run passed before the annotated v2.0.0a9 tag was pushed. The immutable GitHub prerelease was published on 2026-08-31. A subsequent manual dispatch on the actual tag also passed with attestation and publication skipped, proving the new event guard in addition to its source-level regression test.

All three fresh release downloads passed immutable membership and digest checks. Wheel and source-distribution provenance passed exact repository, workflow, tag and source-commit constraints with self-hosted runners denied. One wheel verifier initialization failure resolved on an identical retry; no constraint was relaxed. The downloaded wheel installed offline into a fresh Python 3.11.9 environment and passed the expanded runtime, bounded diagnostic/numeric, real MCP subprocess and SQLite transaction/replay gate. The source suite passed 311 tests with 95.23% branch-aware coverage. See release evidence for asset digests, hosted runs and exact verification commands.

Disposition: a useful, reproducible evaluation alpha, not a stable API or proven third-party production offering. This increment adds no public exports, runtime dependencies, services, telemetry or retries. No PyPI upload, deployment, paid account, user data or other-repository change was needed. Next: upgrade and rerun the separate consumer at the new exact release, complete operator-owned client trust/tool approval, and collect real workload feedback before expanding scope.

Post-a8 input-boundary review and remediation

An offline standard security review at clean ced7be6ee96ba08af5ecb92bfc2683ee6466ab9b covered all 69 supported tracked files; the 38 unsupported legacy/ files were explicitly excluded. Independent baseline, architecture, and focused boundary reviews were reconciled against source. The generated local report is scan 3565ffc8-e944-47f3-afaa-859cdc36624a. No application code or network access was used during that scan, and the advisory connector was unavailable. The report describes the pre-fix commit, not the patched tree.

The review confirmed medium-severity diagnostic amplification before execution and low-severity numeric overflow affecting a host-owned mixed batch. It also confirmed session-local MCP malformed-method/Unicode failures and output-frame overflow as reliability defects, without claiming a built-in remote service or new client authority.

Bound error aggregation at every nesting level to 64 issues including an explicit truncation marker; cap paths/messages at 128 characters and abbreviate dictionary keys before composing descendant paths. Preserve valid long-key data, short diagnostics, and valid alternatives after failed union validation.
Normalize float overflow into finite-number validation errors, including nested annotations, float-first unions, defaults, outputs, and ordered batches.
Guard MCP method classification, escape lone-surrogate metadata safely, and bound final fallback frames including their newline and oversized IDs.
Add installed-wheel numeric/diagnostic and real-pipe malformed-MCP checks, including negative controls for defective package checkers.
Require an actual tag-push event for privileged release steps; preserve manual dispatch as build-only even on a tag ref. Include that workflow in source archives so its source-level regression test has the required fixture.
Clarify lazy experimental task cleanup: TTL limits access, not timed physical memory erasure. Remove the stale version-specific API introduction.

Before fixes, the new suites reproduced 14 validation failures and 11 MCP failures on bounded payloads (the two initialization fixtures were corrected and independently reproduced their UTF-8 failures). No full-scale memory-exhaustion payload was run. After fixes, python -m pytest passed 311 tests with 95.23% branch-aware coverage; Black checked 35 files, Ruff passed, strict mypy checked 25 files, and Bandit over src passed. The fixes add no public exports, dependencies, external services, telemetry, or automatic retries. An isolated source-distribution-to-wheel build and strict Twine checks passed, followed by a fresh offline install exercising runtime boundaries, real MCP pipes, and SQLite transaction/replay. The actual published a8 wheel matched its known SHA-256 but failed the expanded checker with the expected numeric OverflowError; that is a negative control, not a new passing a8 claim. Hosted exact-commit and new-release evidence is recorded above. Published a8 remains immutable and does not acquire these fixes retroactively.

2.0.0a8 verified distribution

The finite-deadline fix merged in PR #41 at 1c05fb4bd46d4836b2f4ced6698d3071d7b00eeb; all 12 exact-main CI jobs passed in run 33385148670. CodeRabbit completed its full review with no actionable findings (a non-blocking test/helper docstring-coverage warning remains separate from required quality gates). A freshly downloaded a7 wheel matched its immutable release and known digest, but correctly failed the new gate with invalid deadline was not rejected.

Release preparation PR #42 synchronized the package/citation metadata and dated the changelog. All 12 exact-main CI jobs and the build-only release dry run passed before the annotated v2.0.0a8 tag was pushed at dfaf41ee850ff94c7f106c60a6752865fb364ad4. The immutable GitHub prerelease was published on 2026-08-31, with unchanged historical a7 assets.

Fresh downloads passed release membership and SHA-256 manifest verification. Both distribution attestations passed explicit repository, workflow, source-ref and source digest constraints with self-hosted runners denied. The downloaded wheel installed offline into a fresh Python 3.11.9 environment and passed runtime/deadline, ordered batch, circuit recovery, MCP subprocess and SQLite transaction/replay checks. See docs/RELEASING.md for exact assets, digests, workflow IDs and verification commands.

Disposition: a reproducible, useful evaluation alpha for typed Python tools, not a stable API or independently proven production service. No PyPI upload, deployment, paid account, new dependency, external data or other-repository change was needed. At that release, the next priority was a consumer-owned a8 upgrade and workload feedback; the existing exact-pin consumer evidence is not silently extended to this release.

Finite-deadline validation follow-up

At clean main 0ccd94b55f0ade481ce073bf3e495f8b1711c73f, a bounded reproduction found that NaN and infinity were accepted as execution deadlines, while an integer such as 10**1000 could leak OverflowError and abort an entire batch. Invalid wait/close timeouts were also accepted, and overflowing MCP task TTLs produced an internal-server error rather than invalid parameters. These were real validation defects affecting otherwise valid calls, not a need for a broader scheduling API.

Normalize finite durations before decorator metadata, runtime construction, invocation admission, and shutdown side effects.
Preserve timeout precedence, positive finite values, explicit None semantics, and zero-duration sync polling; reject bad overrides with invalid_timeout.
Prove invalid calls do not reach policy or execution, consume capacity/rate tokens, trip circuits, leak inputs, or abort good batch items.
Reject unrepresentable task-duration configuration and requested TTLs; prove invalid parameters leave the sole task slot and protocol request ID reusable.
Add installed-wheel deadline/batch regression checks and prove the checker catches discarded deadlines and dropped batch items.

Local verification passed: python -m pytest (279 tests, 94.87% branch-aware coverage), Black (33 files), Ruff, strict mypy (25 files), and Bandit over src. The 39 new cases include 37 runtime/protocol regressions and two negative controls for the package checker. An isolated sdist-to-wheel build, strict Twine check and fresh offline wheel installation passed, including actual deadline/batch behavior, MCP subprocess pipes, and SQLite transaction/replay. Hosted exact-head evidence belongs to the pull request.

This intentionally tightens invalid configuration handling without new public exports, dependencies, services or telemetry. Finite does not mean operationally sensible: the host must still choose practical deadlines. Async cancellation cleanup is cooperative, sync workers cannot be force-killed, and aclose(timeout=...) bounds its sync-worker wait rather than all async cancellation. Docs now distinguish these limitations. The immutable published a7 wheel does not include this fix and cannot pass the newly expanded deadline gate; its earlier verification remains historical evidence. The fix is now distributed in the separately verified a8 release described above.

Transactional application example follow-up

At clean main 048f26a608201d8a09a8d826f041f6598baaa0ee, 208 tests passed with 94.81% branch-aware coverage on Windows/Python 3.11.9. The docs advised making side effects idempotent, but the reservation examples only returned shaped responses. The next adoption gap was a real, reproducible write/replay journey, not a generic runtime persistence or retry layer.

Add an application-owned SQLite inventory store and typed sync tools.
Commit stock and its bounded request ledger atomically; replay identical keys, reject conflicting key reuse, and preserve terminal business rejections.
Prove concurrent duplicate/competing requests across runtime instances, statement/commit rollback, finite lock waiting and replay in a separate process.
Commit real data before deliberately withholding a sync response; prove that timeout/cancellation retains the worker, quiescence is observable, and a later replay never decrements stock again.
Run the self-verifying demo with the isolated installed-wheel gate; keep the earlier MCP preview read-only and clarify the policy-only example's simulation.

docs/SIDE_EFFECTS.md specifies business outcomes separately from runtime status, host-owned authorization and database paths, single-tenant request identity, finite retention without automatic eviction, explicit connections and transaction boundaries, and unproven production properties. SQLite storage is confined to this example, not added to Core's API or runtime requirements. No external account, production data, service, network call or paid dependency is needed.

Local final verification passed: 240 tests with 94.81% branch-aware Core coverage, Black (31 files), Ruff, strict mypy (24 files), and Bandit over Core plus the new SQLite example. The isolated sdist-to-wheel build and strict Twine checks passed; the fresh offline installed-wheel gate passed exports/runtime behavior, real MCP pipes, and the SQLite commit/replay demonstration. The policy preview was also run and produced the expected denial followed by an allowed preview. The 32 new example tests are behavioral evidence, not a claim of power-loss or third-party deployment validation. Exact-head hosted checks are recorded in the corresponding pull request.

Dependency-outage evaluation follow-up

At clean main 6ded14d4a5a1a1754d5d080a8dad763161c19b3d, 185 tests passed with 94.73% branch-aware coverage on Windows/Python 3.11.9. The existing no-I/O microbenchmarks did not quantify interference from a failing dependency or the cost trade-off of limiting that dependency's concurrency. This was an evaluation-evidence gap, not a newly discovered runtime defect or a reason to expand the public API.

Add a bounded synthetic mixed-vendor/cache workload using the real public API.
Compare global capacity, a per-vendor bulkhead, and bulkhead plus circuit control with the same finite request burst and an event-based saturation barrier.
Verify exact successful cache outputs, real vendor executions, safe failures, capacity/metrics, cancellation cleanup, and missing-control detection.
Preserve every repeated measurement and the benchmark digest; document both faster unrelated requests and the slower failure-drain trade-off of a bulkhead.

The recorded five-repetition run made 64 vendor requests and 32 cache requests per scenario. All cache calls succeeded; circuit control reduced actual vendor executions from 64 to two, returning 62 safe failures rather than useful work. See docs/BENCHMARKS.md and its raw report for timings, methodology and limitations. This improves independent evaluation for tool-runtime adopters but is synthetic local evidence, not third-party production adoption. No runtime source, dependency, hosting, telemetry, published artifact or public API was changed.

Final local checks passed: python -m pytest (208 tests, 94.81% branch-aware coverage), python -m black --check src tests examples benchmarks scripts (29 files), python -m ruff check src tests examples benchmarks scripts, python -m mypy (23 files), and python -m bandit -q -r src. An isolated python -m build, strict Twine check, and scripts/verify_distribution.py passed for the candidate wheel. An additional one-repetition run at 512 vendor calls, 512 cache calls and 1 ms delay passed all three scenarios with zero admission rejections, correct cache results and 510 circuit rejections after two actual vendor executions in the guarded scenario. Hosted exact-head verification is recorded in the pull request.

Current verification follow-up

At clean main 4f5d04d3cf3c1f7b2dcec693154d502dd0f6f1b2, the baseline suite passed 177 tests with 94.73% branch coverage on Windows/Python 3.11.9. Two release-evidence gaps remained despite the green source suite: the shared wheel smoke only checked exports/model construction, and hosted package verification ran only on Linux. The previously claimed automated circuit-recovery smoke was therefore overstated.

Replace the import-only gate with real installed sync/async, validation, batch, redacted circuit failure/recovery, metrics and quiescence checks.
Exercise the documented inventory MCP server through actual subprocess pipes, including UTF-8, operational logging, progress ordering, and EOF shutdown.
Prove checker failures for wrong output/version, malformed stdout, ambiguous artifacts, and a hung child; retain checks under Python optimization.
Add fresh offline-wheel CI at Python 3.10 and 3.14 on Linux, Windows, and macOS.
Re-download and verify the unchanged a7 wheel with the expanded gate locally; keep artifact publication and new verification-script provenance distinct.

These changes strengthen reproducible package evaluation for Python tool developers. They add no runtime dependencies, API surface, telemetry, hosting, or external service. See docs/RELEASING.md for commands and the explicit historical evidence correction. Local final verification: 185 tests passed with 94.73% branch-aware coverage; Black, Ruff, strict mypy (22 files), source Bandit, isolated build and strict Twine checks passed. Both the new candidate and freshly downloaded immutable a7 wheel passed the offline installed-package gate on Windows/Python 3.11.9. Hosted results are recorded on the corresponding pull request rather than inferred from this local execution.

Original assessment

The repository began as a broad "unified agent runtime" containing orchestration, reasoning, tool, metrics, and LLM-provider prototypes. The initial implementation never formed an installable Python package, and later documentation described a much larger product than the source actually supplied.

The strongest defensible independent product is a small, provider-neutral Python runtime for defining, inspecting, and safely invoking application-owned tools. It uses the existing decorator, registry, timeout, metrics, and async-execution ideas without trying to reproduce the flagship helix-unified application or compete with full agent frameworks.

What worked at baseline

The repository contained useful raw ideas for a decorator-based tool registry, async execution, timeouts, in-memory metrics, and response metadata.
The source was Python-only and could become dependency-free at runtime.
A source distribution and wheel could be built mechanically.

What did not work at baseline

pip install . failed because helix-flow>=1.0.0 and helix-circle>=1.0.0 were mandatory but unavailable from the configured package index.
The built wheel was 5,206 bytes and contained only distribution metadata and the license; it contained no importable helix_core package.
import helix_core, import llm_providers, and python examples/basic_usage.py all failed.
python -m pytest collected 41 mock-oriented tests but produced 41 setup errors and 0% coverage because the repository-root __init__.py could not be imported as a package.
Five advertised test modules were empty. The non-empty tests exercised AsyncMock fixtures instead of the implementation.
The core dataclasses and their consumers disagreed about field names, status values, lifecycle methods, and result shapes.
The README referenced missing requirements, docs, workflows, APIs, and an MIT license while the repository contains a Business Source License.
No CI workflow existed at HEAD; the earlier workflow deliberately ignored lint and test failures.

Chosen product definition

Samsarix Core is a lightweight, local-first Python tool runtime. It lets a developer:

mark a normal sync or async Python function as a tool;
register it under a stable name;
inspect a JSON-Schema-compatible input contract;
invoke it with validated arguments;
receive a structured success, validation, timeout, or failure result while normal caller cancellation propagates; and
run independent calls with an explicit concurrency bound.

The package does not choose an LLM provider or require an LLM. Its schemas and result objects are suitable for adapters in agent frameworks, CLIs, bots, local automation, or helix-unified.

Target user and primary use case

The target user is a Python developer building an agent, workflow engine, bot, or automation service who wants a small execution kernel without adopting a full AI framework.

The primary release journey is:

install -> decorate a typed function -> register it -> inspect its schema -> invoke it -> handle the structured result

This is independently useful because tool definition and execution are ordinary application infrastructure, not a Samsarix-hosted service.

Product and architecture decisions

Use a conventional src/samsarix_core package layout so tests and builds exercise the installed package shape, with a lightweight helix_core compatibility import. The Python Packaging User Guide describes the src layout as a guard against accidentally importing repository-root files: https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/.
Keep the first release free of runtime dependencies. The standard library is sufficient for signatures, JSON-compatible schemas, validation, async execution, timeouts, and metrics.
Treat type hints and docstrings as the public tool contract. This matches current tool conventions in LangChain and Pydantic AI, while keeping Samsarix Core much smaller and provider-neutral: https://docs.langchain.com/oss/python/langchain/tools and https://pydantic.dev/docs/ai/tools-toolsets/tools/.
Export conservative JSON-Schema-compatible object schemas and reject unknown arguments. JSON Schema Draft 2020-12 is the reference vocabulary: https://json-schema.org/draft/2020-12.
Compile TypedDict into strict named object properties rather than representing heterogeneous records as a loose value union. MCP defines tool input/output contracts as JSON Schema objects, while Python exposes is_typeddict and semantic required/optional key introspection without a runtime dependency: https://modelcontextprotocol.io/specification/2025-11-25/schema and https://docs.python.org/3/library/typing.html#typing.TypedDict.
Return structured results rather than swallowing errors or raising ordinary tool failures across the runtime boundary. Programmer/configuration errors may still raise during decoration or registration.
Offer an optional host-owned pre-execution policy after validation. Current MCP guidance recommends a human denial surface, while current OpenAI Agents SDK and LangChain documentation expose per-tool guardrails or conditional approval policies: https://modelcontextprotocol.io/specification/2025-11-25/server/tools, https://openai.github.io/openai-agents-python/guardrails/, and https://docs.langchain.com/oss/python/langchain/human-in-the-loop. Core supplies only a bounded programmatic allow/deny boundary; client UI and durable approval state remain outside this runtime.
Run synchronous functions in a worker thread. Timeouts bound the caller's wait, but cannot forcibly stop a Python thread; this limitation must remain explicit.
Do not call in-process execution a sandbox. Registered tools retain the current process's filesystem, network, and environment permissions.
Do not log tool arguments, return values, prompts, credentials, or user content by default.
Do not ship the copied multi-provider LLM gateway as part of the supported package. Provider integration is a separate product concern with credentials, privacy, retries, pricing, and fast-moving model compatibility.

Assumptions

The repository owner wants an honest, independently useful extraction rather than a second copy of helix-unified.
Python 3.10 remains the minimum supported version unless compatibility testing proves otherwise.
The existing license text is owner-controlled. Engineering may correct metadata and documentation to describe it, but must not replace the license.
Application code, not an untrusted end user, chooses which Python functions are registered. Tool arguments can still be untrusted and must be validated.

Baseline command results

All baseline commands were run on Windows with Python 3.11.9 at commit 69c9a2bc76ec700cb4bcf7af4286e24d75ea6667.

Command	Result
`python -m pip install .` in a new virtual environment	Failed: no matching distribution for `helix-flow>=1.0.0`; package not installed.
`python -m build --outdir <temp> <clean-copy>`	Exited 0, but produced a metadata-only 5,206-byte wheel with no `helix_core` package and emitted deprecated license-table warnings.
`python -c "import helix_core"`	Failed with `ModuleNotFoundError`.
`python -c "import llm_providers"`	Failed because `llm_providers.unified_llm` did not exist.
`python examples/basic_usage.py`	Failed because `helix_core` did not exist.
`python -m pytest`	Failed: 41 setup errors, 0% coverage, 70% threshold not met.
`python -m black --check .`	Failed: 20 files would be reformatted.
`python -m flake8 .`	Failed with extensive style and unused-code findings.
`python -m mypy . --ignore-missing-imports`	Failed: repository directory name was treated as an invalid package name.

Prioritized findings

P0

Make a normal pip install . succeed without private or imaginary dependencies.
Ensure wheel and sdist contain the actual public package.
Make the documented primary journey runnable without credentials or network access.
Replace mock-only/broken tests with implementation tests and an installed wheel smoke test.
Restore CI that fails when meaningful checks fail.
Replace inaccurate README installation, API, maturity, CI, and license claims.

P1

P2

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.
Add strict named and nested TypedDict schemas after the first consumer exposed the ambiguity of heterogeneous dict results.
Add richer schema support for dataclasses, enums, and constrained values if real adopters need it.

Implementation checklist

Build the public src/samsarix_core API and legacy import compatibility layer.
Implement decoration, schema generation, registration, validation, execution, results, metrics, batch calls, lifecycle, timeout, and cancellation behavior.
Add a copy-pasteable offline example.
Add focused unit and integration tests, including the built wheel.
Add bounded development dependency ranges and deterministic tool configuration.
Add CI across supported Python versions.
Rewrite the README and contribution guidance around actual commands.
Complete the repository-wide threat model, candidate review, validation, and attack-path analysis.
Perform final clean install/build/test/lint/type-check/example verification.

Release acceptance criteria

A fresh virtual environment can install the repository with no private package index or credentials.
The built wheel contains samsarix_core and the helix_core compatibility import, and works when installed outside the source tree.
A new user can complete the primary journey from the README in under five minutes and entirely offline.
Invalid, missing, extra, failed, timed-out, and cancelled invocations have tested behavior.
Concurrency is bounded and tested.
Formatting, linting, type checking, tests, package build, and example execution pass locally and in CI.
Documentation contains no unsupported production, provider, benchmark, coverage, license, or security claims.
No locally actionable P0 remains.

Completed work

Protected and inventoried the clean worktree before edits.
Reviewed all 47 baseline files, recent history, local branches, removed CI, public APIs, tests, examples, configuration, and security-sensitive paths.
Recorded real baseline install, build, import, example, test, format, lint, and type-check results.
Performed bounded comparison against current official packaging, schema, and tool framework documentation.
Selected the narrow standalone tool-runtime product wedge.
Replaced the broken flat layout with the supported src/samsarix_core package, retained a narrow compatibility import, and archived the pre-2.0 prototypes outside the distribution.
Implemented typed declaration, schema export, strict input/default/output validation, structured errors, redaction-by-default, bounded sync/async execution, batch ordering, cancellation, lifecycle, and content-free metrics.
Added 27 real behavioral tests with a 90% branch-aware coverage gate, strict mypy, Ruff, Black, a Python 3.10-3.14 CI matrix, and pinned CI actions.
Built the sdist and universal wheel and completed the offline example from an 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, client cancellation, and bounded concurrent local stdio transport without a runtime dependency.
Added opt-in experimental MCP task augmentation for long-running local jobs, with per-tool negotiation, secure IDs, finite in-memory retention, polling, blocking result retrieval, cancellation, and conservative omission of unauthenticated task listing.
Added stable MCP progress notifications with invocation-scoped async reporting, strict monotonicity, update and UTF-8 message caps, cancellation cutoff, and custom-transport failure propagation.
Added registry, batch, value-complexity, argument, and output resource budgets, plus observable bounded shutdown quiescence for timed-out synchronous work.
Added an async invocation policy with detached validated context, explicit decisions, bounded evaluation, timeout/cancellation integration, safe denial/failure results, and content-free denial metrics across direct, batch, MCP, and MCP task execution.
Added host-configured per-tool execution bulkheads that acquire before global runtime capacity, preserve unrelated tool availability, and retain their slot for surviving synchronous work after timeout or cancellation.
Added host-configured per-tool token buckets immediately before execution, with sustained refill and burst controls, safe retry delays, policy-aware accounting, content-free metrics/lifecycle, and ordinary/task MCP serialization.
Added provider-neutral lifecycle observability with immutable content-free event models, paired logical start/terminal signals, cancellation and host-abort coverage, non-interfering handler failure accounting, and documented OpenTelemetry mapping.
Proved the public MCP API, exact typed result discovery, response-free 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.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 and per-tool circuit failure, fail-fast rejection, and successful half-open recovery on the real redaction adapter.

Deferred work and rationale

P2 framework/provider adapters, durable registry/invocation persistence, process isolation, and richer schema types remain deliberately deferred. Experimental MCP tasks retain bounded results only inside one server process and do not satisfy durable 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 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 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 38-test exact-pin and clean-wheel behavioral evidence is recorded separately in docs/ADOPTION.md.

Owner-, credential-, or production-blocked tasks

The immutable GitHub prerelease v2.0.0a11 is published from commit d9ae73cf09e17a6ed3a6d2f092645dcac4743e22 with verified checksums, GitHub Actions build provenance, clean installed-wheel runtime, MCP and SQLite checks, and official legacy/modern client, persistent MCP reservation and cooperative cancellation journeys. The exact assets, workflow runs, verification, installation evidence, and recovery model are recorded in docs/RELEASING.md. This passes the GitHub release gate only; it does not pass the PyPI, stable API, or third-party production-adoption gates.

Decide whether commercial licensing, paid support, or a service-level agreement will be offered separately from the MPL-2.0 community distribution. None is promised by this repository.
PyPI publication, account creation, and service deployment remain separate owner decisions. The owner has authorized this repository's verified GitHub prerelease.

Known risks

Python thread cancellation is cooperative; a timed-out synchronous function can continue in its worker thread. Its lifetime is now observable and waitable, but the function still needs its own deadline to guarantee eventual termination.
In-process tools have the host process's permissions. This runtime is not suitable for arbitrary untrusted code without a separate isolation boundary.
Type hints are not a complete runtime validation language. This alpha supports a documented JSON-compatible subset and rejects ambiguous usage.
Exception redaction protects ordinary failures, but successful outputs and validation details still cross to the host by design.
The MCP stdio adapter and runtime have per-message and per-invocation byte limits plus opt-in process-local per-tool rate controls, but no authenticated tenant quota, cross-process rate coordination, connection limit, or aggregate-memory limit. Any remote host must apply those controls before invocation.
Public package-index publication still requires owner-controlled credentials and an explicit release decision.
Experimental task results are retained in process until a finite TTL. Task IDs are secure random values and stdio does not expose listing, but possession grants get/result/cancel access within that logical session; a network host must bind task operations to authenticated requestor identity.

Distribution and sustainability model

The simplest distribution is a pure-Python wheel and source distribution built from GitHub tags, with no hosted service and no required API account. Operating cost is therefore zero for the library itself; adopters pay only for infrastructure or providers they choose outside Samsarix Core.

The unmodified MPL-2.0 license protects distributed changes to covered files while allowing use in larger proprietary applications. Sustainability can come from paid integration, support, hosted products, or separate commercial arrangements, but none of those offerings or any revenue and demand claims are assumed here.