weaver-kernel 0.7.0__tar.gz → 0.9.0__tar.gz

{weaver_kernel-0.7.0 → weaver_kernel-0.9.0}/.github/workflows/ci.yml

@@ -45,6 +45,8 @@ jobs:
           python examples/basic_cli.py
           python examples/billing_demo.py
           python examples/http_driver_demo.py
+          python examples/tutorial.py
+          python examples/readme_quickstart.py
 
   conformance_stub:
     name: "Weaver Spec Conformance Stub (v0.1.0)"

{weaver_kernel-0.7.0 → weaver_kernel-0.9.0}/AGENTS.md

@@ -46,7 +46,7 @@ Use these terms consistently. Never substitute synonyms:
 
 ## Quality bar
 
-- `make ci` must pass before every push. It runs: `fmt → lint → type → test → example`.
+- `make ci` must pass before every push. It runs: `fmt-check → lint → type → test → example`. Use `make fmt` to auto-fix formatting before re-running `make ci`.
 - All public interfaces need type hints and docstrings.
 - Never raise bare `ValueError` or `KeyError` to callers. Use custom exceptions from `errors.py`. Catching stdlib exceptions internally to remap them is fine.
 - Error messages are part of the contract — tests must assert both exception type and message.

{weaver_kernel-0.7.0 → weaver_kernel-0.9.0}/CHANGELOG.md

