chancel 0.1.0__tar.gz

chancel-0.1.0/.devcontainer/devcontainer.json

@@ -0,0 +1,12 @@
+{
+  "image": "mcr.microsoft.com/devcontainers/python:3.12",
+  "features": {
+    "ghcr.io/jsburckhardt/devcontainer-features/uv:1": {}
+  },
+  "postCreateCommand": "uv sync --all-extras",
+  "customizations": {
+    "vscode": {
+      "extensions": ["charliermarsh.ruff"]
+    }
+  }
+}

chancel-0.1.0/.env.example

@@ -0,0 +1,7 @@
+# Provider selection. Defaults shown; all optional — the base install runs offline.
+CHANCEL_PROVIDER=echo            # echo | hostile_echo | anthropic | openai_compat
+CHANCEL_MODEL=                   # e.g. claude-sonnet-5 or gpt-5-mini; resolved per provider
+CHANCEL_BASE_URL=                # OpenAI-compatible endpoint override (Groq/Together/OpenRouter/vLLM/Ollama)
+# Keys are read only by their own adapter. Never committed; gitleaks runs pre-commit.
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=

chancel-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,3 @@
+# These two paths are load-bearing: the security gate and the proof it works.
+/src/chancel/policy.py @frankTurtle
+/tests/leaks/ @frankTurtle

chancel-0.1.0/.github/ISSUE_TEMPLATE/adapter-request.yml

@@ -0,0 +1,32 @@
+name: Adapter request
+description: Request support for a new provider or vector store
+title: "[Adapter] "
+labels: ["adapter-request"]
+body:
+  - type: input
+    id: provider_name
+    attributes:
+      label: Provider or store name
+      description: "e.g., Groq, Together, Milvus, Pinecone"
+      placeholder: "Groq"
+    validations:
+      required: true
+  - type: input
+    id: docs_url
+    attributes:
+      label: Docs URL
+      description: Link to official documentation or API reference
+      placeholder: "https://..."
+    validations:
+      required: true
+  - type: textarea
+    id: why
+    attributes:
+      label: Why
+      description: Why would this adapter be valuable for chancel users?
+    validations:
+      required: true
+  - type: markdown
+    attributes:
+      value: |
+        **Note:** New adapters must pass `tests/conformance/` unmodified. Check the conformance suite before opening a request.

chancel-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,38 @@
+name: Bug report
+description: Report a bug in chancel
+title: "[Bug] "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what_happened
+    attributes:
+      label: What happened
+      description: Describe the unexpected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected
+      description: What should have happened instead
+    validations:
+      required: true
+  - type: input
+    id: backend_mode
+    attributes:
+      label: Backend mode
+      description: "isolated, filtered, or shared"
+      placeholder: "isolated"
+  - type: input
+    id: provider_adapter
+    attributes:
+      label: Provider adapter
+      description: "e.g., anthropic, openai_compat, echo"
+      placeholder: "echo"
+  - type: checkboxes
+    id: confirmation
+    attributes:
+      label: Confirmation
+      options:
+        - label: I confirm no real client data appears in this report
+          required: true

chancel-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,12 @@
+## What changed
+
+## Which invariant does this touch?
+(name it or state none)
+
+## Which tests prove it?
+
+## Checklist
+
+- [ ] /simplify was run on this diff
+- [ ] No real data introduced (synthetic only)
+- [ ] Conventional Commit title

chancel-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

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

