sylvesterkaczmarek · sylvesterkaczmarek · Aug 9, 2026 · Aug 9, 2026 · Aug 9, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  unit:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Compile
+        run: python -m compileall -q src tests examples
+      - name: Test
+        run: python -m pytest
+      - name: Build package
+        if: matrix.python-version == '3.12'
+        run: python -m build
+
+  cudaq-smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install CUDA-Q
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[cudaq,dev]"
+      - name: Diagnose
+        run: cudaq-guard doctor --json
+      - name: CPU simulator smoke test
+        run: |
+          cudaq-guard run ghz --policy policies/local-safe.toml --target qpp-cpu --qubits 3 --shots 256 --seed 7 --audit /tmp/cudaq-guard-audit.jsonl > /tmp/ghz.json
+          cat /tmp/ghz.json
+          python - <<'PY'
+          import json
+          data = json.load(open('/tmp/ghz.json'))
+          assert data['kind'] == 'sample'
+          assert data['shots'] == 256
+          assert set(data['counts']).issubset({'000', '111'})
+          PY
+          cudaq-guard audit verify /tmp/cudaq-guard-audit.jsonl
+      - name: VQE smoke test
+        run: cudaq-guard run vqe --policy policies/local-safe.toml --target qpp-cpu --steps 7 --seed 7 --audit /tmp/cudaq-guard-audit.jsonl
diff --git a/.gitignore b/.gitignore
@@ -1,207 +1,15 @@
-# Byte-compiled / optimized / DLL files
 __pycache__/
-*.py[codz]
-*$py.class
-
-# C extensions
+*.py[cod]
 *.so
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
 *.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py.cover
-.hypothesis/
 .pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# UV
-#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#uv.lock
-
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-#poetry.lock
-#poetry.toml
-
-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
-#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
-#pdm.lock
-#pdm.toml
-.pdm-python
-.pdm-build/
-
-# pixi
-#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
-#pixi.lock
-#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
-#   in the .venv directory. It is recommended not to include this directory in version control.
-.pixi
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.envrc
-.venv
-env/
+.venv/
 venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
-.mypy_cache/
-.dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
-
-# PyCharm
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#  and can be added to the global gitignore or merged into this file.  For a more nuclear
-#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
-
-# Abstra
-# Abstra is an AI-powered process automation framework.
-# Ignore directories containing user credentials, local state, and settings.
-# Learn more at https://abstra.io/docs
-.abstra/
-
-# Visual Studio Code
-#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
-#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
-#  you could uncomment the following to ignore the entire vscode folder
-# .vscode/
-
-# Ruff stuff:
-.ruff_cache/
-
-# PyPI configuration file
-.pypirc
-
-# Cursor
-#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
-#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
-#  refer to https://docs.cursor.com/context/ignore-files
-.cursorignore
-.cursorindexingignore
-
-# Marimo
-marimo/_static/
-marimo/_lsp/
-__marimo__/
+dist/
+build/
+.DS_Store
+.idea/
+.vscode/
+*.log
+runs/
+*.jsonl
diff --git a/CITATION.cff b/CITATION.cff
@@ -1,21 +1,25 @@
 cff-version: 1.2.0
-title: NVIDIA Quantum Hybrid
-message: "If you use this repository, please cite it."
+title: NVIDIA CUDA-Q Quantum Guard
+message: "If you use or adapt this software, please cite it."
+type: software
+version: 0.4.0
 authors:
   - family-names: Kaczmarek
     given-names: Sylvester
     orcid: https://orcid.org/0000-0002-0393-228X
-doi: 10.5281/zenodo.17502919
-date-released: 2025-11-01
-url: https://github.com/sylvesterkaczmarek/nvidia-quantum-hybrid
 license: MIT
-type: software
+doi: 10.5281/zenodo.17502919
+url: https://github.com/sylvesterkaczmarek/nvidia-cudaq-quantum-guard
+repository-code: https://github.com/sylvesterkaczmarek/nvidia-cudaq-quantum-guard
 preferred-citation:
-  type: article
-  title: NVIDIA Quantum Hybrid
+  type: software
+  title: NVIDIA CUDA-Q Quantum Guard
   authors:
     - family-names: Kaczmarek
       given-names: Sylvester
       orcid: https://orcid.org/0000-0002-0393-228X
   year: 2025
+  publisher:
+    name: Zenodo
   doi: 10.5281/zenodo.17502919
+  url: https://doi.org/10.5281/zenodo.17502919
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,31 @@
+# Contributing
+
+Contributions are welcome when they improve practical CUDA-Q execution control, diagnostics, provenance, or reproducibility.
+
+## Development setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+For real CUDA-Q smoke tests:
+
+```bash
+python -m pip install -e ".[cudaq,dev]"
+cudaq-guard doctor
+make smoke
+```
+
+## Design rules
+
+- fail closed rather than silently changing target or policy
+- keep credentials out of logs and fixtures
+- do not claim a security property that the code does not enforce
+- keep core policy/audit code usable without a CUDA-Q installation
+- add regression tests for policy semantics and execution adapters
+- keep provider-specific assumptions behind explicit configuration
+
+If a change alters the audit schema or policy semantics, document the compatibility impact in the pull request.
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Sylvester Kaczmarek
+Copyright (c) 2026 Sylvester Kaczmarek
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/Makefile b/Makefile
@@ -0,0 +1,23 @@
+.PHONY: install install-cudaq test smoke doctor build clean
+
+install:
+	python -m pip install -e ".[dev]"
+
+install-cudaq:
+	python -m pip install -e ".[cudaq,dev]"
+
+test:
+	python -m pytest
+
+smoke:
+	cudaq-guard run ghz --policy policies/local-safe.toml --target qpp-cpu --qubits 3 --shots 256 --seed 7 --audit /tmp/cudaq-guard-audit.jsonl
+	cudaq-guard audit verify /tmp/cudaq-guard-audit.jsonl
+
+doctor:
+	cudaq-guard doctor
+
+build:
+	python -m build
+
+clean:
+	rm -rf build dist *.egg-info .pytest_cache