sentinel-kernel 0.1.0__tar.gz

sentinel_kernel-0.1.0/.claude/agents/bsi-auditor.md

@@ -0,0 +1,12 @@
+# Agent: BSI Auditor
+
+Review code as if preparing for formal BSI IT-Grundschutz submission and VS-NfD certification.
+
+Scope: BSI IT-Grundschutz (APP.6, CON.1, CON.3, OPS.1.1.5) / VS-NfD /
+EU AI Act Art. 6, 9, 12, 13, 17 / DSGVO data minimisation.
+
+Blockers: US CLOUD Act exposure / hardcoded secrets / missing encryption /
+raw PII in traces / mandatory network call in air-gapped mode.
+
+Finding format: BSI-[YEAR]-[NNN] / Severity / Reference (e.g. APP.6.A3) /
+Description / Impact / Fix. Do not soften findings.

sentinel_kernel-0.1.0/.claude/agents/protocol-architect.md

@@ -0,0 +1,11 @@
+# Agent: Protocol Architect
+
+Ensure the integrity, sovereignty, and longevity of the Sentinel decision trace protocol.
+
+Ask for every decision:
+- Will this hold up in front of a BSI auditor?
+- Will this work air-gapped in a classified environment?
+- Will this still make sense when EU AI Act is enforced?
+
+Principles: Conservative. Standard formats only. Offline first. Immutability absolute.
+Direct. Quantify BSI impact. When you disagree, offer an alternative.

sentinel_kernel-0.1.0/.claude/agents/security-reviewer.md

@@ -0,0 +1,12 @@
+# Agent: Security Reviewer
+
+Review code for classified, air-gapped deployment.
+
+Think like an attacker who wants to:
+1. Exfiltrate traces from an air-gapped network
+2. Tamper with the audit trail
+3. Inject a policy that always returns ALLOW
+4. Compromise supply chain through a dependency
+
+Examine: trace integrity / policy injection / supply chain / air-gapped exfiltration.
+Output: attack vector / what attacker gains / specific fix / classified blocker YES/NO.

sentinel_kernel-0.1.0/.claude/commands/add-integration.md

@@ -0,0 +1,23 @@
+# /project:add-integration
+
+Scaffold a new AI framework or model provider integration.
+Usage: /project:add-integration [name]
+
+## Before writing any code
+Read docs/integration-guide.md. Answer and document in your PR:
+1. Does this framework send data to a US-owned service?
+2. Does it work fully offline?
+3. Does it introduce a US dependency in the critical path? If yes: stop.
+
+Note: for LangChain specifically, this integration is the explicit open
+alternative to proprietary platform connectors. Document this clearly.
+
+## What to build
+- sentinel/integrations/[name] — standard middleware interface, works offline
+- tests/integrations/test_[name] — trace emitted, DENY recorded, override linked, no-network test
+- examples/[name]_quickstart — under 30 lines, local storage only
+- Update README integrations table and docs/integration-guide.md
+
+## Non-negotiables
+No mandatory network call. No breaking change to storage interface.
+Sovereignty must be documentable — users must know what data goes where.

sentinel_kernel-0.1.0/.claude/commands/bsi-check.md

@@ -0,0 +1,35 @@
+# /project:bsi-check
+
+BSI IT-Grundschutz readiness check. Run before any formal BSI engagement.
+Usage: /project:bsi-check [file or "all"]
+
+## APP.6 — Software
+- [ ] No hardcoded credentials or secrets
+- [ ] Input validation on all public interfaces
+- [ ] Error messages do not leak internal state
+- [ ] All dependencies pinned to exact versions
+- [ ] No sensitive data in logs
+
+## CON.1 — Cryptography
+- [ ] Storage supports encryption at rest
+- [ ] Strong encryption for all network transport
+- [ ] No weak hash algorithms
+- [ ] Key management documented in docs/bsi-profile.md
+
+## CON.3 — Data protection
+- [ ] No raw PII in traces by default
+- [ ] Data minimisation applied
+- [ ] Data residency asserted in every trace
+- [ ] Deletion path exists and documented
+
+## OPS.1.1.5 — Backup
+- [ ] Traces exportable as NDJSON
+- [ ] Backup and restore documented
+- [ ] Air-gapped export works with no network
+
+## VS-NfD prerequisites
+- [ ] Air-gapped mode works end-to-end
+- [ ] No mandatory internet connectivity in critical path
+- [ ] Tested in network-isolated environment
+
+## Output: Severity (BLOCKER/HIGH/MEDIUM/LOW) + BSI reference + fix + blocks BSI YES/NO

