capability-reasoning-kernel 0.4.2__tar.gz → 0.5.0__tar.gz

capability_reasoning_kernel-0.5.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      github-actions:
+        patterns: ["*"]
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly

capability_reasoning_kernel-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,151 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      live_providers:
+        description: Comma-separated providers required by the live gate
+        required: true
+        default: deepseek
+        type: string
+  workflow_call:
+    inputs:
+      live_providers:
+        description: Comma-separated providers required by the live gate
+        required: false
+        default: ""
+        type: string
+    secrets:
+      ANTHROPIC_API_KEY:
+        required: false
+      OPENAI_API_KEY:
+        required: false
+      DEEPSEEK_API_KEY:
+        required: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "0.12.10"
+          checksum: "173d95a0c32d18c896c46ba6fafbf3cf9c14ab74b033f81b76c883ef492a976b"
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install just
+        uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
+
+      - name: Sync dependencies
+        run: uv sync --all-extras --locked
+
+      # The justfile uses `set dotenv-load`; provide a no-secret env so it loads cleanly.
+      # The default suite is key-free and `live` tests are excluded via addopts -m 'not live'.
+      - name: Prepare env
+        run: cp .env.example .env
+
+      - name: Lint
+        run: just lint
+
+      - name: Typecheck
+        run: just typecheck
+
+      - name: Test
+        run: just test # runs with coverage; fails under the threshold in pyproject
+
+      - name: Verify distribution
+        run: just package-check
+
+  artifact-roundtrip:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "0.12.10"
+          checksum: "173d95a0c32d18c896c46ba6fafbf3cf9c14ab74b033f81b76c883ef492a976b"
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Build distribution
+        run: |
+          uv sync --all-extras --locked
+          uv build --clear
+          uv run twine check --strict dist/*
+          uv run python scripts/check_artifacts.py dist
+          sha256sum dist/* > SHA256SUMS
+
+      - name: Upload distribution
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: ci-distribution
+          path: |
+            dist/
+            SHA256SUMS
+          if-no-files-found: error
+          retention-days: 1
+
+      - name: Download distribution
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: ci-distribution
+          path: roundtrip
+
+      - name: Verify downloaded bytes
+        working-directory: roundtrip
+        run: sha256sum --check SHA256SUMS
+
+  # Explicit provider qualification: manual or required by the release's reusable workflow call.
+  live:
+    if: inputs.live_providers != ''
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "0.12.10"
+          checksum: "173d95a0c32d18c896c46ba6fafbf3cf9c14ab74b033f81b76c883ef492a976b"
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install just
+        uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
+
+      - name: Sync dependencies
+        run: uv sync --all-extras --locked
+
+      - name: Run live provider tests
+        env:
+          RK_LIVE_PROVIDERS: ${{ inputs.live_providers }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
+        run: just test-live

{capability_reasoning_kernel-0.4.2 → capability_reasoning_kernel-0.5.0}/.github/workflows/pages.yml

@@ -29,20 +29,20 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       # Actions pinned to immutable commit SHAs (supply-chain hardening); tag in comment.
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Configure Pages
-        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
         with:
           enablement: true # self-enable Pages (build_type=workflow) on first run — no manual Settings step
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
           path: docs
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

capability_reasoning_kernel-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,107 @@
+name: Release
+
+# Test the tagged commit, then promote one immutable distribution through both indexes.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  quality:
+    uses: ./.github/workflows/ci.yml
+    with:
+      live_providers: deepseek
+    secrets:
+      DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
+
+  build:
+    needs: quality
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "0.12.10"
+          checksum: "173d95a0c32d18c896c46ba6fafbf3cf9c14ab74b033f81b76c883ef492a976b"
+          python-version: "3.12"
+      - run: uv sync --all-extras --locked
+      - name: Validate tag and build
+        run: |
+          uv run python scripts/check_version.py
+          uv build --clear
+          uv run twine check --strict dist/*
+          uv run python scripts/check_artifacts.py dist
+          sha256sum dist/* > SHA256SUMS
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: distribution
+          path: |
+            dist/
+            SHA256SUMS
+          if-no-files-found: error
+
+  testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distribution
+      - run: sha256sum --check SHA256SUMS
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  verify-testpypi:
+    needs: testpypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distribution
+      - run: sha256sum --check SHA256SUMS
+      - run: python scripts/check_published.py dist testpypi
+
+  pypi:
+    needs: verify-testpypi
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distribution
+      - run: sha256sum --check SHA256SUMS
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+
+  verify-pypi:
+    needs: pypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distribution
+      - run: sha256sum --check SHA256SUMS
+      - run: python scripts/check_published.py dist pypi

{capability_reasoning_kernel-0.4.2 → capability_reasoning_kernel-0.5.0}/.pre-commit-config.yaml

@@ -16,13 +16,13 @@ repos:
       - id: ruff-check
         name: ruff check --fix (uv.lock version, same as `just fix`)
         language: system
-        entry: uv run ruff check --fix src/ tests/
+        entry: uv run ruff check --fix src/ tests/ scripts/
         pass_filenames: false
         types_or: [python, pyi]
       - id: ruff-format
         name: ruff format (uv.lock version, same as `just fix`)
         language: system
-        entry: uv run ruff format src/ tests/
+        entry: uv run ruff format src/ tests/ scripts/
         pass_filenames: false
         types_or: [python, pyi]
       - id: pyright

{capability_reasoning_kernel-0.4.2 → capability_reasoning_kernel-0.5.0}/CHANGELOG.md

@@ -4,6 +4,77 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-09-06
+
+First stable operational embedding release. It promotes the two release candidates after package,
+provider and real-consumer compatibility validation; each host remains responsible for validating
+its own live adapters and policies.
+
+### Changed
+
+- Qualify OpenAI SDK 3.8 through the required live DeepSeek compatibility gate without calling the
+  OpenAI service, and update the locked Pyright version.
+- Upgrade the SHA-pinned uv and Pages actions after CI artifact round-trip and rendered Pages checks.
+- Validate Vibemonitor's real `KernelGate` integration and complete consumer suite on Python 3.14.
+
+## [0.5.0rc2] - 2026-09-06
+
+Maintenance candidate following the first published operational release. Publication remains
+separate from live host-adapter acceptance.
+
+### Added
+
+- SQLite audit discovery for reserved run IDs and runs needing operator review after incomplete or
+  uncertain execution.
+
+### Changed
+
+- Validate the provider adapters against OpenAI SDK 3.7 and Anthropic SDK 1.4, while bounding their
+  optional dependency ranges below the next untested major versions.
+- Upgrade SHA-pinned GitHub Actions and add a CI upload/download checksum round trip for release
+  artifacts; group future Actions updates into one Dependabot pull request.
+- Refresh the locked Pydantic, pytest and ruff versions used by CI and local development.
+
+### Fixed
+
+- Package builds clear stale distributions, while published-artifact verification ignores unrelated
+  files and still requires exactly one wheel and one source distribution.
+
+## [0.5.0rc1] - 2026-09-06
+
+Published operational embedding candidate. Publication does not imply live-adapter UAT.
+
+### Added
+
+- Single-use `RunSession`, bounded operational defaults and root-wide step/tool/parser/LLM budgets.
+- Explicit tool egress declarations, normalized input verification and output model revalidation.
+- `TraceSink`, memory/SQLite sinks, durable pre-call records and fail-closed storage handling.
+- Correlated invocation IDs, parent run IDs, partial/uncertain effect outcomes and terminal run status.
+- Redacted operational events, detached snapshots and canonical detailed digests.
+- Bounded shared reasoner executor, returned usage/latency capture and public provider result types.
+- Sanitized provider failure categories, HTTP status and allow-listed operational error codes.
+- Crash, concurrency, shared-budget, adapter-contract and provider failure regression tests.
+- Python 3.14 CI, locked dependencies, pinned actions and single-artifact release promotion with
+  a pinned/checksummed uv runtime, version checks, isolated wheel smoke and served-byte verification.
+- Operational/migration guide and conformance checklist.
+
+### Changed
+
+- Require a patched `pydantic-settings>=2.14.2` (GHSA-4xgf-cpjx-pc3j) and refresh its lock entry.
+- Version the SQLite audit schema, migrate the unversioned candidate layout, reject unknown/newer
+  layouts or missing key constraints, and verify released bytes after TestPyPI and PyPI publication.
+- Require an explicit live-provider set in release CI; `0.5.0rc1` qualifies DeepSeek while OpenAI
+  remains supported but is not live-qualified for this candidate.
+- Low-level interpreters reject reuse and context/trace mismatches; child IDs are opaque.
+- Limits span descendants; `RunLimits()` remains unbounded for explicit low-level wiring.
+- Failed tools stop later steps without implying rollback; output validation cannot undo a call.
+- OpenAI-compatible fallback uses structured error parameters, once; refusals/truncations and
+  malformed outputs are terminal errors. DeepSeek routes directly through JSON mode with local
+  schema validation because its compatible API does not implement OpenAI's native JSON Schema mode.
+  Provider exception messages no longer include raw API text.
+- Pyright explicitly resolves the project virtualenv. Documentation distinguishes root planning,
+  delegated untrusted planning and partial effects.
+
 ## [0.4.2] - 2026-07-10
 
 A correctness release for the gate's provenance stage, plus fail-closed hardening of the provider
@@ -143,6 +214,9 @@ Initial reference implementation of the Reasoning Kernel pattern (strong / CaMeL
 invariants, no-effect-bypasses-the-Verifier by construction, the deterministic declassification seam,
 and the worked email-exfiltration demo.
 
+[0.5.0]: https://github.com/gianlucamazza/reasoning-kernel/releases/tag/v0.5.0
+[0.5.0rc2]: https://github.com/gianlucamazza/reasoning-kernel/releases/tag/v0.5.0rc2
+[0.5.0rc1]: https://github.com/gianlucamazza/reasoning-kernel/releases/tag/v0.5.0rc1
 [0.4.2]: https://github.com/gianlucamazza/reasoning-kernel/releases/tag/v0.4.2
 [0.4.1]: https://github.com/gianlucamazza/reasoning-kernel/releases/tag/v0.4.1
 [0.4.0]: https://github.com/gianlucamazza/reasoning-kernel/releases/tag/v0.4.0

{capability_reasoning_kernel-0.4.2 → capability_reasoning_kernel-0.5.0}/PKG-INFO

@@ -1,10 +1,12 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: capability-reasoning-kernel
-Version: 0.4.2
+Version: 0.5.0
 Summary: Reference implementation of the Reasoning Kernel pattern (strong / CaMeL-like form)
 Project-URL: Homepage, https://github.com/gianlucamazza/reasoning-kernel
 Project-URL: Repository, https://github.com/gianlucamazza/reasoning-kernel
 Project-URL: Issues, https://github.com/gianlucamazza/reasoning-kernel/issues
+Project-URL: Documentation, https://github.com/gianlucamazza/reasoning-kernel/blob/main/docs/OPERATIONS.md
+Project-URL: Changelog, https://github.com/gianlucamazza/reasoning-kernel/blob/main/CHANGELOG.md
 Author: Gianluca Mazza — Venere Labs
 License: MIT
 License-File: LICENSE
@@ -15,19 +17,24 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Security
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic-settings>=2.14.2
 Requires-Dist: pydantic>=2.7
 Provides-Extra: dev
+Requires-Dist: anthropic<2,>=0.40; extra == 'dev'
+Requires-Dist: httpx2<3,>=2.12; extra == 'dev'
+Requires-Dist: openai<4,>=1.50; extra == 'dev'
 Requires-Dist: pyright>=1.1.380; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.9; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
 Provides-Extra: providers
-Requires-Dist: anthropic>=0.40; extra == 'providers'
-Requires-Dist: openai>=1.50; extra == 'providers'
+Requires-Dist: anthropic<2,>=0.40; extra == 'providers'
+Requires-Dist: openai<4,>=1.50; extra == 'providers'
 Description-Content-Type: text/markdown
 
 # Reasoning Kernel
@@ -67,8 +74,9 @@ It is a reference implementation, **not** a turn-key security product.
 The pattern guarantees a **topology, not a property**: it fixes *where* mediation and verification
 live, by construction; it does not guarantee any particular policy is safe. Conformance is a
 *necessary*, not a *sufficient*, condition. Concretely: no matter what an injected message says, it can
-never reach the planner nor fire a tool without passing your Gate — that boundary holds by
-construction; whether your Gate's *policy* is correct is on you.
+cannot fire a tool without passing your Gate. The root planner is isolated from tool results;
+delegated sub-planners deliberately see untrusted data under reduced grants. Whether your Gate's
+*policy* is correct is on you.
 
 ## Strong form: no trusted reasoner
 
@@ -96,19 +104,19 @@ The trusted, deterministic kernel is the **interpreter + capability/provenance g
 
 Reasoner providers: Anthropic, OpenAI, Deepseek (OpenAI-compatible, reusing the `openai` SDK via a
 `base_url` — no separate dependency), plus a deterministic `FakeProvider` for key-free tests — all
-behind one interface (`reasoner/base.py`). The fungibility corollary is validated live: OpenAI and
-Deepseek return schema-valid `Plan`s through the same interface (`just test-live`); Anthropic is
-exercised on demand when its key is set.
+behind one interface (`reasoner/base.py`). Configured providers can be exercised through the same
+live contract (`just test-live`). The 0.5 release workflow requires DeepSeek qualification; OpenAI
+and Anthropic remain independently contract-tested unless a release explicitly qualifies them live.
 
 ## No effect bypasses the Verifier — by construction
 
 1. Tool callables live only in `ToolRegistry`, handed only to `EffectDispatcher`; the interpreter
    never holds one.
-2. `EffectDispatcher` cannot be constructed without a `Gate`, and `dispatch` checks it
+2. `EffectDispatcher` cannot be constructed without a `Gate`, and `dispatch` authorizes the call
    unconditionally before the callable runs.
 3. `ToolCallStep` is the only step kind that invokes a tool callable, and its only handler routes
    through the dispatcher. The other step kinds (`const`, `q_parse`, `subkernel`, `merge`) produce
-   values, never external effects.
+   values; a sub-kernel may invoke tools through its reduced Gate and the same dispatcher path.
 
 ## What a run looks like
 
@@ -136,9 +144,9 @@ just demo-limits        # termination: RunLimits aborts the run closed before th
 just demo-reasoner-error # fail-closed: a failing reasoner commits nothing (plan_rejected)
 just demo-merge      # MergeStep: combine several reads into one value; taint flows through the join
 
-uv sync --all-extras           # adds the provider SDKs for the live flows below
+uv sync --all-extras           # explicit provider extra (dev also includes SDKs for mock tests)
 just demo-live   # end-to-end with a REAL planner/parser (needs a key in .env)
-just test-live   # optional: real Anthropic/OpenAI/Deepseek round-trips (needs API keys)
+just test-live   # configured real-provider round-trips; RK_LIVE_PROVIDERS makes a set mandatory
 ```
 
 See [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) for the quality bar (coverage gate, strict typing,
@@ -149,9 +157,15 @@ pre-commit) and how to configure provider keys. Release notes are in
 
 Install: `pip install capability-reasoning-kernel` — it **imports as** `import reasoning_kernel`
 (the PyPI name differs because `reasoning-kernel` was taken by an unrelated project).
+Install the operational release explicitly with
+`pip install capability-reasoning-kernel==0.5.0`.
 
-There is no facade: you wire the parts explicitly, which is the point — every trusted seam is visible.
-The package root re-exports the building blocks. Sketch (see
+For operational embedding, use `RunSession` with a persistent sink and bounded defaults; see
+[operations and migration](docs/OPERATIONS.md) and the [conformance checklist](docs/CONFORMANCE.md).
+It isolates each run, records partial effects and refuses automatic replay. Package publication and
+consumer compatibility tests are not evidence that a host's live adapters are correctly configured.
+
+Explicit low-level wiring remains available. The package root re-exports the building blocks. Sketch (see
 [`demo/email_exfil.py`](src/reasoning_kernel/demo/email_exfil.py) for a complete, runnable version):
 
 ```python
@@ -205,9 +219,8 @@ result = kernel.run(ctx)             # RunResult(trace, committed); committed is
 - **Reasoner failure is fail-closed**: a provider that returns no usable output (empty / refused /
   malformed) raises `ReasonerError` (`reasoner/base.py`), and a provider call that fails in transport
   (rate limit exhausted, 5xx, network fault) raises its `TransportError` subclass; either way the
-  Conductor records a terminal trace event and commits nothing, rather than crashing or acting on a
-  partial result. Treating the model as untrusted compute
-  means a flaky reasoner can never produce a half-applied effect.
+  Conductor records a terminal trace event and stops subsequent work. Earlier effects remain real
+  and are reported in `RunResult.effects`; `committed=None` means no final value, not rollback.
 - **Capability composition (§5.4)**: every reasoner is bound to a `CapabilitySet`; the kernel rejects a
   reasoner whose grant exceeds the dispatcher's — a child can never widen authority. A `SubKernelStep`
   delegates untrusted content to an inner kernel at a **clamped, reduced grant**: an injection in that
@@ -216,9 +229,9 @@ result = kernel.run(ctx)             # RunResult(trace, committed); committed is
 - **Static, data-independent control flow**: a `Plan` is a forward-only DAG of five step kinds
   (`const`, `tool`, `q_parse`, `subkernel`, `merge`), executed linearly by `kernel/interpreter.py`; a
   `QuarantineParseStep`'s target schema is fixed at plan time
-  (`schema_ref`), never chosen on the quarantined value. No branch, loop, or tool selection is
-  conditioned on untrusted content — so control-flow leaks of quarantined data are precluded by
-  construction, not by policy (the matching cost is in *Honest limits*).
+  (`schema_ref`), never chosen on the quarantined value. There are no runtime branches or loops.
+  Delegated sub-planners can choose a child plan based on untrusted input; its authority and literal
+  provenance are reduced accordingly. This is not a claim of data-independent planning across delegation.
 
 ## Honest limits (fundamental — localized, not dissolved)
 
@@ -256,7 +269,7 @@ result = kernel.run(ctx)             # RunResult(trace, committed); committed is
 - **Join** — combining values combines their labels conservatively (union of sources, intersection of
   readers, union of subjects), so taint only ever increases.
 - **Quarantine** — routing untrusted content through the Q-LLM, which cannot launder its taint.
-- **Capability / grant** — an unforgeable permission a tool requires; a run holds a fixed
+- **Capability / grant** — a host-issued permission a tool requires; a run holds a fixed
   `CapabilitySet` (its *grant*), and a sub-kernel's grant can only ever shrink.
 - **Declassifier (`DeclassPolicy`)** — the single deterministic seam that may let tainted data into a
   WRITE; the one place trust is deliberately relaxed.

{capability_reasoning_kernel-0.4.2 → capability_reasoning_kernel-0.5.0}/README.md

@@ -35,8 +35,9 @@ It is a reference implementation, **not** a turn-key security product.
 The pattern guarantees a **topology, not a property**: it fixes *where* mediation and verification
 live, by construction; it does not guarantee any particular policy is safe. Conformance is a
 *necessary*, not a *sufficient*, condition. Concretely: no matter what an injected message says, it can
-never reach the planner nor fire a tool without passing your Gate — that boundary holds by
-construction; whether your Gate's *policy* is correct is on you.
+cannot fire a tool without passing your Gate. The root planner is isolated from tool results;
+delegated sub-planners deliberately see untrusted data under reduced grants. Whether your Gate's
+*policy* is correct is on you.
 
 ## Strong form: no trusted reasoner
 
@@ -64,19 +65,19 @@ The trusted, deterministic kernel is the **interpreter + capability/provenance g
 
 Reasoner providers: Anthropic, OpenAI, Deepseek (OpenAI-compatible, reusing the `openai` SDK via a
 `base_url` — no separate dependency), plus a deterministic `FakeProvider` for key-free tests — all
-behind one interface (`reasoner/base.py`). The fungibility corollary is validated live: OpenAI and
-Deepseek return schema-valid `Plan`s through the same interface (`just test-live`); Anthropic is
-exercised on demand when its key is set.
+behind one interface (`reasoner/base.py`). Configured providers can be exercised through the same
+live contract (`just test-live`). The 0.5 release workflow requires DeepSeek qualification; OpenAI
+and Anthropic remain independently contract-tested unless a release explicitly qualifies them live.
 
 ## No effect bypasses the Verifier — by construction
 
 1. Tool callables live only in `ToolRegistry`, handed only to `EffectDispatcher`; the interpreter
    never holds one.
-2. `EffectDispatcher` cannot be constructed without a `Gate`, and `dispatch` checks it
+2. `EffectDispatcher` cannot be constructed without a `Gate`, and `dispatch` authorizes the call
    unconditionally before the callable runs.
 3. `ToolCallStep` is the only step kind that invokes a tool callable, and its only handler routes
    through the dispatcher. The other step kinds (`const`, `q_parse`, `subkernel`, `merge`) produce
-   values, never external effects.
+   values; a sub-kernel may invoke tools through its reduced Gate and the same dispatcher path.
 
 ## What a run looks like
 
@@ -104,9 +105,9 @@ just demo-limits        # termination: RunLimits aborts the run closed before th
 just demo-reasoner-error # fail-closed: a failing reasoner commits nothing (plan_rejected)
 just demo-merge      # MergeStep: combine several reads into one value; taint flows through the join
 
-uv sync --all-extras           # adds the provider SDKs for the live flows below
+uv sync --all-extras           # explicit provider extra (dev also includes SDKs for mock tests)
 just demo-live   # end-to-end with a REAL planner/parser (needs a key in .env)
-just test-live   # optional: real Anthropic/OpenAI/Deepseek round-trips (needs API keys)
+just test-live   # configured real-provider round-trips; RK_LIVE_PROVIDERS makes a set mandatory
 ```
 
 See [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) for the quality bar (coverage gate, strict typing,
@@ -117,9 +118,15 @@ pre-commit) and how to configure provider keys. Release notes are in
 
 Install: `pip install capability-reasoning-kernel` — it **imports as** `import reasoning_kernel`
 (the PyPI name differs because `reasoning-kernel` was taken by an unrelated project).
+Install the operational release explicitly with
+`pip install capability-reasoning-kernel==0.5.0`.
 
-There is no facade: you wire the parts explicitly, which is the point — every trusted seam is visible.
-The package root re-exports the building blocks. Sketch (see
+For operational embedding, use `RunSession` with a persistent sink and bounded defaults; see
+[operations and migration](docs/OPERATIONS.md) and the [conformance checklist](docs/CONFORMANCE.md).
+It isolates each run, records partial effects and refuses automatic replay. Package publication and
+consumer compatibility tests are not evidence that a host's live adapters are correctly configured.
+
+Explicit low-level wiring remains available. The package root re-exports the building blocks. Sketch (see
 [`demo/email_exfil.py`](src/reasoning_kernel/demo/email_exfil.py) for a complete, runnable version):
 
 ```python
@@ -173,9 +180,8 @@ result = kernel.run(ctx)             # RunResult(trace, committed); committed is
 - **Reasoner failure is fail-closed**: a provider that returns no usable output (empty / refused /
   malformed) raises `ReasonerError` (`reasoner/base.py`), and a provider call that fails in transport
   (rate limit exhausted, 5xx, network fault) raises its `TransportError` subclass; either way the
-  Conductor records a terminal trace event and commits nothing, rather than crashing or acting on a
-  partial result. Treating the model as untrusted compute
-  means a flaky reasoner can never produce a half-applied effect.
+  Conductor records a terminal trace event and stops subsequent work. Earlier effects remain real
+  and are reported in `RunResult.effects`; `committed=None` means no final value, not rollback.
 - **Capability composition (§5.4)**: every reasoner is bound to a `CapabilitySet`; the kernel rejects a
   reasoner whose grant exceeds the dispatcher's — a child can never widen authority. A `SubKernelStep`
   delegates untrusted content to an inner kernel at a **clamped, reduced grant**: an injection in that
@@ -184,9 +190,9 @@ result = kernel.run(ctx)             # RunResult(trace, committed); committed is
 - **Static, data-independent control flow**: a `Plan` is a forward-only DAG of five step kinds
   (`const`, `tool`, `q_parse`, `subkernel`, `merge`), executed linearly by `kernel/interpreter.py`; a
   `QuarantineParseStep`'s target schema is fixed at plan time
-  (`schema_ref`), never chosen on the quarantined value. No branch, loop, or tool selection is
-  conditioned on untrusted content — so control-flow leaks of quarantined data are precluded by
-  construction, not by policy (the matching cost is in *Honest limits*).
+  (`schema_ref`), never chosen on the quarantined value. There are no runtime branches or loops.
+  Delegated sub-planners can choose a child plan based on untrusted input; its authority and literal
+  provenance are reduced accordingly. This is not a claim of data-independent planning across delegation.
 
 ## Honest limits (fundamental — localized, not dissolved)
 
@@ -224,7 +230,7 @@ result = kernel.run(ctx)             # RunResult(trace, committed); committed is
 - **Join** — combining values combines their labels conservatively (union of sources, intersection of
   readers, union of subjects), so taint only ever increases.
 - **Quarantine** — routing untrusted content through the Q-LLM, which cannot launder its taint.
-- **Capability / grant** — an unforgeable permission a tool requires; a run holds a fixed
+- **Capability / grant** — a host-issued permission a tool requires; a run holds a fixed
   `CapabilitySet` (its *grant*), and a sub-kernel's grant can only ever shrink.
 - **Declassifier (`DeclassPolicy`)** — the single deterministic seam that may let tainted data into a
   WRITE; the one place trust is deliberately relaxed.