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

{capability_reasoning_kernel-0.4.1 → capability_reasoning_kernel-0.4.2}/.env.example

@@ -7,7 +7,9 @@ DEEPSEEK_API_KEY=
 
 # Optional overrides (defaults shown)
 # RK_LLM_PROVIDER_DEFAULT=anthropic
-# RK_LLM_MODEL_ANTHROPIC=claude-sonnet-4-6   # or claude-opus-4-8 (more capable, different pricing)
+# RK_LLM_MODEL_ANTHROPIC=claude-sonnet-5      # or claude-opus-4-8 (more capable, different pricing)
 # RK_LLM_MODEL_OPENAI=gpt-5.5                 # or gpt-5.5-pro (more capable, different pricing)
 # RK_LLM_MODEL_DEEPSEEK=deepseek-v4-flash     # or deepseek-v4-pro (more capable, different pricing)
 # RK_DEEPSEEK_BASE_URL=https://api.deepseek.com
+# RK_LLM_TIMEOUT_SECONDS=120.0                # per-request SDK timeout passed to provider clients
+# RK_LLM_MAX_TOKENS=4096                      # default max_tokens for structured-output calls

capability_reasoning_kernel-0.4.2/.github/workflows/pages.yml

@@ -0,0 +1,48 @@
+name: Pages
+
+# Deploy the static landing page in `docs/` to GitHub Pages. No build step — the page is
+# self-contained HTML (CSS + SVG inline). First-time setup requires the repository's
+# Settings → Pages → Source to be set to "GitHub Actions".
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; don't cancel an in-progress publish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      # Actions pinned to immutable commit SHAs (supply-chain hardening); tag in comment.
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
+
+      - name: Configure Pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
+        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
+        with:
+          path: docs
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

capability_reasoning_kernel-0.4.2/.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=1000"]
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  # Ruff and pyright run as local hooks through uv so the hook, `just lint`/`just typecheck`,
+  # and CI all execute the exact versions pinned in uv.lock — no pinned-mirror drift.
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check --fix (uv.lock version, same as `just fix`)
+        language: system
+        entry: uv run ruff check --fix src/ tests/
+        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/
+        pass_filenames: false
+        types_or: [python, pyi]
+      - id: pyright
+        name: pyright (same scope as `just typecheck` — strict dirs set in pyproject)
+        language: system
+        entry: uv run pyright
+        pass_filenames: false
+        types: [python]

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

@@ -4,6 +4,54 @@ 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.4.2] - 2026-07-10
+
+A correctness release for the gate's provenance stage, plus fail-closed hardening of the provider
+integrations. No API removals; two behavior changes in the gate/taint semantics (both strictly
+safety-improving) and stricter model resolution.
+
+### Fixed
+
+- **Gate: a tainted value with unrestricted `readers` no longer skips declassification.**
+  `readers=None` is reserved for purely trusted data, but `quarantine_label` preserves the source's
+  readers — so a Q-LLM parse of a *trusted* const yielded a value that was tainted (Q_LLM) yet
+  carried `readers=None`, and the gate's stage 3 auto-permitted it into a WRITE without consulting
+  the declassification policy. The fast-path now requires an **explicit** readers set covering the
+  tool's required capabilities; unscoped tainted flows go through the declassifier. (Regression
+  tests at gate level and end-to-end: a recipient laundered through the Q-LLM is now blocked by the
+  policy instead of auto-committed.)
+- **Taint: `DERIVED` is no longer counted as an untrusted source.** Merging values derived solely
+  from the trusted query no longer manufactures taint (which caused spurious denials in policies
+  keyed on `is_tainted`); taint derives only from the actual presence of `TOOL_READ` / `Q_LLM` in
+  the joined sources. `DERIVED` remains on the label as an audit marker. The two fixes land
+  together deliberately: each previously masked the other.
+- **`RK_LLM_MAX_TOKENS` now has an effect.** `call_structured` / `parse_with_schema` defaulted to a
+  private module constant, silently ignoring the `settings.llm_max_tokens` override; they now read
+  settings (lazily) as the single source of truth.
+
+### Changed
+
+- **Transport faults fail closed with an audit record.** Provider API errors (rate limit exhausted,
+  5xx, network, SDK timeout) are wrapped in a new `TransportError(ReasonerError)` by the Anthropic
+  and OpenAI/Deepseek providers, so an in-flight run ends with a terminal trace event
+  (`PlanRejected`/`RunErrored`) instead of an unrecorded traceback.
+- **Model resolution is strict and construction-time.** `PLLM`/`QLLM` no longer default to
+  `model="fake"` (a real provider without an explicit model got a 404 deep inside a run); an
+  omitted model resolves via `default_model_for(provider.name)` at construction. `default_model_for`
+  now raises `ValueError` for unknown providers instead of silently falling back to the Anthropic
+  model, and maps `"fake"` to the FakeProvider's ignored sentinel. `call_structured` requires
+  `model=` explicitly.
+- **Anthropic default model refreshed**: `claude-sonnet-4-6` → `claude-sonnet-5` (comment variant
+  stays `claude-opus-4-8`); `.env.example` and `docs/DEVELOPMENT.md` updated, including the
+  previously undocumented `RK_LLM_TIMEOUT_SECONDS` / `RK_LLM_MAX_TOKENS` overrides.
+- **Branch coverage enabled** (`coverage: branch = true`): line coverage alone hid the gate's
+  untested readers fast-path; the new gate tests pin both directions of that branch.
+- **Toolchain drift eliminated.** pre-commit now runs ruff and pyright as local hooks through
+  `uv run` (same versions as `uv.lock`, same scope as `just lint`/`just typecheck` and CI, instead
+  of a stale pinned ruff mirror and a partial pyright scope); a new aggregate `just check` runs
+  lint + typecheck + test exactly as CI does. `CLAUDE.md` and the README role map now include
+  `tools/` (the registry is part of the no-bypass argument).
+
 ## [0.4.1] - 2026-05-31
 
 ### Changed