sentinel_kernel-0.1.0/.claude/commands/protocol-review.md

@@ -0,0 +1,33 @@
+# /project:protocol-review
+
+Review a decision trace or trace-emitting code for EU AI Act compliance and BSI readiness.
+
+## Trace completeness — EU AI Act Art. 12 + 17
+- [ ] Unique trace ID, immutable after creation
+- [ ] Timestamp in UTC
+- [ ] Agent name and version
+- [ ] Model provider and version
+- [ ] Policy name, version, result (ALLOW / DENY / EXCEPTION)
+- [ ] Which rule triggered (if DENY)
+- [ ] Inputs hashed — no raw PII unless explicitly opted in
+- [ ] Output recorded
+- [ ] Sovereign scope: EU or LOCAL
+- [ ] Data residency asserted
+
+## Sovereignty
+- [ ] No US-controlled component in the critical path
+- [ ] Works with zero network connectivity
+- [ ] Data residency assertion independently verifiable
+
+## Policy evaluation
+- [ ] In-process — no remote call
+- [ ] Deterministic
+- [ ] DENY records which rule triggered
+- [ ] Human override creates a second trace entry linked to the original
+
+## Trace integrity
+- [ ] Cannot be modified after writing
+- [ ] Storage is append-only
+- [ ] Correction is a new entry — never an edit
+
+## Output: PASS / FAIL / NEEDS REVIEW + issues with location + suggested fix

sentinel_kernel-0.1.0/.claude/commands/rfc.md

@@ -0,0 +1,28 @@
+# /project:rfc
+
+Open an RFC for a significant or breaking change to the Sentinel protocol.
+
+## When required
+Any change to: trace schema, mandatory fields, storage interface,
+policy evaluation contract, sovereignty assertions.
+
+## RFC document: docs/rfcs/RFC-[NNN]-[title].md
+
+Status: DRAFT | UNDER REVIEW | ACCEPTED | REJECTED
+Author: / Date:
+
+### Summary (one paragraph)
+### Motivation
+### Proposal (before/after for schema changes)
+### Deployment context impact
+  - Air-gapped / classified:
+  - BSI certification path:
+  - EU AI Act compliance:
+### Migration
+### Open questions
+
+## Process
+1. GitHub Discussion linking the RFC
+2. 14-day comment period
+3. Maintainer vote
+4. Merge or close with rationale recorded

sentinel_kernel-0.1.0/.claude/commands/security-audit.md

@@ -0,0 +1,30 @@
+# /project:security-audit
+
+Security audit for classified deployment readiness.
+Think like an attacker targeting an air-gapped environment.
+Usage: /project:security-audit [file or "all"]
+
+## Trace integrity
+- Can a trace be modified after writing?
+- Is the audit trail append-only?
+- Hash or signature on stored traces?
+
+## Policy injection
+- Can untrusted input influence which policy is loaded?
+- Can policy evaluation be bypassed?
+- Is the policy path sanitised?
+
+## Secret handling
+- Secrets in logs, traces, or errors?
+- Sensitive values flowing into traces unredacted?
+
+## Supply chain
+- All dependencies pinned? Fetched over encrypted transport?
+- Any US-owned dependency in the critical path?
+
+## Air-gapped readiness
+- Unexpected outbound network calls?
+- DNS lookups that could leak information?
+- System works fully isolated?
+
+## Output: Severity + Location + Attack scenario + Fix + Classified blocker YES/NO