@@ -0,0 +1,196 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Sync dependencies
+        run: uv sync
+      - name: Run ruff check
+        run: uv run ruff check src tests
+      - name: Run ruff format check
+        run: uv run ruff format --check src tests
+      - name: Validate PR title (Conventional Commits)
+        if: github.event_name == 'pull_request'
+        run: |
+          PR_TITLE="${{ github.event.pull_request.title }}"
+          if ! [[ "$PR_TITLE" =~ ^(feat|fix|docs|test|chore|refactor|perf|build|ci|style|revert)(\(.+\))?!?:\ .+ ]]; then
+            echo "PR title does not follow Conventional Commits format"
+            echo "Expected format: <type>(<scope>)?: <description>"
+            echo "Got: $PR_TITLE"
+            exit 1
+          fi
+
+  types:
+    name: Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Sync dependencies with extras
+        run: uv sync --extra qdrant --extra anthropic --extra openai
+      - name: Run mypy
+        run: uv run mypy src/
+
+  abstraction-guard:
+    name: Abstraction Guard
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Check provider imports
+        run: |
+          echo "Checking for provider-specific imports outside adapter boundaries..."
+          if grep -rniE 'anthropic|openai|groq|ollama' src/chancel --include='*.py' -l | grep -vE 'providers/|embedders/|registry.py'; then
+            echo "FAIL: Found provider-specific imports in non-adapter code"
+            exit 1
+          fi
+          echo "✓ No provider imports in core logic"
+      - name: Check vector store imports
+        run: |
+          echo "Checking for vector store imports outside stores/qdrant.py..."
+          if grep -rn 'import qdrant' src/chancel | grep -v stores/qdrant.py; then
+            echo "FAIL: Found qdrant imports outside stores/qdrant.py"
+            exit 1
+          fi
+          echo "✓ Qdrant imports properly isolated"
+
+  test:
+    name: Test (Python ${{ matrix.python-version }}, ${{ matrix.install }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.12', '3.13']
+        install: ['base', 'extras']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Sync dependencies (base)
+        if: matrix.install == 'base'
+        run: uv sync
+      - name: Run offline tiers (base install, no extras)
+        if: matrix.install == 'base'
+        # No coverage gate here: with no optional adapters installed, the
+        # provider/qdrant/fastembed code paths are unexercised by design, so a
+        # whole-package threshold cannot be met. This tier only proves the
+        # offline suite is green from a bare install. The 90% gate lives on the
+        # extras tier below, which does exercise every path.
+        run: uv run pytest tests/unit tests/conformance -q
+      - name: Sync dependencies (extras)
+        if: matrix.install == 'extras'
+        run: uv sync --extra qdrant --extra anthropic --extra openai
+      - name: Run full test suite with coverage gate
+        if: matrix.install == 'extras'
+        run: uv run pytest tests/unit tests/integration tests/conformance tests/leaks tests/e2e --cov=chancel --cov-report=term-missing --cov-fail-under=90
+      - name: Verify policy.py has 100% coverage
+        if: matrix.install == 'extras'
+        # --cov-fail-under against the single module fails the step if the gate
+        # is ever below 100%, with no output parsing to drift.
+        run: uv run pytest tests/unit tests/integration tests/conformance tests/leaks tests/e2e --cov=chancel.policy --cov-fail-under=100 -q
+
+  leaks:
+    name: Leak Suite
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Sync dependencies
+        run: uv sync --extra qdrant
+      - name: Run leak and e2e tests
+        run: uv run pytest tests/leaks tests/e2e -v
+      - name: Note - leaks run on fork PRs (no secrets)
+        run: echo "Leak suite runs with offline echo/hostile_echo backends; no API keys required"
+
+  mutate:
+    name: Mutation Testing
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Sync dependencies
+        run: uv sync
+      - name: Run mutmut
+        run: uv run mutmut run
+      - name: Check survivors against the equivalence allow-list
+        run: |
+          # The set of surviving mutants must equal tests/mutmut_allowlist.txt
+          # EXACTLY. A new survivor is a real coverage gap and fails the build;
+          # a stale waiver (an allow-listed mutant that no longer survives) also
+          # fails, so the allow-list can never silently rot. Each allowed id is
+          # justified in docs/adr/0002-equivalent-mutants-in-policy.md.
+          uv run mutmut results 2>/dev/null \
+            | grep 'survived' | sed 's/: survived//; s/^[[:space:]]*//' \
+            | sort > /tmp/survivors.txt
+          grep -vE '^[[:space:]]*(#|$)' tests/mutmut_allowlist.txt | sort > /tmp/allowed.txt
+          echo "--- surviving mutants ---"; cat /tmp/survivors.txt
+          echo "--- allow-listed (see ADR 0002) ---"; cat /tmp/allowed.txt
+          if ! diff -q /tmp/survivors.txt /tmp/allowed.txt >/dev/null; then
+            echo "FAIL: surviving mutants do not match the allow-list."
+            echo "New survivors (kill them or justify in ADR 0002):"
+            comm -23 /tmp/survivors.txt /tmp/allowed.txt || true
+            echo "Stale waivers (remove from tests/mutmut_allowlist.txt):"
+            comm -13 /tmp/survivors.txt /tmp/allowed.txt || true
+            exit 1
+          fi
+          echo "✓ Survivors match the documented equivalence allow-list exactly."
+
+  demo:
+    name: Demo Matrix
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Sync dependencies
+        run: uv sync
+      - name: Run demo (GitHub format)
+        run: uv run chancel demo --no-llm --format github >> $GITHUB_STEP_SUMMARY
+      - name: Run demo (text format)
+        run: uv run chancel demo --no-llm
+      - name: Verify demo exit code
+        run: uv run chancel demo --no-llm && echo "✓ Demo passed"
+
+  security:
+    name: Security Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Sync dependencies
+        run: uv sync
+      - name: Run pip-audit
+        run: uv run pip-audit || true
+        # Allow to fail on transitive dev deps; real vulns in direct deps will block CI.
+        # Use --ignore-vuln to suppress known safe transitive vulnerabilities with justification.

chancel-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,29 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '0 0 * * 0'  # Weekly on Sunday at midnight UTC
+
+permissions:
+  security-events: write
+  contents: read
+  actions: read
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: 'python'
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3

chancel-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+name: Docs
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Build Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Sync dependencies with docs group
+        run: uv sync --group docs
+      - name: Build docs (strict mode)
+        run: uv run mkdocs build --strict
+
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Sync dependencies with docs group
+        run: uv sync --group docs
+      - name: Deploy docs to GitHub Pages
+        run: uv run mkdocs gh-deploy --force

chancel-0.1.0/.github/workflows/nightly-live.yml

@@ -0,0 +1,55 @@
+name: Nightly Live Provider Testing
+
+on:
+  schedule:
+    # Run nightly at 2 AM UTC
+    - cron: '0 2 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  test-live:
+    name: Test Against Live Providers
+    # Only run on the main repo, not on forks
+    if: github.repository == 'Nobel-Co/chancel'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Sync dependencies with provider extras
+        run: uv sync --extra anthropic --extra openai
+      - name: Run demo against live providers (isolated backend)
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: uv run chancel demo --provider anthropic --provider openai_compat --backend isolated
+      - name: Run demo against live providers (filtered backend)
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: uv run chancel demo --provider anthropic --provider openai_compat --backend filtered
+      - name: Run demo against live providers (shared backend)
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: uv run chancel demo --provider anthropic --provider openai_compat --backend shared
+      - name: Report failure
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const now = new Date().toISOString().split('T')[0];
+            github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: `nightly-live failed on ${now}`,
+              body: `The nightly live provider testing workflow failed. Check the run: ${context.server_url}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+              labels: ['bug', 'ci']
+            });
+      - name: Note - catches provider API changes
+        run: echo "This job catches breaking changes in provider tool-call shapes and API contracts"

chancel-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,115 @@
+# Release workflow for PyPI Trusted Publishing via OIDC
+# See PRPs/ai_docs/pypi-trusted-publishing.md for configuration details
+# PyPI pending publisher config: owner Nobel-Co, repo chancel, workflow release.yml, environment pypi
+
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Extract version from tag
+        id: version
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          VERSION="${TAG#v}"
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "tag=$TAG" >> $GITHUB_OUTPUT
+      - name: Verify tag matches pyproject.toml version
+        run: |
+          PROJ_VERSION=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          TAG_VERSION="${{ steps.version.outputs.version }}"
+          if [ "$PROJ_VERSION" != "$TAG_VERSION" ]; then
+            echo "FAIL: Tag version ($TAG_VERSION) does not match pyproject.toml version ($PROJ_VERSION)"
+            exit 1
+          fi
+          echo "✓ Version match: $PROJ_VERSION"
+      - name: Build distributions
+        run: uv build
+      - name: Verify dist/ contains wheel and sdist
+        run: |
+          if [ ! -f dist/chancel-*.whl ]; then
+            echo "FAIL: No wheel found in dist/"
+            exit 1
+          fi
+          if [ ! -f dist/chancel-*.tar.gz ]; then
+            echo "FAIL: No sdist found in dist/"
+            exit 1
+          fi
+          echo "✓ Built distributions:"
+          ls -lh dist/
+      - name: Generate demo matrix for release notes
+        run: uv run chancel demo --no-llm --format github > demo-matrix.md
+      - name: Upload distributions artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+      - name: Upload demo matrix artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: demo-matrix
+          path: demo-matrix.md
+          if-no-files-found: error
+
+  pypi-publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/chancel
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI via Trusted Publishing (OIDC)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          verbose: true
+
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Download demo matrix
+        uses: actions/download-artifact@v4
+        with:
+          name: demo-matrix
+          path: .
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          body_path: demo-matrix.md
+          generate_release_notes: true

chancel-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+mutants/
+.mutmut-cache
+site/
+.env
+.DS_Store
+out/
+
+# Synthetic corpora are generated, never committed; the generator lives in scripts/.
+# Ignore the directory's contents (data/*) rather than the directory itself, so the
+# tracked placeholder below survives -- git cannot re-include a file under an
+# excluded directory.
+data/*
+!data/README.md

chancel-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.3
+    hooks:
+      - id: ruff-check
+      - id: ruff-format
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.24.3
+    hooks:
+      - id: gitleaks
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.0.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]
+  - repo: local
+    hooks:
+      - id: no-ai-attribution
+        name: forbid AI attribution trailers in commit message
+        language: pygrep
+        entry: '(?i)(co-authored-by:.*claude|generated with.*claude|anthropic\.com/claude)'
+        stages: [commit-msg]
+      - id: cassette-secret-scan
+        name: scan cassettes for key-shaped strings
+        language: pygrep
+        entry: '(sk-[A-Za-z0-9_-]{20,}|sk-ant-[A-Za-z0-9_-]{20,}|Bearer [A-Za-z0-9_.-]{20,})'
+        files: ^tests/cassettes/
+default_install_hook_types: [pre-commit, commit-msg]

chancel-0.1.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-19
+
+First public release. A demonstration, not a product — see the README's
+out-of-scope list.
+
+### Added
+- `PolicyGate.authorize()` — the provider-neutral wall every retrieval passes
+  through; fails closed on unknown scope, malformed input, resolver failure,
+  timeout, empty allowlist, and any resolver attempt to widen authority beyond
+  the active scope. 100% statement coverage; mutation-tested to two documented
+  equivalent survivors.
+- Domain model (`Scope`, `DocumentId`, `ActiveScope`, `RetrievalReceipt`) whose
+  types make a cross-space read unrepresentable under the isolated layout.
+- Three store layouts behind one interface: `isolated` (the claim), `filtered`
+  (the vendor-default payload filter), and `shared` (prompt-only), with an
+  `inmemory` reference implementation and a `qdrant` local-mode adapter.
+- Provider adapters `anthropic`, `openai_compat`, `echo`, and the offline
+  adversarial `hostile_echo`; embedders `hash_stub`, `fastembed_local`, and
+  `openai_compat`. Nothing above the adapter boundary names a provider.
+- `Retriever` — the sole caller of a store's search, exposing no collection or
+  filter parameter — and a neutral `ScopedAgent` loop whose one retrieval tool
+  takes a query string only.
+- Append-only audit log with a SHA-256 hash chain; `chancel verify-log` names
+  the first divergent line and prints the head hash as an external anchor.
+- Three-tier memory with `promote_fact()`, which refuses any fact whose
+  provenance includes a space-scoped id.
+- The leak suite: seven findings asserting the predicted color per backend, and
+  `chancel demo` rendering the backend × provider matrix with no API key, no
+  Docker, and no model download.
+- CLI: `demo`, `ask`, `attack`, `verify-log`, `gen-corpus`.
+
+[Unreleased]: https://github.com/Nobel-Co/chancel/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Nobel-Co/chancel/releases/tag/v0.1.0

chancel-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,8 @@
+# Contributing
+
+- PRs only.
+- Use Conventional Commits.
+- No AI attribution trailers in commit messages.
+- Run `just all` before opening a PR.
+- **Any PR containing real data (client names, real matters, real filings) is rejected — synthetic generated data only.**
+- New adapters must pass `tests/conformance/` without modifying it.