@@ -7,6 +7,203 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-05-29
+
+### Added
+- Capability namespaces and hierarchical discovery in `CapabilityRegistry`:
+  dot-notation `capability_id`s now expose `list_namespaces()` /
+  `list_namespace(prefix)` operations; `register_namespace(prefix, loader=...)`
+  enables deferred registration for large tool ecosystems (the loader runs
+  at most once on first access). `search()` gained an `offset` kwarg for
+  pagination, strips a small stop-word set, and now scores with a
+  BM25-flavoured ranker that weights `capability_id`/`tags` matches above
+  `description`. Flat (un-namespaced) capability IDs continue to work
+  unchanged. (#45)
+- Capability marketplace, part 1 — manifest format & local registry: new
+  `CapabilityDescriptor` and `CapabilityManifest` dataclasses (both
+  JSON-round-trippable via `to_dict`/`from_dict`), new
+  `agent_kernel.federation` module with `build_manifest()`,
+  `import_manifest()`, and `merge_sensitivity()`, and new `Kernel.advertise()`
+  / `Kernel.import_remote()` methods. `Kernel` gained a `kernel_id`
+  argument used as the manifest publisher identity. Three trust policies
+  are honoured at import time (`most_restrictive` (default), `local_only`,
+  `remote_deferred`); imported capabilities are routed through a
+  caller-supplied driver and flow through the full local policy → token →
+  firewall pipeline. HMAC tokens remain kernel-scoped — a token issued by
+  one kernel cannot be verified by another with a different secret. New
+  errors `NamespaceNotFound`, `FederationError`, `ManifestError`,
+  `TrustPolicyError`. (#52)
+- New docs: [`docs/federation.md`](docs/federation.md) for the marketplace
+  protocol and a namespace section in
+  [`docs/capabilities.md`](docs/capabilities.md).
+- Capability marketplace, part 2 — federated discovery: new
+  `agent_kernel.federation_discovery` module with `discover_peers()`,
+  `sign_manifest()`, `verify_manifest()`, `serve_manifest_payload()`, and
+  `DiscoveryRateLimiter`. `Kernel.discover_peers()` fetches one or more
+  manifests over HTTP from peer URLs or a registry URL. Signed envelopes
+  (HMAC-SHA256) detect tampering and let importers refuse unsigned
+  manifests when a verification secret is in play (and vice versa). New
+  errors `ManifestSignatureError` and `DiscoveryError`. (#51, closes #49)
+- OpenTelemetry integration: new `agent_kernel.otel` module with
+  `instrument_kernel(kernel)` that wraps `Kernel.invoke` and
+  `Kernel.grant_capability` with OTel spans + metrics (invocation count,
+  latency histogram, denial counter). No-op when the optional `[otel]`
+  extra is not installed (`OTEL_AVAILABLE` reports the runtime status).
+  Idempotent — repeat calls on the same kernel are no-ops. (#38)
+- Streaming firewall: new `Firewall.apply_stream()` async-iterator method
+  that processes driver chunks one-at-a-time, applying PII redaction
+  per-chunk. New `StreamingDriver` Protocol in `drivers/base.py` extends
+  `Driver` with an optional `execute_stream()`. New `Kernel.invoke_stream()`
+  yields `Frame` chunks; the last chunk carries `is_final=True`. Drivers
+  without `execute_stream` automatically fall back to a single-chunk stream
+  via `execute()`. `Frame` gained an `is_final: bool` field. (#47)
+- `examples/readme_quickstart.py` — a runnable mirror of the README quickstart,
+  wired into `make example` and the CI "Examples" step. Together with
+  `tests/test_readme_quickstart.py` (which extracts and runs the inline README
+  snippet itself), CI fails if the documented quickstart stops producing the
+  expected output. (#83)
+
+### Changed
+- Tech debt: `policy_dsl.py` decomposed (was 661 lines). Parsing and
+  schema dataclasses now live in `policy_dsl_parser.py`
+  (`PolicyMatch`, `PolicyRule`, `parse_engine_data`, `parse_rule`,
+  YAML/TOML loaders), and the denial-explanation traversal in
+  `policy_dsl_explain.py`. The public import surface
+  (`DeclarativePolicyEngine`, `PolicyMatch`, `PolicyRule`) is unchanged.
+  `RateLimiter` and rate-limit constants extracted from `policy.py` into
+  a new `rate_limit.py` module; `policy.py` continues to re-export them
+  under their original names. (#68)
+- Tech debt: `kernel.py` split into the `agent_kernel.kernel` sub-package
+  to honour AGENTS.md's ≤ 300-line module bar. The `Kernel` class lives
+  in `kernel/__init__.py`; heavy methods (invoke pipeline, dry-run,
+  federation, streaming) delegate to sibling modules. Existing
+  `from agent_kernel import Kernel` / `from agent_kernel.kernel import Kernel`
+  imports are unchanged. (#68)
+
+### Documentation
+- Fixed handle-expansion examples that omitted the now-required `principal`
+  argument and therefore raised `HandleConstraintViolation` when copy-pasted:
+  the README quickstart (#83) and `docs/context_firewall.md` +
+  `docs/architecture.md` (#84) now pass `principal=` and link to
+  `docs/security.md#handle-expansion-boundary`. The README quickstart also
+  drops two unused imports (`ExecutionContext`, `HMACTokenProvider`).
+- `docs/capabilities.md` "Sensitivity tags" now lists `SensitivityTag.MEMORY`
+  and links to `docs/security.md#memory-actions`. (#89)
+- Corrected the base-dependency list in `docs/agent-context/invariants.md` and
+  `docs/agent-context/architecture.md` from "`httpx` only" to
+  "`httpx` + `pydantic`", pointing to `AGENTS.md` as the canonical dependency
+  policy. (#90)
+- The `agent_kernel` module docstring's `Errors::` block now lists every
+  exported error class — added `TokenRevoked`, `AdapterParseError`,
+  `CapabilityAlreadyRegistered`, `HandleConstraintViolation`,
+  `ManifestSignatureError`, and `DiscoveryError`. (#91)
+
+### Tests
+- Added explicit dry-run regression tests for `HTTPDriver` and `MCPDriver`,
+  pinning the kernel's driver-agnostic dry-run short-circuit. (#68)
+- `tests/test_public_api.py` — asserts every error class exported via `__all__`
+  appears in the `agent_kernel` module docstring, preventing public-API
+  docstring drift. (#91)
+- `tests/test_readme_quickstart.py` — extracts the README quickstart code block
+  and executes it, asserting the documented output so the inline snippet cannot
+  silently drift from the working API. (#83)
+
+### Fixed
+- `merge_sensitivity()` (and `most_restrictive` imports) now ranks the `MEMORY`
+  sensitivity tag instead of silently treating it as `NONE`. (#52)
+- `import_manifest()` is now atomic: a manifest whose capability ID is already
+  registered locally — or that lists the same ID more than once — raises
+  `ManifestError` and registers nothing, instead of leaving a partial,
+  unrouted import behind. (#52)
+- `CapabilityRegistry.search()` now triggers every pending deferred namespace
+  loader before ranking, so matches are no longer missed when the query shares
+  no token with a namespace prefix. (#45)
+- A deferred namespace loader that fails (by raising or returning an
+  out-of-namespace capability) no longer permanently disables the namespace —
+  the load is retried on a later access. (#45)
+- `Makefile` now invokes every tool via `python -m <tool>` (matching the
+  existing `test` target) so `make ci` uses the active interpreter's
+  site-packages instead of whatever `ruff` / `mypy` resolves first on
+  `PATH`. Fixes spurious `import-not-found` / `no-redef` errors on machines
+  where `mypy` or `ruff` is provided by an isolated installer such as
+  `uv tool` or `pipx`. (#86)
+- `make ci` now runs the non-mutating `fmt-check` target (`ruff format
+  --check`) instead of the file-mutating `fmt` target. Local `make ci`
+  now fails on unformatted code exactly like `.github/workflows/ci.yml`
+  does, instead of silently auto-fixing the working tree and letting an
+  unfixed commit be pushed. `make fmt` remains available for manual
+  auto-formatting. `AGENTS.md`, `docs/agent-context/workflows.md`,
+  `docs/agent-context/review-checklist.md`, `CONTRIBUTING.md`, and the
+  `README.md` development section are updated to describe the new chain. (#88)
+
+## [0.8.0] - 2026-05-22
+
+### Added
+- "Secure your first MCP tool in 5 minutes" tutorial: new
+  [`docs/tutorial.md`](docs/tutorial.md) walks a new reader from install to a
+  working invocation, covering registration, principals, grants, the three
+  LLM-safe response modes (`summary` / `table` / `handle_only`), handle
+  expansion, policy denial with stable `reason_code`, and `explain()`
+  audit. The admin-only `raw` mode is described but not exercised by the
+  walkthrough. Companion runnable example
+  [`examples/tutorial.py`](examples/tutorial.py) uses `InMemoryDriver`
+  (offline, zero external deps) and is exercised by `make example` and CI;
+  it now `assert`s that no PII field leaks into the LLM-safe Frame so a
+  firewall regression fails the build. (#46)
+- README "How this relates to neighboring projects" section: a neutral
+  boundaries table covering `AgentFence` (external CLI/proxy gate),
+  `contextweaver` (context compilation library), `ChainWeaver`
+  (deterministic flow orchestrator), and `weaver-spec` (specification +
+  conformance suite), plus a "When *not* to use this" callout. (#71)
+- Grant-constraint enforcement on handle expansion (#76). `Handle` now carries
+  the `principal_id` and `constraints` from the original grant, persisted at
+  handle creation time by `HandleStore.store`. `HandleStore.expand` rechecks
+  these against the requested expand query:
+  - A request `limit` larger than the grant's `max_rows` is rejected with
+    `HandleConstraintViolation` (`reason_code = handle_constraint_violation`).
+  - A request `fields` entry outside `allowed_fields` is rejected; an
+    unscoped expand applies `allowed_fields` as the default projection.
+  - A request filter that disagrees with the grant's `scope` is rejected;
+    the scope filter is otherwise AND-merged so the caller cannot bypass it.
+  - A `principal_id` parameter that does not match the handle's stored
+    principal raises `HandleConstraintViolation`
+    (`reason_code = handle_principal_mismatch`).
+- `SensitivityTag.MEMORY` and memory-action policy rules in
+  `DefaultPolicyEngine` (#75). Project-scoped memory reads are allowed by
+  default; sensitive-scoped reads require the `memory_reader_sensitive` role
+  (or `admin`); writes always require `memory_writer` (or `admin`). The
+  `explain()` path lists the same conditions with stable `reason_code`s.
+- New stable `DenialReason` codes: `HANDLE_CONSTRAINT_VIOLATION`,
+  `HANDLE_PRINCIPAL_MISMATCH`, `MEMORY_WRITE_REQUIRES_WRITER`,
+  `MEMORY_SENSITIVE_READ_DENIED`.
+- `HandleConstraintViolation` error class (subclass of `AgentKernelError`,
+  exported from `agent_kernel`) — carries an optional `reason_code` matching
+  the `DenialReason` vocabulary so handle-side and grant-side denials share
+  one set of stable codes.
+- `Kernel.expand` accepts an optional `principal: Principal` argument that
+  is forwarded to `HandleStore.expand` for principal-mismatch checks.
+- Memory-action input redaction (#75): `ActionTrace.args` for any capability
+  whose ID starts with `memory.` has payload-like keys (`payload`, `content`,
+  `value`, `memory`, `text`, `body`) replaced with `"[REDACTED]"`. Keys are
+  preserved so audit can confirm the action took place without exposing the
+  durable content the agent wrote or read.
+- New `tests/test_firewall_boundary.py` (#74) — focused regression suite that
+  pushes synthetic secret/PII values through the raw → `Frame` boundary
+  end-to-end and asserts those values never appear in summary/table/raw
+  frames, are stripped by `allowed_fields`, never reach `ActionTrace.args`
+  for memory capabilities, and stay quarantined when raw mode is downgraded
+  for non-admin principals.
+
+### Security
+- Closes #76: handle expansion can no longer return data outside the original
+  grant's `max_rows` / `allowed_fields` / `scope`, and handle IDs are no
+  longer bearer credentials that work across principals.
+- Closes #75: memory reads and writes are governed actions with stable
+  denial codes and trace-side redaction of durable payloads.
+- Closes #74: redaction boundary is pinned by negative assertions against
+  fake-secret strings, catching future regressions that drop a redaction
+  step or route raw data through a new path.
+
 ## [0.7.0] - 2026-05-20
 
 ### Added

{weaver_kernel-0.7.0 → weaver_kernel-0.9.0}/CONTRIBUTING.md

@@ -15,11 +15,12 @@ pip install -e ".[dev]"
 ## Running checks
 
 ```bash
-make fmt    # auto-format with ruff
-make lint   # lint with ruff
-make type   # type-check with mypy
-make test   # run pytest with coverage
-make ci     # all of the above + examples
+make fmt        # auto-format with ruff (not run by `make ci`)
+make fmt-check  # verify formatting with `ruff format --check` (no mutation)
+make lint       # lint with ruff
+make type       # type-check with mypy
+make test       # run pytest with coverage
+make ci         # fmt-check + lint + type + test + example
 ```
 
 ## Pull request guidelines

weaver_kernel-0.9.0/Makefile

@@ -0,0 +1,25 @@
+.PHONY: fmt fmt-check lint type test example ci
+
+fmt:
+	python -m ruff format src/ tests/ examples/
+
+fmt-check:
+	python -m ruff format --check src/ tests/ examples/
+
+lint:
+	python -m ruff check src/ tests/ examples/
+
+type:
+	python -m mypy src/
+
+test:
+	python -m pytest -q --cov=agent_kernel
+
+example:
+	python examples/basic_cli.py
+	python examples/billing_demo.py
+	python examples/http_driver_demo.py
+	python examples/tutorial.py
+	python examples/readme_quickstart.py
+
+ci: fmt-check lint type test example

{weaver_kernel-0.7.0 → weaver_kernel-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: weaver-kernel
-Version: 0.7.0
+Version: 0.9.0
 Summary: Capability-based security kernel for AI agents operating in large tool ecosystems
 Project-URL: Homepage, https://github.com/dgenio/agent-kernel
 Project-URL: Repository, https://github.com/dgenio/agent-kernel
@@ -289,15 +289,16 @@ pip install weaver-kernel
 
 > **Note:** The PyPI package is `weaver-kernel` (Weaver ecosystem), but the Python import remains `agent_kernel`.
 
+> **New here?** [docs/tutorial.md](docs/tutorial.md) walks through register → grant → invoke → expand → explain in five minutes.
+
 ```python
 import asyncio, os
 os.environ["AGENT_KERNEL_SECRET"] = "my-secret"
 
 from agent_kernel import (
-    Capability, CapabilityRegistry, HMACTokenProvider,
+    Capability, CapabilityRegistry,
     InMemoryDriver, Kernel, Principal, SafetyClass, StaticRouter,
 )
-from agent_kernel.drivers.base import ExecutionContext
 from agent_kernel.models import CapabilityRequest
 
 # 1. Register a capability
@@ -330,7 +331,11 @@ async def main():
     print(frame.facts)           # ['Total rows: 1', 'Top keys: id, title', ...]
     print(frame.handle)          # Handle(handle_id='...', ...)
 
-    expanded = kernel.expand(frame.handle, query={"limit": 1, "fields": ["title"]})
+    # `principal` is required: the handle is bound to the granting principal,
+    # so an omitted principal raises HandleConstraintViolation.
+    expanded = kernel.expand(
+        frame.handle, query={"limit": 1, "fields": ["title"]}, principal=principal
+    )
     print(expanded.table_preview)  # [{'title': 'Buy milk'}]
 
     trace = kernel.explain(frame.action_id)
@@ -339,6 +344,12 @@ async def main():
 asyncio.run(main())
 ```
 
+> This snippet is extracted and executed by CI (`tests/test_readme_quickstart.py`), and
+> a standalone runnable mirror lives at
+> [`examples/readme_quickstart.py`](examples/readme_quickstart.py) (run by `make example`).
+> CI fails if either stops producing the documented output, so this quickstart cannot
+> silently drift from the working API.
+
 ## Where it fits
 
 ```
@@ -356,6 +367,45 @@ asyncio.run(main())
 
 `agent-kernel` sits **above** `contextweaver` (context compilation) and **above** raw tool execution. It provides the authorization, execution, and audit layer.
 
+## How this relates to neighboring projects
+
+`agent-kernel` is the embeddable runtime layer of the **Weaver ecosystem**. The
+projects below solve adjacent problems and are designed to compose, not to
+overlap.
+
+| Project | Role | Where it runs | Use it when… |
+|---|---|---|---|
+| **agent-kernel** *(this repo)* | Embeddable library/runtime: capability registry, policy, HMAC tokens, context firewall, audit trace. | In-process inside your agent host. | You need authorization, redaction, and audit between an LLM loop and a large tool ecosystem. |
+| [**AgentFence**](https://github.com/dgenio/AgentFence) | External CLI / local proxy that intercepts tool calls and applies a policy gate. | Out-of-process, alongside your agent. | You want a policy boundary without changing your agent code, or you need to gate a third-party agent host you can't modify. |
+| [**contextweaver**](https://github.com/dgenio/contextweaver) | Library that selects and compiles the context an LLM receives. | In-process, before the LLM call. | You need to assemble relevant context for a prompt. It sits *under* the LLM loop; agent-kernel sits *between* the LLM and tools. |
+| **ChainWeaver** | Orchestrator for deterministic tool chains. | In-process or as a separate service. | You need to run a multi-step deterministic flow rather than free-form LLM tool use. |
+| [**weaver-spec**](https://github.com/dgenio/weaver-spec) | Specification: invariants, capability/token/frame contracts, conformance suite. | Not a runtime — it's docs + a contract test suite. | You're building another Weaver-compatible implementation, or you want to verify an existing one. |
+
+A minimal architecture using `agent-kernel` as the central runtime:
+
+```
+LLM / agent loop
+       │
+       ▼
+contextweaver  ─►  agent-kernel  ─►  driver  ─►  MCP / HTTP / A2A / internal API
+                       │
+                       ▼
+                  ActionTrace
+```
+
+### When *not* to use this
+
+- You only need a process-level policy gate around an existing agent host —
+  reach for `AgentFence` instead.
+- You only need to compile context for a prompt — use `contextweaver`.
+- You want a deterministic, scripted workflow with no LLM in the inner loop —
+  use `ChainWeaver`.
+- You're writing a static analyzer or one-shot CLI scanner with no
+  per-invocation runtime — `agent-kernel` would be overkill.
+
+See [docs/tutorial.md](docs/tutorial.md) for an end-to-end "secure your first
+MCP tool in 5 minutes" walkthrough.
+
 ## Weaver Spec Compatibility: v0.1.0
 
 agent-kernel is a compliant implementation of [weaver-spec v0.1.0](https://github.com/dgenio/weaver-spec).
@@ -392,7 +442,7 @@ See [docs/agent-context/invariants.md](docs/agent-context/invariants.md) for the
 git clone https://github.com/dgenio/agent-kernel
 cd agent-kernel
 pip install -e ".[dev]"
-make ci      # fmt + lint + type + test + examples
+make ci      # fmt-check + lint + type + test + examples
 ```
 
 ## License

{weaver_kernel-0.7.0 → weaver_kernel-0.9.0}/README.md

@@ -43,15 +43,16 @@ pip install weaver-kernel
 
 > **Note:** The PyPI package is `weaver-kernel` (Weaver ecosystem), but the Python import remains `agent_kernel`.
 
+> **New here?** [docs/tutorial.md](docs/tutorial.md) walks through register → grant → invoke → expand → explain in five minutes.
+
 ```python
 import asyncio, os
 os.environ["AGENT_KERNEL_SECRET"] = "my-secret"
 
 from agent_kernel import (
-    Capability, CapabilityRegistry, HMACTokenProvider,
+    Capability, CapabilityRegistry,
     InMemoryDriver, Kernel, Principal, SafetyClass, StaticRouter,
 )
-from agent_kernel.drivers.base import ExecutionContext
 from agent_kernel.models import CapabilityRequest
 
 # 1. Register a capability
@@ -84,7 +85,11 @@ async def main():
     print(frame.facts)           # ['Total rows: 1', 'Top keys: id, title', ...]
     print(frame.handle)          # Handle(handle_id='...', ...)
 
-    expanded = kernel.expand(frame.handle, query={"limit": 1, "fields": ["title"]})
+    # `principal` is required: the handle is bound to the granting principal,
+    # so an omitted principal raises HandleConstraintViolation.
+    expanded = kernel.expand(
+        frame.handle, query={"limit": 1, "fields": ["title"]}, principal=principal
+    )
     print(expanded.table_preview)  # [{'title': 'Buy milk'}]
 
     trace = kernel.explain(frame.action_id)
@@ -93,6 +98,12 @@ async def main():
 asyncio.run(main())
 ```
 
+> This snippet is extracted and executed by CI (`tests/test_readme_quickstart.py`), and
+> a standalone runnable mirror lives at
+> [`examples/readme_quickstart.py`](examples/readme_quickstart.py) (run by `make example`).
+> CI fails if either stops producing the documented output, so this quickstart cannot
+> silently drift from the working API.
+
 ## Where it fits
 
 ```
@@ -110,6 +121,45 @@ asyncio.run(main())
 
 `agent-kernel` sits **above** `contextweaver` (context compilation) and **above** raw tool execution. It provides the authorization, execution, and audit layer.
 
+## How this relates to neighboring projects
+
+`agent-kernel` is the embeddable runtime layer of the **Weaver ecosystem**. The
+projects below solve adjacent problems and are designed to compose, not to
+overlap.
+
+| Project | Role | Where it runs | Use it when… |
+|---|---|---|---|
+| **agent-kernel** *(this repo)* | Embeddable library/runtime: capability registry, policy, HMAC tokens, context firewall, audit trace. | In-process inside your agent host. | You need authorization, redaction, and audit between an LLM loop and a large tool ecosystem. |
+| [**AgentFence**](https://github.com/dgenio/AgentFence) | External CLI / local proxy that intercepts tool calls and applies a policy gate. | Out-of-process, alongside your agent. | You want a policy boundary without changing your agent code, or you need to gate a third-party agent host you can't modify. |
+| [**contextweaver**](https://github.com/dgenio/contextweaver) | Library that selects and compiles the context an LLM receives. | In-process, before the LLM call. | You need to assemble relevant context for a prompt. It sits *under* the LLM loop; agent-kernel sits *between* the LLM and tools. |
+| **ChainWeaver** | Orchestrator for deterministic tool chains. | In-process or as a separate service. | You need to run a multi-step deterministic flow rather than free-form LLM tool use. |
+| [**weaver-spec**](https://github.com/dgenio/weaver-spec) | Specification: invariants, capability/token/frame contracts, conformance suite. | Not a runtime — it's docs + a contract test suite. | You're building another Weaver-compatible implementation, or you want to verify an existing one. |
+
+A minimal architecture using `agent-kernel` as the central runtime:
+
+```
+LLM / agent loop
+       │
+       ▼
+contextweaver  ─►  agent-kernel  ─►  driver  ─►  MCP / HTTP / A2A / internal API
+                       │
+                       ▼
+                  ActionTrace
+```
+
+### When *not* to use this
+
+- You only need a process-level policy gate around an existing agent host —
+  reach for `AgentFence` instead.
+- You only need to compile context for a prompt — use `contextweaver`.
+- You want a deterministic, scripted workflow with no LLM in the inner loop —
+  use `ChainWeaver`.
+- You're writing a static analyzer or one-shot CLI scanner with no
+  per-invocation runtime — `agent-kernel` would be overkill.
+
+See [docs/tutorial.md](docs/tutorial.md) for an end-to-end "secure your first
+MCP tool in 5 minutes" walkthrough.
+
 ## Weaver Spec Compatibility: v0.1.0
 
 agent-kernel is a compliant implementation of [weaver-spec v0.1.0](https://github.com/dgenio/weaver-spec).
@@ -146,7 +196,7 @@ See [docs/agent-context/invariants.md](docs/agent-context/invariants.md) for the
 git clone https://github.com/dgenio/agent-kernel
 cd agent-kernel
 pip install -e ".[dev]"
-make ci      # fmt + lint + type + test + examples
+make ci      # fmt-check + lint + type + test + examples
 ```
 
 ## License

{weaver_kernel-0.7.0 → weaver_kernel-0.9.0}/docs/agent-context/architecture.md

@@ -39,7 +39,7 @@ The architecture optimizes for:
 | Tokens signed, not encrypted | Simplicity; avoids key management complexity | Payloads are readable — never store secrets in them |
 | Keyword-based capability search | Deterministic; no external service dependency | Less flexible than semantic search; relies on good tagging |
 | Firewall is mandatory | Prevents accidental context blowup and data leakage | All output is bounded; debugging requires admin `raw` mode |
-| Single dep (`httpx` only) | Minimal attack surface for a security kernel | Adding a dependency requires justification |
+| Minimal deps (`httpx` + `pydantic`) | Small attack surface for a security kernel | Adding a dependency requires justification (see `AGENTS.md`) |
 
 ## Things not to simplify
 

{weaver_kernel-0.7.0 → weaver_kernel-0.9.0}/docs/agent-context/invariants.md

@@ -40,7 +40,8 @@ These constraints are non-negotiable. Violating any one silently degrades securi
    derived keys must stay out of logs, error messages, and traces.
 
 6. **Never add dependencies without justification.** The dependency list is intentionally
-   minimal (`httpx` only). Every new dependency expands the attack surface.
+   minimal (`httpx` + `pydantic` — see [`AGENTS.md`](../../AGENTS.md) for the canonical
+   dependency policy). Every new dependency expands the attack surface.
 
 7. **Never register duplicate capability IDs.** The registry raises
    `CapabilityAlreadyRegistered`. Duplicates cause ambiguous routing and policy

{weaver_kernel-0.7.0 → weaver_kernel-0.9.0}/docs/agent-context/review-checklist.md

@@ -10,7 +10,7 @@
 Run before every PR submission.
 
 ### CI gate
-- [ ] `make ci` passes (fmt → lint → type → test → example).
+- [ ] `make ci` passes (fmt-check → lint → type → test → example).
 
 ### Correctness
 - [ ] Every changed docstring matches the actual implementation.

{weaver_kernel-0.7.0 → weaver_kernel-0.9.0}/docs/agent-context/workflows.md

@@ -7,18 +7,24 @@
 
 | Command | Purpose | When to run |
 |---------|---------|-------------|
-| `make ci` | Full pre-push gate: fmt → lint → type → test → example | Before every push |
-| `make fmt` | Auto-format with ruff | During development |
+| `make ci` | Full pre-push gate: fmt-check → lint → type → test → example | Before every push |
+| `make fmt` | Auto-format with ruff (mutates files) | During development |
+| `make fmt-check` | Verify formatting with `ruff format --check` (no mutation) | Used by `make ci`; matches what CI runs |
 | `make lint` | Lint check with ruff | Isolated lint verification |
 | `make type` | mypy type check | After changing type annotations |
 | `make test` | pytest with coverage | After changing code |
 | `make example` | Run all example scripts | After changing examples or core APIs |
 
 `make ci` is the **single authoritative pre-push command**. It runs all five targets
-in sequence. If `make ci` passes, the PR is ready for review.
-
-**Note:** `make fmt` auto-formats locally, but CI runs `ruff format --check` and fails
-on unformatted code. Always run `make ci` to catch this asymmetry.
+in sequence and mirrors the checks in the `test` job of `.github/workflows/ci.yml`: the
+format step is the non-mutating `fmt-check` (equivalent to CI's `ruff format --check`),
+and lint/type/test/example run the same tools CI does. (CI's separate `conformance_stub`
+job is a no-op placeholder and is not part of the local gate.) The Makefile
+additionally invokes every tool via `python -m <tool>` — a local hardening over CI
+that uses the active interpreter's site-packages, preventing spurious failures when
+`ruff` or `mypy` are provided by isolated installers such as `uv tool` or `pipx`. If
+`make ci` passes locally, the same checks will pass in CI. Use `make fmt` (the
+mutating target) when you want to auto-fix formatting before re-running `make ci`.
 
 ## PR conventions
 

{weaver_kernel-0.7.0 → weaver_kernel-0.9.0}/docs/architecture.md

@@ -31,7 +31,7 @@ The central orchestrator. Wires all components together and exposes:
 - `request_capabilities(goal)` — discover relevant capabilities
 - `grant_capability(request, principal, justification)` — policy check + token issuance
 - `invoke(token, principal, args, response_mode, dry_run=False)` — execute + firewall + trace, or short-circuit before driver dispatch when `dry_run=True`
-- `expand(handle, query)` — paginate/filter stored results
+- `expand(handle, *, query, principal=None)` — paginate/filter stored results; `principal` is required for principal-bound handles (see [`docs/security.md`](security.md#handle-expansion-boundary))
 - `explain(action_id)` — retrieve audit trace
 - `explain_denial(request, principal, justification)` — return a structured `DenialExplanation` instead of raising `PolicyDenied`
 
@@ -52,8 +52,9 @@ Both built-in engines satisfy `ExplainingPolicyEngine`:
   3. **DESTRUCTIVE** — requires role `admin` + `justification ≥ 15 chars`
   4. **PII/PCI** — requires `tenant` attribute; enforces `allowed_fields` unless `pii_reader`
   5. **SECRETS** — requires role `admin|secrets_reader` + `justification ≥ 15 chars`
-  6. **max_rows** — 50 (user), 500 (service)
-  7. **Rate limiting** — sliding-window per `(principal_id, capability_id)` (60 READ / 10 WRITE / 2 DESTRUCTIVE per 60s; service role gets 10×)
+  6. **MEMORY** — `memory.read` with `scope.memory_scope == "sensitive"` requires role `memory_reader_sensitive|admin`; `memory.write` / DESTRUCTIVE memory requires role `memory_writer|admin`. Project-scoped memory reads are allowed by default. The kernel also redacts `payload`/`content`/`value`/`memory`/`text`/`body` keys from `ActionTrace.args` for any capability whose ID starts with `memory.`
+  7. **max_rows** — 50 (user), 500 (service)
+  8. **Rate limiting** — sliding-window per `(principal_id, capability_id)` (60 READ / 10 WRITE / 2 DESTRUCTIVE per 60s; service role gets 10×)
 - **`DeclarativePolicyEngine`** — loads rules from a YAML or TOML file (or a plain dict). Supports `safety_class`, `sensitivity`, `roles`, `attributes`, `min_justification`, `intent`, and `scope` match conditions; `allow`/`deny` actions; per-rule `constraints` merged into the resulting `PolicyDecision`; configurable `default` action. Rules are evaluated top-down with first-match-wins. `pyyaml` and `tomli` are optional dependencies — `import agent_kernel` works without them; calling `from_yaml`/`from_toml` without the parser raises `PolicyConfigError` with an install hint.
 
 #### Intent and scope on requests
@@ -96,6 +97,10 @@ Every `PolicyDecision`, `DenialExplanation`, `FailedCondition`, and `PolicyDenie
 | `explicit_deny_rule` | DSL: a `deny` rule matched fully |
 | `intent_not_allowed` | DSL: `match.intent` rejected the request's intent |
 | `scope_not_allowed` | DSL: `match.scope` rejected the request's scope |
+| `handle_constraint_violation` | `HandleStore.expand` request exceeded grant's `max_rows`, `allowed_fields`, or `scope` (#76) |
+| `handle_principal_mismatch` | Handle expansion attempted by a different principal than the one the original grant was issued to (#76) |
+| `memory_write_requires_writer` | `SensitivityTag.MEMORY` WRITE/DESTRUCTIVE without `memory_writer` or `admin` role (#75) |
+| `memory_sensitive_read_denied` | `SensitivityTag.MEMORY` read with `scope.memory_scope == "sensitive"` without `memory_reader_sensitive` or `admin` role (#75) |
 
 Allow-side codes (`AllowReason.*`): `default_policy_allow`, `rule_allow`, `default_fallthrough_allow`, `token_verified`.
 

{weaver_kernel-0.7.0 → weaver_kernel-0.9.0}/docs/capabilities.md

@@ -3,9 +3,60 @@
 ## Naming conventions
 
 - Use `domain.verb_noun` format: `billing.list_invoices`, `users.get_profile`.
+- Prefer fully namespaced IDs (`billing.invoices.list`) over flat ones —
+  the registry will infer namespace operations from the dot-segments and
+  large ecosystems benefit from being able to list/search per namespace.
 - Be specific: prefer `billing.cancel_invoice` over `billing.update`.
 - Avoid generic names like `billing.execute` or `api.call`.
 
+## Namespaces and discovery
+
+`CapabilityRegistry` recognises dot-notation namespaces automatically. No
+extra registration step is required — `register(Capability(capability_id=
+"billing.invoices.list", ...))` is enough to populate the `billing` and
+`billing.invoices` namespaces.
+
+```python
+registry.list_namespaces()
+# ['billing', 'crm']
+
+registry.list_namespace("billing")
+# [Capability('billing.invoices.list'), Capability('billing.payments.refund'), …]
+```
+
+For large tool ecosystems where eagerly registering hundreds of
+capabilities is wasteful, declare a deferred loader. The loader runs at
+most once, the first time the namespace is searched, listed, or any
+capability under it is fetched via `get()`:
+
+```python
+def load_billing() -> list[Capability]:
+    return [
+        Capability(capability_id="billing.invoices.list", …),
+        Capability(capability_id="billing.invoices.create", …),
+        Capability(capability_id="billing.payments.refund", …),
+    ]
+
+registry.register_namespace(
+    "billing",
+    description="Billing and invoicing tools",
+    loader=load_billing,
+)
+```
+
+Search ranks matches with a BM25-flavoured scorer that weights
+`capability_id` and `tags` higher than `description`, strips a small
+stop-word set (`a`, `the`, `please`, …), and offers `offset` for
+pagination:
+
+```python
+results = registry.search("list invoices", max_results=10, offset=0)
+```
+
+Search is deterministic — equal-scoring capabilities are returned in
+`capability_id` order — and trips any deferred namespace loader whose
+prefix shares a token with the query.
+
 ## Granularity
 
 Each capability should map to a single, auditable action with clear side-effects.
@@ -32,6 +83,10 @@ Each capability should map to a single, auditable action with clear side-effects
 Use `SensitivityTag.PII` when results may contain: name, email, phone, SSN, address.
 Use `SensitivityTag.PCI` when results may contain: card numbers, CVV, bank details.
 Use `SensitivityTag.SECRETS` when results may contain: API keys, passwords, tokens.
+Use `SensitivityTag.MEMORY` when results are durable agent memory (project notes,
+session handoff, learned context). Pair it with the `memory.read` / `memory.write` /
+`memory.forget` capability IDs to activate the policy rules and audit-trace redaction
+described in [`docs/security.md#memory-actions`](security.md#memory-actions).
 
 Always pair sensitivity tags with `allowed_fields` to restrict which fields are returned
 to non-privileged callers.