sentinel_kernel-0.1.0/.claude/rules/code-style.md

@@ -0,0 +1,13 @@
+# Code Style
+
+Trace correctness over performance. A missing trace is worse than a crash.
+Interfaces over implementations. Storage, policy eval, trace emission are interfaces.
+Offline first. No feature is complete until tested without network.
+No silent failures. No secrets in code, traces, or logs.
+
+Every public interface states:
+- What it does
+- Sovereignty guarantees it provides (or explicitly does not)
+- What happens with no network connection
+
+Use /project:rfc before any breaking change to the trace schema.

sentinel_kernel-0.1.0/.claude/rules/protocol-conventions.md

@@ -0,0 +1,36 @@
+# Protocol Conventions — Decision Trace Schema
+
+## Mandatory fields
+```
+trace_id          Unique. Immutable after creation.
+parent_trace_id   For nested decisions. Null if top-level.
+timestamp         ISO 8601 UTC.
+latency_ms        Wall clock time of the full decision.
+agent             Name of the agent or function.
+agent_version     Version string. Null if unavailable.
+model             Model identifier.
+model_version     Version. Null if unavailable.
+policy            Policy name.
+policy_version    Policy version. Null if not versioned.
+policy_result     ALLOW | DENY | EXCEPTION_REQUIRED.
+policy_rule       Rule that triggered. Null only if ALLOW.
+inputs_hash       SHA-256 of serialised inputs. Always present.
+inputs_raw        Raw inputs. Opt-in only. Never default.
+output            The decision output.
+override_by       Who overrode. Null if no override.
+override_reason   Reason. Null if no override.
+override_at       Timestamp. Null if no override.
+sovereign_scope   EU | LOCAL | CUSTOM.
+data_residency    Where the trace is stored. Human-readable.
+schema_version    Schema version.
+```
+
+## Immutability
+A trace is never edited. Corrections and overrides are new entries.
+
+## Portability
+Traces export as NDJSON. No binary formats. No proprietary encoding.
+
+## Schema changes
+Optional fields: no RFC required.
+Removing/renaming or new mandatory fields: RFC required.

sentinel_kernel-0.1.0/.claude/rules/sovereignty-rules.md

@@ -0,0 +1,29 @@
+# EU Sovereignty Rules — Non-Negotiable
+
+## The three laws
+
+### 1. No US CLOUD Act exposure in the critical path
+Any US-incorporated entity in the trace emission path creates CLOUD Act
+exposure regardless of server location. An EU data centre run by a US
+company does not solve this. US services may appear only in optional
+integrations, clearly marked as non-sovereign.
+
+### 2. Air-gapped must always work
+Local file storage is the reference deployment for classified environments.
+Test offline before marking any feature complete.
+
+### 3. Apache 2.0, forever
+No licence change. No CLA enabling relicensing. No closed-source features.
+
+## Before adding any dependency (document in PR every time)
+1. Who is the parent company?
+2. US-incorporated?
+3. Makes network calls at runtime?
+4. Works pinned and offline?
+If 2 and 3 are both yes: not in the critical path.
+
+## What EU-sovereign means
+Does NOT mean: cannot use code written by Americans.
+DOES mean: no US company has runtime access to decision traces.
+DOES mean: EU law governs all data at rest and in transit.
+DOES mean: a regulator can independently verify the data residency claim.

sentinel_kernel-0.1.0/.claude/rules/testing.md

@@ -0,0 +1,18 @@
+# Testing
+
+## Five mandatory tests per feature
+1. Happy path
+2. Offline — local storage, zero network
+3. Policy DENY — blocks execution, DENY recorded with rule name
+4. Override — second linked trace entry, original untouched
+5. EU AI Act fields — all mandatory fields present and correct
+
+## Sovereignty tests — CI blockers (every PR)
+- test_offline_mode_emits_complete_trace
+- test_all_eu_ai_act_fields_present
+- test_trace_is_immutable_after_write
+- test_deny_records_triggering_rule
+- test_override_creates_linked_entry
+
+## Coverage targets
+Core trace emission: 95%+ / Storage interface: 90%+ / Integrations: 80%+