@@ -95,6 +143,7 @@ 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.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
 [0.3.0]: https://github.com/gianlucamazza/reasoning-kernel/releases/tag/v0.3.0

capability_reasoning_kernel-0.4.2/CLAUDE.md

@@ -0,0 +1,35 @@
+# CLAUDE.md — reasoning-kernel
+
+Framework-agnostic Python **reference implementation** of the Reasoning Kernel pattern (strong,
+CaMeL-like form; Debenedetti et al. 2025): the LLM is treated as untrusted compute, mediated by
+context on input and verification on output. Published to PyPI as `capability-reasoning-kernel`.
+Remote: `gianlucamazza/reasoning-kernel`.
+
+## The two invariants (do not violate)
+- **A** — the reasoner never sees raw reality: every model call gets a system-assembled, inspectable
+  context (`src/reasoning_kernel/context/`).
+- **B** — the reasoner never commits reality: no model output becomes a durable effect except through
+  the single deterministic gate (`src/reasoning_kernel/kernel/gate.py`).
+
+The pattern fixes a *topology*, not a policy guarantee — keep mediation/verification at those
+boundaries by construction.
+
+## Stack & layout
+- Python, `uv` (uv.lock), `pyproject.toml`, `just`. Lint Ruff, types pyright.
+- `src/reasoning_kernel/`: `context/` · `kernel/` (gate) · `reasoner/` · `memory/` · `schemas/` ·
+  `tools/` (registry — sole holder of tool callables, part of the no-bypass argument) · `demo/`
+
+## Commands
+```bash
+just check       # lint + typecheck + test (everything CI runs)
+just lint        # ruff
+just fix         # ruff --fix
+just typecheck   # pyright
+just test-live   # tests against live model
+just demo        # run demo (also: demo-live, demo-subkernel, demo-limits, demo-merge, demo-reasoner-error)
+uv sync          # install/refresh env (--all-extras for providers + dev tools)
+```
+
+## Conventions
+- It's a reference impl + spec, not a turn-key product — favor clarity and conformance over features.
+- Changes touching invariants A/B must preserve the topology; update `docs/` and the README spec.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capability-reasoning-kernel
-Version: 0.4.1
+Version: 0.4.2
 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
@@ -32,6 +32,15 @@ Description-Content-Type: text/markdown
 
 # Reasoning Kernel
 
