weaver-kernel 0.6.0__tar.gz → 0.8.0__tar.gz

{weaver_kernel-0.6.0 → weaver_kernel-0.8.0}/.github/workflows/ci.yml

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

{weaver_kernel-0.6.0 → weaver_kernel-0.8.0}/CHANGELOG.md

@@ -7,6 +7,119 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- Structured intent and scope metadata on `CapabilityRequest`: new optional
+  `intent: str | None` and `scope: dict[str, Any]` fields let policy engines
+  authorize based on machine-readable intent and scope alongside the existing
+  free-text `goal`. `DeclarativePolicyEngine` rules can match on these via new
+  `intent: [...]` and `scope: {key: value}` clauses in YAML/TOML policy files.
+  Intent-aware allow rules fail closed for legacy callers that don't set an
+  intent. (#72)
+- Structured policy decision trace (`PolicyDecisionTrace` + `PolicyTraceStep`):
+  both built-in policy engines now attach a step-by-step trace to every
+  `PolicyDecision` (allow and deny paths). Each step records the rule
+  considered, the outcome (`matched`/`skipped`/`denied`/`allowed`/
+  `constraint_applied`), a human-readable detail, and — for terminal
+  steps — the stable reason code. Traces echo `intent` and `scope_keys`
+  (scope dimension names only — values redacted) from the request and contain
+  no raw argument values. `DryRunResult.policy_decision`
+  also carries a synthesized single-step trace. (#73)
+- Stable machine-readable denial reason codes: new `DenialReason` and
+  `AllowReason` enums in `agent_kernel.policy_reasons` (also exported as
+  `from agent_kernel import DenialReason, AllowReason`). Every built-in
+  denial path on `DefaultPolicyEngine` and `DeclarativePolicyEngine` populates
+  `PolicyDecision.reason_code`, `DenialExplanation.reason_code`,
+  `FailedCondition.reason_code`, and `PolicyDenied.reason_code`. Tests should
+  assert on these codes instead of matching the human-readable `reason` /
+  `narrative` strings, which remain part of the API but may evolve for
+  clarity. Codes: `missing_role`, `missing_tenant_attribute`,
+  `missing_attribute`, `insufficient_justification`, `invalid_constraint`,
+  `rate_limited`, `no_matching_rule`, `explicit_deny_rule`,
+  `intent_not_allowed`, `scope_not_allowed`; allow-side: `default_policy_allow`,
+  `rule_allow`, `default_fallthrough_allow`. (#77)
+- New public exports: `AllowReason`, `DenialReason`, `PolicyDecisionTrace`,
+  `PolicyTraceStep`.
+
+### Changed
+- `PolicyDecision` gained optional `reason_code: str | None` and
+  `trace: PolicyDecisionTrace | None` fields (both default `None` so
+  third-party engines that don't populate them keep working).
+- `DenialExplanation` and `FailedCondition` gained optional `reason_code`
+  fields populated by both built-in engines on every denial path.
+- `PolicyDenied(reason_code=...)` keyword argument: the exception now carries
+  a `reason_code` attribute so callers can branch on a stable code without
+  matching the human-readable message.
+
 ## [0.6.0] - 2026-05-19
 
 ### Added

{weaver_kernel-0.6.0 → weaver_kernel-0.8.0}/Makefile

@@ -16,5 +16,6 @@ example:
 	python examples/basic_cli.py
 	python examples/billing_demo.py
 	python examples/http_driver_demo.py
+	python examples/tutorial.py
 
 ci: fmt lint type test example

{weaver_kernel-0.6.0 → weaver_kernel-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: weaver-kernel
-Version: 0.6.0
+Version: 0.8.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,6 +289,8 @@ 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"
@@ -356,6 +358,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).

{weaver_kernel-0.6.0 → weaver_kernel-0.8.0}/README.md

@@ -43,6 +43,8 @@ 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"
@@ -110,6 +112,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).

{weaver_kernel-0.6.0 → weaver_kernel-0.8.0}/docs/architecture.md

@@ -52,13 +52,61 @@ 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×)
-- **`DeclarativePolicyEngine`** — loads rules from a YAML or TOML file (or a plain dict). Supports `safety_class`, `sensitivity`, `roles`, `attributes`, and `min_justification` 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.
+  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
+
+`CapabilityRequest` carries optional structured metadata alongside its free-text `goal`:
+
+- `intent: str | None` — a machine-readable label (e.g. `"customer_support_lookup"`).
+- `scope: dict[str, Any]` — a small structured map (e.g. `{"region": "eu-west", "customer_id": "C-42"}`).
+
+`DeclarativePolicyEngine` rules can match on these via top-level keys in `match`:
+
+```yaml
+- name: support_eu_lookup
+  match:
+    safety_class: [READ]
+    intent: [customer_support_lookup]
+    scope: { region: "eu-west" }
+  action: allow
+```
+
+Intent-aware rules fail closed: a request with `intent=None` never matches a rule that requires a specific intent. `scope: { key: "*" }` means "the key must be present with any value".
 
 #### Denial explanations
 
-`PolicyEngine.explain()` (when available) returns a structured `DenialExplanation` with `denied`, `rule_name`, a `failed_conditions: list[FailedCondition]` describing each missing condition with `required`/`actual`/`suggestion`, a `remediation` list, and a human-readable `narrative`. Engines collect all failing conditions (no short-circuit) so callers get the full picture. For `DeclarativePolicyEngine`, an explicit deny rule that fully matches is reported as the cause; partial-match deny rules are skipped during explanation so the surfaced advice is actionable rather than self-defeating.
+`PolicyEngine.explain()` (when available) returns a structured `DenialExplanation` with `denied`, `rule_name`, a `failed_conditions: list[FailedCondition]` describing each missing condition with `required`/`actual`/`suggestion`/`reason_code`, a `remediation` list, a human-readable `narrative`, and a top-level `reason_code` (the code of the first failed condition). Engines collect all failing conditions (no short-circuit) so callers get the full picture. For `DeclarativePolicyEngine`, an explicit deny rule that fully matches is reported as the cause; partial-match deny rules are skipped during explanation so the surfaced advice is actionable rather than self-defeating.
+
+#### Reason codes
+
+Every `PolicyDecision`, `DenialExplanation`, `FailedCondition`, and `PolicyDenied` from the built-in engines carries a stable `reason_code`. Assert on these codes — not on the human-readable `reason` / `narrative` strings:
+
+| Code (`DenialReason.*`) | When |
+|---|---|
+| `missing_role` | Principal lacks a required role |
+| `missing_tenant_attribute` | PII/PCI capability needs `tenant` attribute |
+| `missing_attribute` | Declarative rule's required attribute absent or mismatched |
+| `insufficient_justification` | Justification shorter than the minimum |
+| `invalid_constraint` | Constraint value (e.g. `max_rows`) not parseable |
+| `rate_limited` | Sliding-window rate limit exceeded |
+| `no_matching_rule` | DSL: no rule matched + default `deny` |
+| `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`.
+
+#### Decision trace
+
+Every `PolicyDecision` from a built-in engine carries a `PolicyDecisionTrace` describing how the decision was reached: the engine name, the capability and principal IDs, the request's `intent` (echoed) and `scope_keys` (scope dimension names only — values are redacted), and an ordered list of `PolicyTraceStep` entries. Each step records the rule name, the outcome (`matched`/`skipped`/`denied`/`allowed`/`constraint_applied`), a human-readable detail, and — for terminal steps — the same stable `reason_code` carried on the decision. Traces are safe to log and serialize: they contain rule names, condition names, and codes only — never raw argument values.
 
 #### Dry-run mode
 

weaver_kernel-0.8.0/docs/security.md

@@ -0,0 +1,95 @@
+# Security Model
+
+## Threat model
+
+| Threat | Mitigation |
+|--------|-----------|
+| Tool-space interference (agent calls wrong tool) | Capability registry + policy gate before any execution |
+| Confused deputy attack | Tokens are bound to `principal_id` — cannot be reused by another principal |
+| Token forgery / tampering | HMAC-SHA256 signature; any bit flip → `TokenInvalid` |
+| Token replay after expiry | Expiry checked on every `verify()` call |
+| Context injection via raw tool output | Firewall always transforms `RawResult → Frame`; raw data never reaches LLM by default |
+| PII / PCI leakage | Redaction + `allowed_fields` enforcement in the firewall |
+| Privilege escalation via WRITE/DESTRUCTIVE | Policy engine enforces role requirements |
+| Audit evasion | Every `invoke()` creates an immutable `ActionTrace` |
+| Handle scope escape (expand exceeds grant) | Handles persist grant constraints; `HandleStore.expand` rechecks `max_rows`, `allowed_fields`, `scope`, and principal binding (#76) |
+| Memory exfiltration via tool output | `SensitivityTag.MEMORY` capabilities gate sensitive reads and durable writes; `ActionTrace.args` redacts payload-like fields for `memory.*` capabilities (#75) |
+| Raw memory payload reaching audit log | Kernel strips `payload`/`content`/`value`/`memory`/`text`/`body` from `ActionTrace.args` for `memory.*` capabilities |
+
+## Token scopes
+
+A `CapabilityToken` binds:
+- `capability_id` — which capability is authorized
+- `principal_id` — who the token was issued to
+- `constraints` — max_rows, allowed_fields, etc. (signed into the token)
+- `expires_at` — validity window
+
+Any change to these fields invalidates the HMAC signature.
+
+## Confused deputy prevention
+
+Consider an agent that obtains a token for `billing.list_invoices` then passes it to a different agent. The second agent cannot use it because `verify()` checks that `token.principal_id == expected_principal_id`.
+
+The same principle extends to handles: every `Handle` carries the `principal_id`
+the original grant was issued to. When `handle.principal_id` is non-empty,
+`HandleStore.expand` rejects expansion unless the caller supplies a matching
+`principal_id`. **An omitted or empty `principal_id` is treated as a
+mismatch** (`HandleConstraintViolation`, `reason_code = HANDLE_PRINCIPAL_MISMATCH`),
+so a handle ID alone is not a bearer credential — proof of the original
+principal is always required. `Kernel.expand(..., principal=Principal(...))`
+forwards the principal automatically.
+
+## Handle expansion boundary
+
+Calling `kernel.expand(handle, query=...)` does not re-run the policy engine —
+the original grant already authorised the dataset, and handles are short-lived.
+But the grant's _constraints_ must still apply, otherwise an over-broad
+`expand` query would silently return data the original grant never covered.
+
+`HandleStore.expand` rechecks the constraints the kernel persists on the handle
+at creation time (`token.constraints`):
+
+| Constraint | Enforced behavior on expand |
+|------------|-----------------------------|
+| `max_rows` | A request `limit` larger than the cap raises `HandleConstraintViolation`. An unspecified or larger implicit limit is silently clamped. |
+| `allowed_fields` | A request `fields` entry that is not in `allowed_fields` raises `HandleConstraintViolation`. An unscoped expand applies `allowed_fields` as the default projection, so disallowed fields never leak. |
+| `scope` (e.g. `{"region": "eu"}`) | The scope filter is AND-merged into the request filter. A request filter that disagrees on a scoped dimension raises `HandleConstraintViolation`. |
+| `principal_id` | A mismatched `principal_id` parameter raises `HandleConstraintViolation` (`HANDLE_PRINCIPAL_MISMATCH`). |
+
+Errors carry stable `reason_code` values (`handle_constraint_violation`,
+`handle_principal_mismatch`) — assert on those, not on the message text.
+
+## Memory actions
+
+Capabilities tagged `SensitivityTag.MEMORY` represent durable agent memory
+(project notes, session handoff, learned context). Reads of project-scoped
+memory are allowed by default; reads of sensitive-scoped memory require an
+explicit role. Writes always require the `memory_writer` role (or `admin`)
+because they persist into future sessions.
+
+| Action | Required role | Denial reason code |
+|--------|---------------|--------------------|
+| `memory.read` with `scope["memory_scope"] == "project"` | none | — |
+| `memory.read` with `scope["memory_scope"] == "sensitive"` | `memory_reader_sensitive` or `admin` | `memory_sensitive_read_denied` |
+| `memory.write` (any scope) | `memory_writer` or `admin` | `memory_write_requires_writer` |
+| `memory.forget` (DESTRUCTIVE) | `admin` (then `memory_writer` or `admin`) | `missing_role`, then `memory_write_requires_writer` |
+
+To prevent durable memory content from leaking into the audit log, the kernel
+strips payload-like fields (`payload`, `content`, `value`, `memory`, `text`,
+`body`) from `ActionTrace.args` for any capability whose ID begins with
+`memory.`. Non-sensitive metadata keys (`key`, `id`, `scope`, ...) are
+preserved so audit can still confirm an action took place.
+
+## Security disclaimers
+
+> **v0.1 is not production-hardened for real authentication.**
+
+- HMAC tokens are tamper-evident but **not encrypted**. Do not put sensitive data in token fields.
+- The `AGENT_KERNEL_SECRET` must be kept secret. Rotate it if compromised.
+- The default `InMemoryDriver` has no persistence — suitable for testing only.
+- PII redaction is heuristic (regex-based). It is not a substitute for proper data governance.
+- Rate limiting is enforced per `(principal_id, capability_id)` pair using a sliding window.
+  Default limits: 60 READ / 10 WRITE / 2 DESTRUCTIVE invocations per 60-second window.
+  Principals with the `"service"` role receive 10× the default limits. Limits are
+  configurable via `DefaultPolicyEngine(rate_limits=...)`. There is no distributed or
+  persistent rate-limit state — limits reset on process restart.