sentinel_kernel-0.1.0/.claude/settings.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git diff:*)", "Bash(git log:*)", "Bash(git status:*)",
+      "Bash(git add:*)", "Bash(git commit:*)", "Bash(git push:*)",
+      "Bash(grep:*)", "Bash(find:*)", "Bash(cat:*)", "Bash(ls:*)",
+      "Bash(mkdir:*)", "Bash(mv:*)", "Bash(cp:*)",
+      "Read(**)",
+      "Write(sentinel/**)", "Write(tests/**)", "Write(docs/**)",
+      "Write(examples/**)", "Write(policies/**)",
+      "Write(.claude/**)", "Write(CLAUDE.md)"
+    ],
+    "deny": [
+      "Write(.env)", "Write(.env.*)", "Write(**/*.pem)", "Write(**/*.key)"
+    ]
+  }
+}

sentinel_kernel-0.1.0/.claude/skills/bsi-compliance/SKILL.md

@@ -0,0 +1,16 @@
+# SKILL: BSI Compliance Check
+
+## Auto-trigger when
+New dependency added / encryption touched / offline path changed / mandatory trace field modified.
+
+## Checks
+- Secrets: no hardcoded credentials, no sensitive values in traces or logs
+- EU AI Act fields: mandatory fields present after schema changes? Any removed without RFC? BLOCK.
+- Air-gapped: works with no network? New mandatory outbound call? BLOCK.
+- Dependencies: US-owned? Makes network calls? Flag both.
+
+## Output
+BSI-SKILL: PASS | WARN | BLOCK
+[WARN] new dependency — check ownership and network behaviour
+[BLOCK] mandatory trace field removed without RFC
+[BLOCK] mandatory network call added — breaks air-gapped deployment

sentinel_kernel-0.1.0/.claude/skills/sovereignty-check/SKILL.md

@@ -0,0 +1,17 @@
+# SKILL: Sovereignty Check
+
+## Auto-trigger when
+New import or dependency / network call written / storage write path changed.
+
+## Checks
+- Network calls: destination? In critical path? US-owned? Can disable offline?
+  If US-owned and in critical path: VIOLATION.
+- Data residency: data_residency correct? sovereign_scope accurate?
+  Can a regulator independently verify?
+- Offline: works with no network?
+
+## Output
+SOVEREIGNTY-SKILL: SOVEREIGN | DEGRADED | VIOLATION
+[OK] storage is local — sovereign
+[WARN] optional integration uses non-sovereign service — marked
+[VIOLATION] dependency sends data to US-owned service in critical path

sentinel_kernel-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check sentinel/
+
+      - name: Type check
+        run: mypy sentinel/ --ignore-missing-imports || true
+
+      - name: Test with coverage
+        run: pytest tests/ -v --cov=sentinel --cov-report=term-missing --cov-fail-under=75
+
+  quickstart:
+    name: Quickstart smoke test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install -e .
+      - run: python examples/minimal_trace.py
+      - run: python examples/policy_deny.py

sentinel_kernel-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+*.db
+*.sqlite
+.DS_Store
+
+# Claude Code — private files, never commit
+CLAUDE.local.md
+.claude/settings.local.json

