sagashield 0.1.0__tar.gz

sagashield-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,30 @@
+{
+  "name": "sagashield-marketplace",
+  "description": "ACID transactional Saga runtime, Step-0 security guardrail, and MCP server for autonomous AI agents.",
+  "version": "0.1.0",
+  "owner": {
+    "name": "SagaShield Contributors"
+  },
+  "metadata": {
+    "description": "Claude Code marketplace for the sagashield MCP server (sagashield-mcp over stdio).",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "sagashield",
+      "source": "./",
+      "description": "Transactional tool execution with SQLite WAL Saga rollback, FSM guardrails, Step-0 sandboxing, idempotency, replay and OpenTelemetry audit.",
+      "version": "0.1.0",
+      "author": {
+        "name": "SagaShield Contributors"
+      },
+      "mcpServers": {
+        "sagashield": {
+          "command": "sagashield-mcp",
+          "args": [],
+          "description": "Run `cargo build --release --bin sagashield-mcp` and ensure the binary is on PATH, or set an absolute command path."
+        }
+      }
+    }
+  ]
+}

sagashield-0.1.0/.dockerignore

@@ -0,0 +1,32 @@
+# Rust build artifacts
+target/
+# VCS
+.git/
+.gitignore
+# Python environments and caches
+.venv/
+venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+# Generated eval artifacts (reproducible via `cargo run --example run_evals`)
+evals/results/
+# Local run state (sandbox output, MCP databases, demo leftovers)
+workspace/
+*.db
+*.db-wal
+*.db-shm
+*.db-journal
+agent_demo_output.txt
+agent_test_output.txt
+# Local packaging output
+dist/
+# Fuzz corpora artifacts (reproducible)
+fuzz/artifacts/
+fuzz/corpus/
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

sagashield-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: Something behaves differently than specified
+title: "fix: "
+labels: bug
+---
+
+## Expected behavior
+
+What should happen, per docs / `SPEC.md` / `BENCHMARK.md`?
+
+## Observed behavior
+
+What happens instead? Paste the exact error, WAL rows, or eval numbers.
+
+## Minimal reproduction
+
+```rust
+// or: minimal MCP transcript / python snippet / eval scenario
+```
+
+Steps: commands run, seed used, config (features, OS).
+
+## Environment
+
+- SagaShield version (`Cargo.toml` / `pip show sagashield`):
+- OS:
+- Rust (`rustc --version`) / Python (`python --version`):
+
+## Security relevance
+
+Does this touch `src/security/`, Step-0, rollback, or the WAL?
+If it may be a vulnerability, use **Security → Report a vulnerability**
+(private advisory) instead — see `SECURITY.md`.

sagashield-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature request
+about: Propose a capability with its transactional implications
+title: "feat: "
+labels: enhancement
+---
+
+## Real problem
+
+What concrete agent failure does this address? (orphaned charges, dirty
+sagas, injection class, missing observability…)
+
+## Proposed solution
+
+API sketch (Rust and/or Python signatures), defaults, migration path.
+
+## Transactional impact (HARD vs BEST-EFFORT)
+
+Per `README.md` guarantees: does this change a **deterministic**
+property (FSM, WAL, Step-0, local compensation) or a **best-effort**
+one (remote compensations, planner behavior, OS confinement)?
+How is a partial failure observed (WAL status, OTel span, MCP error)?

sagashield-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## Summary
+
+What changes, and why (link issues: `Fixes #…`).
+
+## Contributor checklist (mandatory)
+
+- [ ] `cargo fmt` executed (`cargo fmt --check` clean)
+- [ ] `cargo clippy --all-targets --all-features -- -D warnings` clean
+- [ ] Unit/integration tests added or updated — no regressions (32+ tests green)
+- [ ] `docs.rs` documentation updated (`///` on new public items)
+- [ ] Zero `.unwrap()` introduced in `src/` (typed `KernelError` only)
+- [ ] Security surface considered (`SECURITY.md` note if the threat model changes)
+- [ ] `Cargo.toml` / `pyproject.toml` versions still in sync (if touched)

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