+[![PyPI](https://img.shields.io/pypi/v/capability-reasoning-kernel)](https://pypi.org/project/capability-reasoning-kernel/)
+[![Python](https://img.shields.io/pypi/pyversions/capability-reasoning-kernel)](https://pypi.org/project/capability-reasoning-kernel/)
+[![CI](https://github.com/gianlucamazza/reasoning-kernel/actions/workflows/ci.yml/badge.svg)](https://github.com/gianlucamazza/reasoning-kernel/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/gianlucamazza/reasoning-kernel)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
+
+**[Live site →](https://gianlucamazza.github.io/reasoning-kernel/)**
+
 **The problem.** An LLM agent that reads untrusted data — an email, a web page, a tool result — can be
 hijacked by instructions hidden in that data and then act on them: leak your contacts, send mail, call
 tools on your behalf. This is a reference implementation of an architecture where such a hijack
@@ -82,6 +91,7 @@ The trusted, deterministic kernel is the **interpreter + capability/provenance g
 | Reasoner(s)    | `reasoner/` (multi-provider)    | a provider or the interface     |
 | Conductor      | `kernel/interpreter.py`         | the execution loop              |
 | Verifier       | `kernel/gate.py`, `effects.py`  | verification policy             |
+| Tool catalog   | `tools/registry.py`             | sole holder of tool callables   |
 | Memory / Trace | `memory/`                       | durability / audit format       |
 
 Reasoner providers: Anthropic, OpenAI, Deepseek (OpenAI-compatible, reusing the `openai` SDK via a
@@ -184,15 +194,19 @@ result = kernel.run(ctx)             # RunResult(trace, committed); committed is
 
 - **Provenance is multi-dimensional**: a `ProvenanceLabel` carries *origin* (`sources`), *where it may
   flow* (`readers`), and *whose data it is* (`subjects`). Third-party data is never auto-released into a
-  WRITE — even to the requesting user — and the Q-LLM cannot launder any of these dimensions.
+  WRITE — even to the requesting user — and the Q-LLM cannot launder any of these dimensions. A tainted
+  value whose flow was never scoped (`readers=None` is reserved for purely trusted data) is likewise
+  never auto-permitted into a WRITE: it is routed to the declassifier like any other tainted flow.
 - **Invariant A is typed**: the trusted channel is a `TrustedQuery` (text + label); `const`/inline
   literals DERIVE their label from it, so the trust assumption is explicit rather than by convention.
 - **Termination**: `RunLimits` bounds steps / effects / q-parses (and an optional per-call timeout); a
   run exceeding a bound aborts closed (`RunAborted`), committing nothing further. The timeout abort is
   prompt — it does not block waiting on the hung call (`kernel/interpreter.py:_call_reasoner`).
 - **Reasoner failure is fail-closed**: a provider that returns no usable output (empty / refused /
-  malformed) raises `ReasonerError` (`reasoner/base.py`); the Conductor records it and commits
-  nothing, rather than crashing or acting on a partial result. Treating the model as untrusted compute
+  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.
 - **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`

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

@@ -1,5 +1,14 @@
 # Reasoning Kernel
 
+[![PyPI](https://img.shields.io/pypi/v/capability-reasoning-kernel)](https://pypi.org/project/capability-reasoning-kernel/)
+[![Python](https://img.shields.io/pypi/pyversions/capability-reasoning-kernel)](https://pypi.org/project/capability-reasoning-kernel/)
+[![CI](https://github.com/gianlucamazza/reasoning-kernel/actions/workflows/ci.yml/badge.svg)](https://github.com/gianlucamazza/reasoning-kernel/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/gianlucamazza/reasoning-kernel)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
+
+**[Live site →](https://gianlucamazza.github.io/reasoning-kernel/)**
+
 **The problem.** An LLM agent that reads untrusted data — an email, a web page, a tool result — can be
 hijacked by instructions hidden in that data and then act on them: leak your contacts, send mail, call
 tools on your behalf. This is a reference implementation of an architecture where such a hijack
@@ -50,6 +59,7 @@ The trusted, deterministic kernel is the **interpreter + capability/provenance g
 | Reasoner(s)    | `reasoner/` (multi-provider)    | a provider or the interface     |
 | Conductor      | `kernel/interpreter.py`         | the execution loop              |
 | Verifier       | `kernel/gate.py`, `effects.py`  | verification policy             |
+| Tool catalog   | `tools/registry.py`             | sole holder of tool callables   |
 | Memory / Trace | `memory/`                       | durability / audit format       |
 
 Reasoner providers: Anthropic, OpenAI, Deepseek (OpenAI-compatible, reusing the `openai` SDK via a
@@ -152,15 +162,19 @@ result = kernel.run(ctx)             # RunResult(trace, committed); committed is
 
 - **Provenance is multi-dimensional**: a `ProvenanceLabel` carries *origin* (`sources`), *where it may
   flow* (`readers`), and *whose data it is* (`subjects`). Third-party data is never auto-released into a
-  WRITE — even to the requesting user — and the Q-LLM cannot launder any of these dimensions.
+  WRITE — even to the requesting user — and the Q-LLM cannot launder any of these dimensions. A tainted
+  value whose flow was never scoped (`readers=None` is reserved for purely trusted data) is likewise
+  never auto-permitted into a WRITE: it is routed to the declassifier like any other tainted flow.
 - **Invariant A is typed**: the trusted channel is a `TrustedQuery` (text + label); `const`/inline
   literals DERIVE their label from it, so the trust assumption is explicit rather than by convention.
 - **Termination**: `RunLimits` bounds steps / effects / q-parses (and an optional per-call timeout); a
   run exceeding a bound aborts closed (`RunAborted`), committing nothing further. The timeout abort is
   prompt — it does not block waiting on the hung call (`kernel/interpreter.py:_call_reasoner`).
 - **Reasoner failure is fail-closed**: a provider that returns no usable output (empty / refused /
-  malformed) raises `ReasonerError` (`reasoner/base.py`); the Conductor records it and commits
-  nothing, rather than crashing or acting on a partial result. Treating the model as untrusted compute
+  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.
 - **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`

{capability_reasoning_kernel-0.4.1 → capability_reasoning_kernel-0.4.2}/SECURITY.md

@@ -34,8 +34,8 @@ permissive policy written on top of it.
 
 | Version | Supported |
 |---------|-----------|
-| `0.3.x` | ✅ |
-| `< 0.3` | ❌ |
+| `0.4.x` | ✅ |
+| `< 0.4` | ❌ |
 
 ## Reporting a vulnerability
 
@@ -47,4 +47,4 @@ Please report privately — do **not** open a public issue for a suspected vulne
 Include a minimal reproduction (a plan + tool/policy setup that commits an effect that should have been
 blocked), the expected vs. actual behavior, and the affected version/commit. Expect an initial
 acknowledgement within a few days. As a single-maintainer reference project there is no formal SLA, but
-mechanism-level issues are taken seriously and will be addressed in a `0.3.x` patch.
+mechanism-level issues are taken seriously and will be addressed in a `0.4.x` patch.

capability_reasoning_kernel-0.4.2/docs/ANALYSIS-2026-07.md

@@ -0,0 +1,246 @@
+# Analisi del progetto e piano di miglioramento — luglio 2026
+
+Analisi completa della codebase alla versione **0.4.1** (branch `main`, commit `0189752`),
+condotta su tre assi: core fidato (kernel/memory/context), livello di integrazione LLM
+(reasoner/config/tools), e qualità/DevEx (test, CI, packaging, documentazione).
+
+## Stato di avanzamento (aggiornato 2026-07-10)
+
+**✅ Tranche 1 (0.4.2) — completata su questo branch.** Corretti e testati: A1 (gate:
+`readers=None` tainted → declassificazione, con regressione end-to-end), M1 (`DERIVED` fuori
+da `_UNTRUSTED`), fast-path del gate testato + branch coverage attiva, `RK_LLM_MAX_TOKENS`
+cablato, `model` risolto strettamente alla costruzione dei ruoli (`default_model_for` rifiuta
+provider ignoti), `TransportError` per i guasti di trasporto Anthropic/OpenAI/Deepseek
+(esportato dall'API pubblica), test `AnthropicProvider`, default `claude-sonnet-5`,
+CHANGELOG/README/DEVELOPMENT aggiornati. Suite: 111 test, coverage ~94% (branch).
+
+**✅ Consolidamento drift (stesso branch):** pre-commit riallineato a justfile/CI (ruff e
+pyright come hook local via `uv run`, stessa versione di uv.lock e stesso scope di
+`just typecheck`), target aggregato `just check`, `tools/` aggiunto al layout di CLAUDE.md e
+alla role map del README.
+
+> Nota: il passaggio a `uv sync --all-extras --locked` in `.github/workflows/ci.yml` (entrambi
+> i job) è pronto ma NON è su questo branch: il token dell'app GitHub non ha il permesso
+> `workflows`, quindi va applicato manualmente insieme agli altri interventi CI aperti.
+
+**⬜ Ancora aperti:** tranche 0.5.0 (RunLimits globali sui sub-kernel — M3/1.3,
+`ToolExecutionError` + evento di trace, fallback strict-schema robusto — 1.1, trace writer
+per-run — M4, export `LLMResult`/`LLMUsage` — 3.1), infra release (build unica promossa +
+gate di test/versione — 2.1/2.2, dependabot — 2.3, pinning SHA — 2.4, matrice 3.14 — 2.7,
+`permissions` in ci.yml — 2.5, `uv build` + `twine check` — 2.9), spec/docs (semantica limits
+— 4.3, regola "argomenti che escono ⇒ WRITE" — M2, CONFORMANCE.md — 4.4, metadati pyproject
+— §3), e i P2 restanti (hardening prompt, test minori, audit trace).
+
+## Stato di salute (baseline verificata)
+
+| Check | Esito |
+|---|---|
+| `ruff check` + `ruff format --check` | pulito (67 file) |
+| `pyright` (strict su schemas/kernel/memory) | 0 errori |
+| `pytest` (suite non-live) | 98 passed |
+| Coverage | 92.19% (soglia 85% applicata in CI) |
+
+L'architettura di sicurezza regge: nessun bypass strutturale del gate (il registry è
+l'unico detentore dei callable, il dispatcher chiama `Gate.check` incondizionatamente),
+validazione del Plan solida (id unici, ref forward-only, niente cicli), clamp monotono dei
+grant nei sub-kernel, join delle label monotono. I finding sotto riguardano punti specifici,
+non la topologia del pattern.
+
+---
+
+## P0 — Correttezza del gate (invariante B)
+
+### A1. Valore tainted con `readers=None` salta la declassificazione ⚠️
+
+`kernel/gate.py:71-77` + `kernel/taint.py:58-68` + `schemas/provenance.py:43,54-58`
+
+`provenance.py` documenta `readers=None` = "unrestricted, **reserved for purely trusted
+data**", ma `quarantine_label()` preserva i `readers` della sorgente: un `q_parse` su un
+const trusted produce un valore **tainted (Q_LLM) con `readers=None`**. Nello stage 3 del
+gate, `allows_reader()` restituisce `True` quando `readers is None` → `permitted=True`,
+la declassificazione viene saltata.
+
+Scenario: piano con `const → q_parse(const) → send_email(to=ref(q_parse))`. L'output del
+Q-LLM (compute probabilistico non fidato, per spec "verification never depends on trusting
+a probabilistic component") diventa argomento di una WRITE senza alcun vincolo
+deterministico oltre lo schema.
+
+**Fix (minimale, fail-closed):** in `gate.check`, per gli argomenti tainted trattare
+`readers is None` come *non* auto-permesso e instradare a declassificazione. In alternativa
+(più invasivo) non produrre mai label tainted con `readers=None` in `quarantine_label` /
+`result_label`.
+
+### M1. `DERIVED` è considerato untrusted: il merge di soli valori trusted diventa tainted
+
+`schemas/provenance.py:34` + `kernel/taint.py:30-31`
+
+`_UNTRUSTED = {TOOL_READ, Q_LLM, DERIVED}` e `join_labels` aggiunge `DERIVED` a ogni join
+con >1 input: `merge(const, const)` risulta tainted anche se tutti gli input derivano dalla
+query trusted → denial spuri nelle policy che usano `is_tainted`.
+
+**Fix:** togliere `DERIVED` da `_UNTRUSTED`; il taint deve derivare solo dalla presenza
+effettiva di `TOOL_READ`/`Q_LLM`. `DERIVED` resta come marcatore di audit.
+
+> **A1 e M1 vanno corretti insieme**: oggi si mascherano a vicenda (il merge over-taintato
+> passa comunque grazie al buco readers=None; chiudere solo A1 bloccherebbe i merge di dati
+> trusted).
+
+### Test mancante sul fast-path del gate
+
+`tests/` + `gate.py:71-78` — il ramo "readers permettono → niente declassificazione" nel
+caso positivo non ha alcun test, e la line coverage al 100% lo nasconde perché
+`branch = true` non è abilitato in `[tool.coverage.run]`. Aggiungere il test (arg tainted
+con readers che coprono le required_caps + declassificatore `DenyAll` mai consultato) e
+abilitare la branch coverage.
+
+---
+
+## P1 — Robustezza e semantica da definire
+
+### RunLimits per-interprete, non globali (amplificazione via sub-kernel)
+
+`kernel/interpreter.py:199-207` — ogni sub-kernel riceve gli stessi `limits` ma contatori
+azzerati: con fan-out di sub-kernel il totale di effetti scala ~`E·S^D`. Il sub-planner è
+per costruzione prompt-injectable, quindi un blob malevolo può moltiplicare i tentativi di
+effetto entro il grant. Né README né docstring dichiarano questa semantica.
+**Fix:** budget condiviso (contatori globali del run radice) passato ai sub-Interpreter;
+in ogni caso documentare la semantica scelta in `limits.py` e nel README, con un test che
+la pinna.
+
+### Errori di trasporto dei provider → trace senza evento terminale
+
+`kernel/interpreter.py:53` — `_PLAN_ERRORS` non copre `anthropic.APIError` /
+`openai.APIError` (429 esauriti, 5xx, timeout SDK): il traceback propaga e la trace
+(promessa come audit log completo) termina senza `RunErrored`/`RunAborted`.
+**Fix:** wrappare le eccezioni API in un `TransportError(ReasonerError)` nei provider.
+Stesso tema per i tool callable (`interpreter.py:126-127`): un `TypeError` nel callable
+propaga senza evento di trace — introdurre `ToolExecutionError` con evento dedicato.
+
+### Fallback JSON-mode basato su substring del messaggio d'errore
+
+`reasoner/openai.py:19-21` — `_is_strict_schema_error` fa match su `"response_format"` nel
+testo dell'eccezione: fragile in entrambe le direzioni (fallback che non scatta con
+messaggi diversi; 400 non correlati che innescano un secondo round-trip). È il meccanismo
+che regge `DeepseekProvider`.
+**Fix:** ispezionare i campi strutturati di `openai.BadRequestError` (`exc.param` /
+`exc.body`), o tentare il fallback una sola volta su qualunque `BadRequestError`
+ri-sollevando l'errore originale se fallisce anche quello.
+
+### `model="fake"` come default sui ruoli con provider reali
+
+`reasoner/roles.py:55,80` + `parse.py:23` — `PLLM(provider)` senza `model=` spedisce
+`model="fake"` all'API reale → 404 a runtime lontano dal punto d'errore.
+**Fix:** `model` keyword-only obbligatorio, o risoluzione automatica via
+`default_model_for(provider.name)`.
+
+### `RK_LLM_MAX_TOKENS` non ha alcun effetto
+
+`config.py:38` vs `reasoner/parse.py:14` — `llm_max_tokens` è definito in Settings ma
+`parse.py` usa una propria costante `DEFAULT_MAX_TOKENS = 4096`: l'override in `.env` è
+silenziosamente ignorato. **Fix:** far leggere `settings.llm_max_tokens` (import lazy) e
+rimuovere la costante. Collegato: `PLLM.plan()` non espone `max_tokens` e nessun provider
+controlla `finish_reason`/`stop_reason` == troncamento (errore criptico invece di
+`ReasonerError("output truncated")`).
+
+### Default modello Anthropic di una generazione indietro
+
+`config.py:32` + `.env.example:10` — `claude-sonnet-4-6` funziona ancora ma è superato:
+aggiornare a `claude-sonnet-5` (o `claude-opus-4-8`), allineando `.env.example`. Il beta
+header `structured-outputs-2025-11-13` in `anthropic.py:15,36` è ormai superfluo (feature
+GA) e può essere rimosso al prossimo bump dell'SDK.
+
+### Release workflow: artefatto non promosso e nessun gate
+
+`.github/workflows/release.yml` — i job `testpypi` e `pypi` fanno ciascuno `uv build`:
+l'artefatto pubblicato su PyPI non è quello validato su TestPyPI. Inoltre il publish parte
+sul tag senza rieseguire la suite né verificare tag ↔ `project.version`.
+**Fix:** job `build` unico + `upload/download-artifact`; step di verifica versione;
+job di test come `needs:` dei publish. (Trusted publishing e permessi sono già corretti.)
+
+### Stage provenance solo sulle WRITE: argomenti dei READ come canale di uscita
+
+`kernel/gate.py:62` — un tool READ con argomenti che lasciano il sistema (es.
+`web_fetch(url)`, `search(query)`) trasmetterebbe dati tainted senza controllo di
+provenance. Non sfruttabile oggi (i READ della demo non hanno argomenti), ma è un gap di
+spec per chi conforma il proprio sistema.
+**Fix minimo:** documentare in `capability.py` e nella spec che ogni tool i cui argomenti
+attraversano il confine DEVE essere registrato WRITE. Più robusto: flag
+`args_leave_boundary` su `ToolSpec`.
+
+---
+
+## P2 — Qualità, API, DevEx
+
+**API pubblica**
+- `LLMProvider` è esportato ma `LLMResult`/`LLMUsage` (necessari per implementarlo) no —
+  aggiungerli a `__all__` (`__init__.py`).
+- `supports_structured_output` dichiarato nel Protocol ma mai consultato: usarlo o rimuoverlo.
+- `default_model_for` (`factory.py:39`) fa fallback silenzioso al modello Anthropic per
+  provider ignoti — meglio errore esplicito.
+- Commento in `config.py:31` elenca `"fake"` tra i provider validi ma la factory lo rifiuta
+  (scelta intenzionale): allineare il commento.
+
+**Interpreter/trace (audit)**
+- `Interpreter`/`TraceWriter` non rientranti: un secondo `run()` mescola gli eventi del
+  primo (trace.py:13-23) — documentare one-shot o creare il writer per run.
+- `TraceEvent` non frozen + `snapshot()` shallow: lo "snapshot immutabile" non è
+  strutturale.
+- `digest()` basato su `repr()`: non deterministico per payload arbitrari — usare
+  serializzazione canonica.
+- `RunId(f"{ctx.run_id}/{step.id}")` senza escaping: uno step id con `/` rende ambiguo il
+  trace — vietare `/` negli id del Plan.
+- `dispatch()` etichetta `produced_by="__effect__<tool>"` invece dello step id.
+- Ogni `_call_reasoner` crea un `ThreadPoolExecutor` (thread orfani cumulativi su timeout);
+  nessun timeout sui tool callable — riusare l'executor, valutare `tool_timeout_s`.
+
+**Hardening prompt (mitigato dall'architettura, ma a buon mercato)**
+- `context/assembler.py:61-66` e `interpreter.py:193`: il blob non fidato non è recintato —
+  delimitatori falsificabili (`# Extraction instruction:` contraffatto). Fix: tag sentinella
+  e istruzione ripetuta dopo il blob.
+- Il sub-planner vede il catalogo tool completo, non filtrato per grant ridotto
+  (`effects.py:55-61`): filtrare per `required_caps ⊆ grant`.
+
+**Test mancanti (oltre al fast-path P0)**
+- `AnthropicProvider` a coverage 0% nonostante l'injection seam esista già: replicare i
+  fake client di `test_reasoner_robustness.py`.
+- Timeout del Q-LLM mai esercitato (solo il planner): test con provider che si blocca su
+  `parse_blob` dopo un piano valido.
+- Literal inline in `ToolCallStep.args` con query tainted → send bloccato (variante di
+  `test_const_label_derives_from_query`).
+- Oracolo di `test_every_committed_effect_was_gated_first` confronta solo per nome tool:
+  contare le occorrenze.
+- `RunLimits` accetta valori negativi: `Field(ge=0)` + test.
+
+**CI / supply chain**
+- Aggiungere `.github/dependabot.yml` (ecosystem `github-actions` + `uv`).
+- Pinnare a SHA le action in `ci.yml` e soprattutto `release.yml` (pages.yml lo fa già).
+- `permissions: contents: read` in `ci.yml`; `uv sync --locked`; matrice Python + 3.14
+  (e classifier); step `uv build` + `twine check` nel job quality; `branch = true` nella
+  coverage.
+
+**DevEx / docs**
+- pre-commit: l'hook pyright copre solo `schemas kernel memory` mentre `just typecheck`
+  copre tutto `src/` — usare `uv run pyright`; il pin ruff `v0.9.0` diverge dal venv —
+  hook local `uv run ruff`.
+- justfile: aggiungere target aggregato `check: lint typecheck test`.
+- CLAUDE.md e la tabella "Role → module map" del README omettono `tools/` (che è parte
+  dell'argomento no-bypass).
+- `RK_LLM_MAX_TOKENS` e `RK_LLM_TIMEOUT_SECONDS` assenti da DEVELOPMENT.md/.env.example.
+- Valutare `docs/CONFORMANCE.md`: checklist verificabile per il claim "conform your own
+  system to it" (oggi la spec vive tutta nel README).
+- pyproject: URL `Changelog`/`Documentation`, migrazione licenza a PEP 639, classifier 3.14.
+
+---
+
+## Roadmap proposta
+
+1. **0.4.2 (patch, subito):** A1 + M1 con test dedicati (fix congiunto), branch coverage,
+   fix `RK_LLM_MAX_TOKENS`, `model` obbligatorio sui ruoli, `TransportError`, test
+   AnthropicProvider, default `claude-sonnet-5`.
+2. **0.5.0 (minor):** semantica globale dei RunLimits (breaking sulla semantica, non
+   sull'API), `ToolExecutionError` + evento di trace, fallback strict-schema robusto,
+   trace writer per-run, esportazione `LLMResult`/`LLMUsage`.
+3. **Infra (indipendente):** release workflow a build unica con gate, dependabot, pinning
+   SHA, matrice 3.14, allineamento pre-commit, `just check`.
+4. **Spec/docs:** semantica limits, regola "argomenti che escono ⇒ WRITE", `tools/` nel
+   role map, CONFORMANCE.md.

{capability_reasoning_kernel-0.4.1 → capability_reasoning_kernel-0.4.2}/docs/DEVELOPMENT.md

@@ -16,6 +16,7 @@ Python 3.12+ is required. The default suite needs no API keys: it runs against t
 
 | Command            | What it does                                                              |
 |--------------------|--------------------------------------------------------------------------|
+| `just check`       | `lint` + `typecheck` + `test` — everything CI runs, in one command        |
 | `just demo`        | Worked demo (FakeProvider): legit send commits; injection inert; exfil blocked |
 | `just demo-subkernel` | §5.4 composition demo: untrusted content delegated at a reduced grant  |
 | `just demo-limits` | Termination demo: `RunLimits` aborts the run closed before the second effect |
@@ -61,16 +62,16 @@ Keys are accepted under either their conventional bare name or an `RK_`-prefixed
 
 | Provider  | Env var                                  | Default model (more capable variant)        |
 |-----------|------------------------------------------|---------------------------------------------|
-| Anthropic | `ANTHROPIC_API_KEY` / `RK_ANTHROPIC_API_KEY` | `claude-sonnet-4-6` (`claude-opus-4-8`) |
+| Anthropic | `ANTHROPIC_API_KEY` / `RK_ANTHROPIC_API_KEY` | `claude-sonnet-5` (`claude-opus-4-8`) |
 | OpenAI    | `OPENAI_API_KEY` / `RK_OPENAI_API_KEY`       | `gpt-5.5` (`gpt-5.5-pro`)               |
 | Deepseek  | `DEEPSEEK_API_KEY` / `RK_DEEPSEEK_API_KEY`   | `deepseek-v4-flash` (`deepseek-v4-pro`) |
 
 Other overrides (defaults in `config.py`): `RK_LLM_PROVIDER_DEFAULT`, `RK_LLM_MODEL_*`,
-`RK_DEEPSEEK_BASE_URL`, `RK_LLM_TIMEOUT_SECONDS`. A live test or demo **skips** any provider whose
+`RK_DEEPSEEK_BASE_URL`, `RK_LLM_TIMEOUT_SECONDS`, `RK_LLM_MAX_TOKENS`. A live test or demo **skips** any provider whose
 key is absent, so partial configuration is fine.
 
 Each provider has a sensible default and a more capable variant (the parenthesised id above). Model
-ids are current as of May 2026; the defaults are the cost-effective tier, the variants the
+ids are current as of July 2026; the defaults are the cost-effective tier, the variants the
 frontier tier. For Deepseek the legacy `deepseek-chat` / `deepseek-reasoner` names still resolve as
 deprecated aliases of `deepseek-v4-flash` but should not be used.
 

capability_reasoning_kernel-0.4.2/docs/favicon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Reasoning Kernel">
+  <rect width="64" height="64" fill="#0c0c0b"/>
+  <rect x="3.5" y="3.5" width="57" height="57" fill="none" stroke="#b45f43" stroke-width="2"/>
+  <text x="11" y="42" font-family="ui-monospace, SFMono-Regular, Menlo, monospace"
+        font-size="26" font-weight="500" fill="#b45f43">&gt;_</text>
+</svg>