sentinel_kernel-0.1.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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/).
+
+## [Unreleased]
+
+### Fixed
+- `SQLiteStorage.save()` now uses `INSERT` instead of `INSERT OR REPLACE` — duplicate `trace_id` raises `IntegrityError` instead of silently overwriting. Traces are now genuinely append-only in SQLite.
+- `DecisionTrace.from_dict()` now reconstructs `policy_evaluation` and `human_override` from stored JSON. Previously these were lost on deserialization.
+
+### Added
+- `tests/test_eu_ai_act_fields.py` — 12 tests verifying EU AI Act Article 12/13/14 field presence on real traces
+
+## [0.1.0] — 2026-04-01
+
+Initial public alpha release.
+
+### Added
+- `Sentinel` class with `@sentinel.trace` decorator (sync and async)
+- `DecisionTrace` dataclass with SHA-256 input/output hashing
+- `PolicyEvaluation` model with ALLOW / DENY / EXCEPTION / NOT_EVALUATED
+- `HumanOverride` model for recording human intervention
+- `DataResidency` enum (LOCAL, EU, EU-DE, EU-FR, air-gapped)
+- `SQLiteStorage` backend — zero dependencies, works everywhere
+- `FilesystemStorage` backend — NDJSON append-only, designed for air-gapped environments
+- `StorageBackend` abstract interface for custom backends
+- `NullPolicyEvaluator` (default), `SimpleRuleEvaluator` (Python callables), `LocalRegoEvaluator` (OPA binary)
+- Trace query interface with project, agent, and policy result filters
+- `sentinel.span()` async context manager for manual trace control
+- Schema version 1.0.0 draft
+- Documentation: schema reference, EU AI Act mapping, integration guide, BSI profile
+- Apache 2.0 license
+
+### Not yet implemented
+- CLI (`sentinel` command is declared but not yet implemented)
+- LangChain / LangGraph integration
+- PostgreSQL storage backend
+- OpenTelemetry export
+- Test suite (in progress)

sentinel_kernel-0.1.0/CLAUDE.md

@@ -0,0 +1,76 @@
+# Sentinel — Claude Instructions
+
+## What this project is
+
+Sentinel is an EU-sovereign AI decision middleware kernel.
+It sits in the execution path of any AI agent and turns every decision
+into a structured, auditable, sovereign artifact.
+
+The sovereignty is the product. Everything else is implementation detail.
+
+- License: Apache 2.0, permanently
+- Governance: Linux Foundation Europe intended (formal engagement planned with v1.0)
+- Target: BSI reference implementation for EU-sovereign AI decision infrastructure
+
+## Why this exists
+
+The leading AI decision platforms are excellent. They are also American,
+fully subject to the US CLOUD Act. For European regulated industries —
+defence, critical infrastructure, financial services, healthcare — a
+US-owned decision record layer is a structural barrier, not a preference.
+
+EU AI Act Art. 12, 13, 17 mandates audit trails for high-risk AI from
+2 August 2026. No US provider can deliver this from their jurisdiction.
+Sentinel is the open, sovereign answer.
+
+Proprietary platforms are building developer ecosystems with SDKs,
+community registries, and framework connectors — all locked to their
+ontology and jurisdiction. Sentinel is the alternative: open, portable,
+sovereign. The v0.3 LangChain integration is the explicit open alternative
+to proprietary platform connectors.
+
+## The three invariants
+
+1. No US CLOUD Act exposure in the critical path.
+2. Air-gapped must always work. If it breaks offline, it is not complete.
+3. Apache 2.0, forever. No enterprise edition. No licence key. No relicensing.
+
+## The decision trace — mandatory fields
+
+- Unique trace ID (immutable after creation)
+- Timestamp in UTC
+- Agent name and version
+- Model provider and version
+- Policy name, version, result (ALLOW / DENY / EXCEPTION)
+- Which rule triggered (if DENY)
+- Hashed inputs — never raw PII by default
+- Output
+- Sovereign scope (EU / LOCAL)
+- Data residency assertion
+
+These are the EU AI Act Art. 12/13/17 compliance evidence and the BSI audit trail.
+
+## Before adding any dependency — document in PR
+
+1. Who is the parent company?
+2. US-incorporated and subject to CLOUD Act?
+3. Makes network calls at runtime?
+4. Works fully offline?
+
+If 2 and 3 are both yes: not in the critical path.
+
+## Code principles
+
+- Offline-first — no feature is complete until tested without network
+- No proprietary formats — traces must be portable
+- Storage is pluggable — no backend is mandatory
+- Breaking changes to the trace schema require an RFC (/project:rfc)
+- Never swallow errors silently — a missing trace is worse than a crash
+
+## Deployment contexts
+
+- Air-gapped classified (no network, local storage only)
+- On-premise enterprise (EU-sovereign infrastructure)
+- Sovereign edge (EU data residency required)
+
+Test against the most constrained context first.