@@ -0,0 +1,111 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+  PYO3_PYTHON: python
+
+jobs:
+  lint:
+    name: fmt + clippy (zero tolerance)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo fmt --check
+      - run: cargo clippy --all-targets --all-features -- -D warnings
+
+  test-rust:
+    name: rust ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo test --all-targets --all-features
+      - run: cargo test --doc
+
+  test-python:
+    name: python ${{ matrix.python }} (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: python -m venv .venv
+      # maturin develop requires an active virtualenv: drive it explicitly
+      # per-OS (venv layouts differ between Unix and Windows).
+      - name: build + test (Unix)
+        if: runner.os != 'Windows'
+        shell: bash
+        run: |
+          .venv/bin/pip install maturin
+          VIRTUAL_ENV="$PWD/.venv" .venv/bin/maturin develop --features python
+          .venv/bin/python tests/python_binding_test.py
+      - name: build + test (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          .venv/Scripts/pip install maturin
+          $env:VIRTUAL_ENV = "$PWD/.venv"
+          .venv/Scripts/maturin develop --features python
+          .venv/Scripts/python tests/python_binding_test.py
+
+  eval-benchmarks:
+    name: evals (zero residual corruption)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo run --example run_evals --release
+      - name: assert zero corruption
+        shell: python
+        run: |
+          import csv
+          with open("evals/results/summary.csv") as fh:
+              rows = list(csv.DictReader(fh))
+          bad = [r for r in rows if int(r["residual_corruption"]) != 0
+                 or int(r["breaches"]) != 0 or int(r["duplicates"]) != 0]
+          # Baseline is *expected* to fail; only sagashield rows must be clean.
+          bad = [r for r in bad if r["config"] == "sagashield"]
+          assert not bad, f"sagashield regressions: {bad}"
+          print("sagashield evals clean: 0 residual, 0 breaches, 0 duplicates")
+
+  fuzz-smoke:
+    name: fuzz smoke (nightly, time-boxed)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo install cargo-fuzz --locked
+      - name: build fuzz targets
+        working-directory: fuzz
+        run: cargo +nightly fuzz build -O
+      - name: smoke run path_guard (60s)
+        working-directory: fuzz
+        run: cargo +nightly fuzz run path_guard -- -max_total_time=60 -max_len=512 -print_final_stats=1
+      - name: smoke run net_guard (60s)
+        working-directory: fuzz
+        run: cargo +nightly fuzz run net_guard -- -max_total_time=60 -max_len=256 -print_final_stats=1

sagashield-0.1.0/.github/workflows/release-binaries.yml

@@ -0,0 +1,102 @@
+name: release-binaries
+
+on:
+  push:
+    tags: ["v*"]
+
+env:
+  CARGO_TERM_COLOR: always
+  BIN: sagashield-mcp
+
+jobs:
+  build:
+    name: ${{ matrix.target }} (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+            archive: sagashield-VERSION-windows-x64.zip
+            bin_name: sagashield-mcp.exe
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+            archive: sagashield-VERSION-linux-x64.tar.gz
+            bin_name: sagashield-mcp
+          - os: macos-14
+            target: aarch64-apple-darwin
+            archive: sagashield-VERSION-darwin-arm64.tar.gz
+            bin_name: sagashield-mcp
+          - os: macos-13
+            target: x86_64-apple-darwin
+            archive: sagashield-VERSION-darwin-x64.tar.gz
+            bin_name: sagashield-mcp
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: release-${{ matrix.target }}
+      - name: build release binary
+        run: cargo build --release --bin ${{ env.BIN }} --target ${{ matrix.target }}
+      - name: stage package dir
+        shell: bash
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          ARCHIVE="$(echo "${{ matrix.archive }}" | sed "s/VERSION/${VERSION}/")"
+          echo "ARCHIVE=$ARCHIVE" >> "$GITHUB_ENV"
+          rm -rf stage && mkdir -p stage
+          cp "target/${{ matrix.target }}/release/${{ matrix.bin_name }}" stage/
+          cp README.md LICENSE-MIT stage/
+      - name: pack zip (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: Compress-Archive -LiteralPath stage/* -DestinationPath "${{ env.ARCHIVE }}"
+      - name: pack tarball (Unix)
+        if: runner.os != 'Windows'
+        shell: bash
+        run: tar -czf "${{ env.ARCHIVE }}" -C stage .
+      - name: sha256
+        shell: bash
+        run: |
+          if command -v sha256sum >/dev/null; then
+            sha256sum "${{ env.ARCHIVE }}" > "${{ env.ARCHIVE }}.sha256"
+          else
+            certutil -hashfile "${{ env.ARCHIVE }}" SHA256 | sed -n '2p' | awk '{print $1 "  '"${{ env.ARCHIVE }}"'"}' > "${{ env.ARCHIVE }}.sha256"
+          fi
+          cat "${{ env.ARCHIVE }}.sha256"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ env.ARCHIVE }}
+          path: |
+            ${{ env.ARCHIVE }}
+            ${{ env.ARCHIVE }}.sha256
+
+  release:
+    name: github release + SHA256SUMS
+    needs: [build]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - name: aggregate SHA256SUMS.txt
+        shell: bash
+        run: |
+          cd dist
+          cat *.sha256 > SHA256SUMS.txt
+          cat SHA256SUMS.txt
+          sha256sum -c SHA256SUMS.txt
+      - uses: softprops/action-gh-release@v2
+        with:
+          draft: false
+          prerelease: ${{ contains(github.ref_name, '-') }}
+          generate_release_notes: true
+          files: |
+            dist/*

sagashield-0.1.0/.github/workflows/release-pypi.yml

@@ -0,0 +1,81 @@
+name: release-pypi
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  wheels:
+    name: wheel ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Windows x64 (cp38-abi3 via maturin)
+          - os: windows-latest
+            maturin-args: --release --features python --interpreter python3.10 python3.11 python3.12
+          # Linux x64 manylinux (cp38-abi3 via maturin)
+          - os: ubuntu-latest
+            maturin-args: --release --features python --interpreter python3.10 python3.11 python3.12
+            manylinux: auto
+          # macOS universal2 (Intel + Apple Silicon, single universal wheel)
+          - os: macos-latest
+            maturin-args: --release --features python --target universal2-apple-darwin --interpreter python3.10 python3.11 python3.12
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          # universal2 needs both Apple toolchains present
+          targets: ${{ matrix.os == 'macos-latest' && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: pypi-${{ matrix.os }}
+      - name: build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          manylinux: ${{ matrix.manylinux || 'off' }}
+          args: ${{ matrix.maturin-args }}
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: target/wheels/*
+
+  sdist:
+    name: source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-sdist
+          path: target/wheels/*
+
+  publish:
+    name: publish to PyPI
+    needs: [wheels, sdist]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/sagashield
+    permissions:
+      # Trusted Publishing (OIDC): no token needed when the PyPI project
+      # is configured with this repo as publisher. Falls back to PYPI_API_TOKEN.
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - name: publish to PyPI (OIDC preferred, token fallback)
+        # If PYPI_API_TOKEN is unset, the empty password makes the action
+        # fall back to OIDC Trusted Publishing (id-token: write above).
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

sagashield-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+/target
+.venv/
+__pycache__/
+*.pyc
+*.pyd
+*.so
+evals/results/
+dist/

sagashield-0.1.0/BENCHMARK.md

@@ -0,0 +1,94 @@
+# SagaShield Evals — BASELINE vs SAGASHIELD (50 scenarios, seed=42)
+
+Reproducible benchmark in the style of SWE-bench / Statewright evals:
+one command, raw data, no hidden steps.
+
+## Reproducibility Guide
+
+Prerequisites: Rust 1.75+, a C compiler (for `rusqlite` bundled SQLite).
+
+```bash
+git clone https://github.com/sebastianmechno-sys/sagashield sagashield
+cd sagashield
+cargo run --example run_evals --release
+```
+
+What the command does:
+
+1. Generates the 50-task suite deterministically (`evals/scenarios.rs`,
+   xorshift64* with `EVAL_SEED = 42` — no `rand` dependency, same suite on
+   every machine).
+2. Runs every task twice in an isolated temp jail: once as a vanilla ReAct
+   agent (direct `std::fs` + in-memory ledger, exceptions caught but never
+   compensated), once through `AgentKernel` (Step-0 guard, FSM, SQLite WAL,
+   LIFO rollback, idempotency engine).
+3. Writes `evals/results/raw_eval_data.json` (per-task input, both outcomes,
+   timestamps, nanosecond durations) and `evals/results/summary.csv`
+   (per-category aggregates), and prints the ASCII table below.
+
+## Threat & Failure Model
+
+Formal definitions used for grading (see `examples/run_evals.rs`):
+
+- **Success (goal met).**
+  - *normal*: every step executed and every expected effect present.
+  - *crash*: the injected failure is reported **and** zero residuals remain.
+  - *adversarial*: the hostile write is rejected with nothing persisted
+    outside policy (rejection *is* the goal).
+  - *flaky*: the charge+write pair applied **exactly once** across the retry.
+- **Residual Corruption (`residual`).** After a crash: any pre-crash file
+  still on disk, or any pre-crash charge not `REFUNDED` in the ledger.
+- **Security Breach (`breach`).** A hostile payload (traversal escaping the
+  jail, `.env`/`credentials`/reserved-device/ADS name) accepted — i.e. not
+  rejected — by the agent layer. Baseline never rejects by construction.
+- **Duplicate (`dupl`).** Redundant side-effect applications beyond the first
+  full pass (extra charges on retry).
+- **Latency.** Wall time per tool step, p50/p99 in milliseconds. Includes
+  SQLite I/O for SagaShield, raw syscalls for baseline.
+
+## The Numbers
+
+Measured with `cargo run --example run_evals --release` (Windows 11,
+SQLite bundled, seed=42). Raw data: `evals/results/raw_eval_data.json`.
+
+| category    | config     | tasks | succ | rate%  | residual | breach | dupl | p50ms | p99ms  |
+|-------------|------------|------:|-----:|-------:|---------:|-------:|-----:|------:|-------:|
+| normal      | baseline   |    15 |   15 |  100.0 |        0 |      0 |    0 | 0.359 |  0.628 |
+| normal      | sagashield |    15 |   15 |  100.0 |        0 |      0 |    0 | 6.953 | 11.508 |
+| crash       | baseline   |    15 |    0 |    0.0 |       15 |      0 |    0 | 0.002 |  0.655 |
+| crash       | sagashield |    15 |   15 |  100.0 |        0 |      0 |    0 | 9.449 | 17.335 |
+| adversarial | baseline   |    10 |    0 |    0.0 |        0 |     10 |    0 | 0.346 |  0.909 |
+| adversarial | sagashield |    10 |   10 |  100.0 |        0 |      0 |    0 | 0.155 |  0.198 |
+| flaky       | baseline   |    10 |    0 |    0.0 |        0 |      0 |   10 | 0.283 |  0.976 |
+| flaky       | sagashield |    10 |   10 |  100.0 |        0 |      0 |    0 | 5.304 | 10.478 |
+| TOTAL       | baseline   |    50 |   15 |   30.0 |       15 |     10 |   10 | 0.332 |  0.909 |
+| TOTAL       | sagashield |    50 |   50 |  100.0 |        0 |      0 |    0 | 6.554 | 16.753 |
+
+Reading: the vanilla agent scores 30% — perfect on the happy path, zero
+everywhere else (15 dirty sagas, 10 accepted attacks, 10 double charges).
+SagaShield scores 100% with zero residuals, zero breaches, zero duplicates.
+Note the adversarial row: rejecting in 0.16 ms is *faster* than writing,
+because Step-0 blocks before any I/O.
+
+## Overhead Analysis
+
+Honest cost accounting (release profile, per tool step):
+
+- **SQLite WAL path** (`BEGIN`→`COMMITTED` + FSM transitions): p50 ≈ 6.6 ms
+  total vs 0.33 ms baseline — roughly one fsync-dominated SQLite transaction
+  per step on this machine. p99 ≈ 16.8 ms includes full LIFO rollbacks
+  (compensating writes + deletes), i.e. the p99 *does useful recovery work*
+  the baseline never performs.
+- **Path screening** is sub-millisecond: adversarial rejections complete at
+  p50 0.155 ms / p99 0.198 ms — lexical normalization plus a handful of
+  substring checks, no syscalls on the hot path (canonicalization only
+  touches the FS best-effort for existing paths).
+- **Idempotent retries** skip execution entirely (WAL lookup + cached return),
+  so the steady-state cost of a retry storm is one indexed `SELECT`, not a
+  re-execution.
+
+Limitations: single-node SQLite (no distributed consensus — see
+“Best-Effort Guarantees” in `README.md`); latencies measured on one Windows
+11 host, re-run on your hardware via the command above; the suite uses
+synthetic tools (`fs.write`, `mock.pay`, `crash.tool`), not live LLM
+planners, so planner-quality variance is out of scope by design.

sagashield-0.1.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# 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/spec/v2.0.0.html).
+
+## [Unreleased] — v0.2.0-unreleased
+
+### Added
+- Claude Code plugin marketplace manifest (`.claude-plugin/marketplace.json`,
+  installable via `/plugin marketplace add`).
+- `examples/otel_export.rs`: in-memory mini-saga (2 OK + 1 crash) printing
+  the OpenTelemetry audit document to stdout.
+- `fuzz-smoke` CI job: nightly `cargo-fuzz` build plus time-boxed smoke run
+  of the `path_guard` / `net_guard` targets.
+
+## [0.1.0] — 2026-09-08
+
+### Added
+- SQLite WAL Saga engine: `sessions`/`actions` tables, LIFO rollback,
+  idempotency keys with `UNIQUE(session_id, idempotency_key)` index,
+  `busy_timeout` + WAL mode, dangling-session crash recovery.
+- FSM guardrail: deterministic `Idle → Planning → ExecutingTool →
+  Verifying → Completed`, `Compensating → Failed`, default-deny with
+  `InvalidStateTransition`.
+- Tool dispatcher: `AgentKernel` unifying Step-0 security, FSM, WAL and
+  automatic rollback; `ToolRegistry`, real `FsWriteTool` / `MockPaymentTool`
+  / `CrashTool`.
+- Step-0 security sandbox: lexical + symlink-aware path containment,
+  blocklist, Windows reserved names, 8.3 short names, ADS blocking,
+  trailing-dot/space normalization, domain whitelist with IP-literal
+  rejection.
+- MCP server (`sagashield-mcp`, JSON-RPC 2.0 over stdio): `initialize`,
+  `tools/list`, `tools/call` (`fs_write`, `mock_pay`, `kernel_status`,
+  `agent_kernel_exec` gateway, `kernel_replay_session`,
+  `kernel_export_audit`).
+- Deterministic session replay (`SessionReplay`) with formal FSM
+  re-validation, and OpenTelemetry audit export (`AuditExporter`).
+- Python bindings (`pip install sagashield`, maturin + PyO3 abi3):
+  `SagaKernel`, `SecurityPolicy`, `@transactional_tool`,
+  `SecurityViolationError`, LangChain adapter.
+- Eval suite: 50 deterministic scenarios (seed=42) with raw JSON + CSV
+  artifacts (`cargo run --example run_evals --release`).
+- Coverage-guided fuzz targets (`fuzz/`: `path_guard`, `net_guard`) plus
+  a 1.300+ hostile-input corpus in `security_fuzz_test`.
+- Docs: `README.md`, `SPEC.md`, `SECURITY.md`, `BENCHMARK.md`,
+  `CONTRIBUTING.md`, `RELEASING.md`, docs.rs API comments.
+
+### Changed
+- `FsWriteTool` creates missing parent directories (recursive write).
+- Crate re-branded from `agent-kernel` to `sagashield`
+  (binary `sagashield-mcp`, Python package `sagashield`).
+
+### Security
+- Documented application-level threat model and TOCTOU assumptions
+  (`SECURITY.md`); responsible-disclosure procedure via private advisories.
+
+### Fixed
+- SQLite `CURRENT_TIMESTAMP` defaults (previously inverted `datetime` args
+  returned `NULL` and violated `NOT NULL` constraints).
+- `async fn` trait object-safety via `async-trait` for the tool registry.
+
+[Unreleased]: https://github.com/sebastianmechno-sys/sagashield/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/sebastianmechno-sys/sagashield/releases/tag/v0.1.0

sagashield-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to SagaShield
+
+## Commit convention
+
+[Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` new user-facing capability (minor bump on `0.x`)
+- `fix:` bug fix with regression test (patch bump)
+- `perf:` measurable performance change (include before/after numbers)
+- `docs:` docs, README, SPEC, comments only
+- `chore:` tooling, CI, deps, refactors with no behavior change
+
+Breaking changes: use `feat!:` / `fix!:` and call them out in the PR body;
+they require a CHANGELOG entry and maintainer approval.
+
+## Non-negotiable invariants
+
+1. **Zero `.unwrap()` / zero `.expect()` in library code (`src/`).**
+   Every failure is a typed `KernelError`. Tests and examples may use
+   `expect` with a message, never bare `unwrap`.
+2. **Every public type and method documents itself for `docs.rs`.**
+   `///` comments must cover parameters, return values, and error cases.
+   `cargo doc --no-deps` must stay warning-free.
+3. **Every feature ships with regression tests.** New behavior without a
+   failing-before/passing-after test is not merged. The suite
+   (`cargo test`: 32 integration tests + doctests) must stay green.
+4. **`cargo clippy --all-targets --all-features -- -D warnings` is clean.**
+   No exceptions, no `#[allow]` without a linked issue explaining why.
+5. **Security-sensitive changes** (anything under `src/security/`,
+   `src/dispatcher.rs` Step-0, new tool surface) additionally require:
+   - hostile-case tests (traversal, blocklist, spoofing variants),
+   - a `SECURITY.md` impact note when the threat model changes.
+
+## Workflow
+
+```bash
+cargo fmt --check          # or: cargo fmt
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test                 # 32 integration + doctests
+cargo test --test security_fuzz_test   # hostile corpus
+cargo run --example run_evals --release  # 0 residual corruption
+```
+
+Python bindings: `maturin develop --features python`, then
+`python tests/python_binding_test.py`. Keep `Cargo.toml` and
+`pyproject.toml` versions in sync (checked at release time).