sentinel_kernel-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,128 @@
+# Contributing to Sentinel
+
+Contributions are welcome from individuals, research institutions,
+and organisations.
+
+---
+
+## Getting started
+
+1. Fork the repository
+2. Create a feature branch from `main`
+3. Make your changes
+4. Run the test suite: `pytest`
+5. Open a pull request
+
+**First contribution?** Look for issues labelled
+[`good first issue`](../../issues?q=label%3A%22good+first+issue%22).
+
+---
+
+## Code of conduct
+
+Be respectful, constructive, and professional. Sentinel is built by
+a diverse community across industries, institutions, and countries.
+Contributions are evaluated on their technical merit.
+
+---
+
+## Pull request requirements
+
+Every PR must:
+
+1. **Pass all existing tests** — no regressions.
+2. **Include tests for new functionality** — see test requirements below.
+3. **Document sovereignty posture** — if your change introduces a dependency,
+   network call, or storage path change, answer the sovereignty checklist
+   in your PR description.
+
+### Sovereignty checklist (for PRs that add dependencies or network calls)
+
+- [ ] Who is the parent company of the dependency?
+- [ ] Is it US-incorporated and subject to the CLOUD Act?
+- [ ] Does it make network calls at runtime?
+- [ ] Does it work fully offline?
+
+If the dependency is US-owned and makes network calls: it cannot be in the
+critical path. It may be offered as an optional, clearly-labelled integration.
+
+### Test requirements
+
+Every new feature must include at minimum:
+
+1. Happy path test
+2. Offline test (local storage, zero network)
+3. Policy DENY test (DENY recorded with rule name)
+4. Override test (second linked trace entry, original untouched)
+5. EU AI Act fields test (all mandatory fields present)
+
+Coverage targets: core trace emission 95%+, storage interface 90%+,
+integrations 80%+.
+
+---
+
+## Integration contributions
+
+Adding a new framework or model provider integration? Read
+[`docs/integration-guide.md`](docs/integration-guide.md) first.
+
+Every integration must:
+
+- Document its sovereignty posture
+- Work offline or clearly label which features require network
+- Include a quickstart example under 30 lines
+- Pass the standard integration test suite
+
+---
+
+## RFC process
+
+Significant changes to the following require an RFC before implementation:
+
+- Trace schema (mandatory fields, field semantics)
+- Storage interface
+- Policy evaluation contract
+- Sovereignty assertions
+
+### How to open an RFC
+
+1. Create a document at `docs/rfcs/RFC-[NNN]-[title].md`
+2. Open a GitHub Discussion linking your RFC
+3. A 14-day comment period follows
+4. Maintainers vote to accept or reject
+5. The decision and rationale are permanently recorded in the Discussion
+
+### What does not require an RFC
+
+- Bug fixes
+- New optional trace fields
+- New storage backend implementations
+- New integration modules
+- Documentation improvements
+- Test additions
+
+---
+
+## Design partner issues
+
+If your organisation has a deployment context — regulated industry, classified
+environment, public sector — that tests Sentinel's architecture, open an issue
+on GitHub to discuss design partner status.
+
+---
+
+## Community
+
+- **GitHub Discussions:** For RFCs, architecture questions, and design partner conversations
+- Community channels TBD
+
+---
+
+## License
+
+By contributing to Sentinel, you agree that your contributions will be
+licensed under the Apache License 2.0. See [LICENSE](LICENSE) for the
+full licence text.
+
+No Contributor License Agreement (CLA) is required. No contribution grants
+any party the right to relicence this software.