From 5d620d8e4be79632f751b9855364bd445ac833e6 Mon Sep 17 00:00:00 2001 From: D Thomas <146stat@gmail.com> Date: Sun, 2 Aug 2026 14:17:21 +0000 Subject: [PATCH] docs: establish public alpha onboarding --- ALPHA_TESTING.md | 6 + README.md | 177 ++++++++++++++++++++++++++- docs/alpha-evaluation.md | 27 ++++ docs/concepts/trust-modes.md | 2 +- docs/getting-started/installation.md | 116 +++++++++++++----- docs/getting-started/quickstart.md | 45 +++++-- docs/index.md | 76 +++++++----- docs/releases/v0.7.4-alpha.md | 44 +++++++ mkdocs.yml | 5 + 9 files changed, 422 insertions(+), 76 deletions(-) create mode 100644 docs/alpha-evaluation.md create mode 100644 docs/releases/v0.7.4-alpha.md diff --git a/ALPHA_TESTING.md b/ALPHA_TESTING.md index 57ccafa..05020b9 100644 --- a/ALPHA_TESTING.md +++ b/ALPHA_TESTING.md @@ -112,3 +112,9 @@ Do not include: - confidential workloads - sensitive evidence - regulated or classified information + +## Submit feedback + +After completing the evaluation, open the repository's **Alpha evaluation +feedback** issue form. Do not include credentials, private keys, cloud account +identifiers, confidential workloads, or sensitive evidence. diff --git a/README.md b/README.md index 7c6b9dc..40a9fb9 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,180 @@ # QuantumD +[![CI](https://github.com/WindDAnalytics/quantumd/actions/workflows/ci.yml/badge.svg)](https://github.com/WindDAnalytics/quantumd/actions/workflows/ci.yml) +[![Documentation](https://github.com/WindDAnalytics/quantumd/actions/workflows/docs.yml/badge.svg)](https://github.com/WindDAnalytics/quantumd/actions/workflows/docs.yml) +[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/) +[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE) +[![Status](https://img.shields.io/badge/status-public%20alpha-orange.svg)](CHANGELOG.md) + > **QuantumD exists to produce trustworthy evidence, not favorable quantum results.** -QuantumD is the trust and execution layer for AI-generated quantum software. It enforces a strict zero-trust boundary around quantum execution: AI may generate the quantum program, but QuantumD independently evaluates it before trusting or executing it. +QuantumD is the trust and execution layer for AI-generated quantum software. +It verifies the exact workload, enforces execution policy, binds authorization +to what actually runs, and produces evidence that can be checked independently. + +AI may generate a circuit or computational workflow. QuantumD decides whether +that exact workload is permitted to execute and whether the resulting evidence +supports the claimed run. + +## What QuantumD proves + +QuantumD binds together: + +- the project source and manifest +- the verification decision +- the authorized backend and shot count +- the logical and executed circuit identities +- the result artifact +- the execution receipt +- the signing-key lineage +- the order of authorization and execution + +A successful job identifier or a complete cloud log is not enough. QuantumD +checks the chain connecting reviewer intent, authorization, execution, and +results. + +## Run the public alpha + +QuantumD `0.7.4a0` is published on TestPyPI. Use an isolated Python environment +and download only the QuantumD wheel from TestPyPI. Dependencies are then +resolved from the default Python Package Index. + +```bash +python3.12 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip + +python -m pip download \ + --no-deps \ + --only-binary=:all: \ + --index-url https://test.pypi.org/simple/ \ + quantumd==0.7.4a0 + +echo \ + "761a865a5aaf655f570fa3ae6f1d0f9b1b09cb89ee5519ac1843b738d251b7d2 quantumd-0.7.4a0-py3-none-any.whl" \ + | sha256sum --check + +python -m pip install \ + ./quantumd-0.7.4a0-py3-none-any.whl +``` + +Create and execute a governed local project: + +```bash +quantumd quickstart my-first-quantumd-project +``` + +Inspect the trust posture and independently verify the evidence: + +```bash +quantumd doctor my-first-quantumd-project + +quantumd verify-chain \ + my-first-quantumd-project \ + --latest +``` + +The local quickstart is intentionally restricted: + +```text +Trust mode: LOCAL_DEVELOPMENT +Trust scope: LOCAL_SIMULATION_ONLY +Hardware authorization: PROHIBITED +KMS signing used: False +IBM contacted: False +Hardware action: None +``` + +Independent verification should finish with: + +```text +[STATUS] COMPLETE EVIDENCE CHAIN VERIFIED +IBM contacted: False +KMS contacted: False +Hardware action: None +``` + +No Google Cloud account, IBM Quantum account, or hardware access is required +for the local quickstart. + +## The Evidence Graph + +A local simulator run produces a compact evidence chain: + +```text +PROJECT -> QVERIFY -> QEXEC +``` + +An organization-governed hardware workflow extends the chain: + +```text +PROJECT + | + v +QVERIFY -> QPLAN -> QAPPROVAL -> QSUB -> IBM JOB -> QEXEC +``` + +Each node binds to the exact records before and after it. Independent +verification checks signatures, key lineage, workload identity, circuit +identity, result hashes, shot counts, and execution timing without contacting +IBM or KMS. + +## Trust modes + +| Trust mode | Purpose | Hardware authority | +| --- | --- | --- | +| `UNCONFIGURED` | No valid signing provider | Prohibited | +| `LOCAL_DEVELOPMENT` | Project-local simulator evaluation | Prohibited | +| `KMS_GOVERNED` | Organization-managed authorization and signing | Policy controlled | +| `SELF_MANAGED_HARDWARE` | Planned developer-managed hardware path | Not yet available | + +A local-development identity cannot be promoted into hardware authority. +Missing, mismatched, replayed, expired, or corrupted evidence causes denial. + +## Evaluate QuantumD + +QuantumD is recruiting five early evaluators: + +1. a quantum developer +2. a software-supply-chain or security engineer +3. an ML, data, or scientific-computing engineer +4. a technical leader from an audit-exposed environment +5. an educator, researcher, or advanced technical student + +Complete the installation and quickstart without a live walkthrough. Then +submit the structured **Alpha evaluation feedback** issue form. + +Read [ALPHA_TESTING.md](ALPHA_TESTING.md) before beginning. + +## Documentation + +- [Installation](docs/getting-started/installation.md) +- [Local quickstart](docs/getting-started/quickstart.md) +- [Evidence Graph](docs/concepts/evidence-graph.md) +- [Trust boundary](docs/concepts/trust-boundary.md) +- [Trust modes](docs/concepts/trust-modes.md) +- [IBM Quantum provider](docs/providers/ibm-quantum.md) +- [CLI reference](docs/reference/cli.md) +- [Security policy](SECURITY.md) +- [Contributing](CONTRIBUTING.md) +- [Support](SUPPORT.md) + +## Alpha boundaries + +QuantumD is alpha software. Interfaces and evidence schemas may evolve. +Pin exact versions and preserve evidence with the version that produced it. + +Local simulation is suitable for evaluation and development. QuantumD alpha +must not be treated as the sole control protecting safety-critical, classified, +regulated, or financially material operations. + +Security concerns must be reported privately under [SECURITY.md](SECURITY.md). +Do not publish credentials, private keys, confidential workloads, or sensitive +evidence in issues or Discussions. + +## Project + +- Website: [quantumd.ai](https://quantumd.ai) +- License: [Apache License 2.0](LICENSE) +- Current alpha: `0.7.4a0` +- Release tag: `v0.7.4-alpha` diff --git a/docs/alpha-evaluation.md b/docs/alpha-evaluation.md new file mode 100644 index 0000000..98b6a62 --- /dev/null +++ b/docs/alpha-evaluation.md @@ -0,0 +1,27 @@ +# Alpha evaluation + +QuantumD is recruiting five early technical evaluators: + +1. a quantum developer +2. a software-supply-chain or security engineer +3. an ML, data, or scientific-computing engineer +4. a technical leader from an audit-exposed environment +5. an educator, researcher, or advanced technical student + +## Evaluation rule + +Complete the installation and local quickstart without a live walkthrough. +Record where the documentation creates confusion, skepticism, or unnecessary +work. + +Use the [installation guide](getting-started/installation.md), then run: + +~~~bash +quantumd quickstart my-first-quantumd-project +quantumd doctor my-first-quantumd-project +quantumd verify-chain my-first-quantumd-project --latest +~~~ + +Submit the repository's **Alpha evaluation feedback** issue form. Do not +publish credentials, private keys, cloud identifiers, confidential workloads, +sensitive evidence, or regulated data. diff --git a/docs/concepts/trust-modes.md b/docs/concepts/trust-modes.md index a23b9da..5da5368 100644 --- a/docs/concepts/trust-modes.md +++ b/docs/concepts/trust-modes.md @@ -30,7 +30,7 @@ When KMS is configured, it takes precedence over local-development trust. ## `SELF_MANAGED_HARDWARE` -Planned for Phase 5B. +Planned. This mode will allow a developer to use an encrypted local signing identity and their own IBM Quantum account without requiring GCP. diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index a14fd92..a0b6359 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -1,61 +1,121 @@ # Installation -QuantumD can run in Linux, WSL, Cloud Shell, or another compatible Python -environment. +QuantumD runs on Linux, Windows Subsystem for Linux, Cloud Shell, and other +compatible Python environments. -## Install from source +The public alpha requires Python 3.10 or newer. Python 3.12 is the reference +environment used by the release and acceptance workflows. -The public repository is the authoritative installation path before the -production PyPI alpha is released. +## Install the published alpha -~~~bash -git clone https://github.com/WindDAnalytics/quantumd.git -cd quantumd +Create an isolated environment: -python -m venv .venv +~~~bash +python3.12 -m venv .venv source .venv/bin/activate - python -m pip install --upgrade pip -python -m pip install -e . ~~~ +Download only the exact QuantumD wheel from TestPyPI: + +~~~bash +python -m pip download \ + --no-deps \ + --only-binary=:all: \ + --index-url https://test.pypi.org/simple/ \ + quantumd==0.7.4a0 +~~~ + +Verify the published wheel: + +~~~bash +echo \ + "761a865a5aaf655f570fa3ae6f1d0f9b1b09cb89ee5519ac1843b738d251b7d2 quantumd-0.7.4a0-py3-none-any.whl" \ + | sha256sum --check +~~~ + +Install the downloaded wheel: + +~~~bash +python -m pip install \ + ./quantumd-0.7.4a0-py3-none-any.whl +~~~ + +Because the wheel is installed from a local file, its dependencies resolve +from the default Python Package Index rather than TestPyPI. + +!!! warning "Do not use TestPyPI as the only dependency index" + + Avoid `using TestPyPI as the sole package index`. TestPyPI is + a testing service and may contain unrelated or incomplete dependency + packages. Download the exact QuantumD artifact first, then install the + local wheel. + Confirm the installation: ~~~bash quantumd --help -quantumd doctor . ~~~ -## WSL +## Run the first governed workflow + +~~~bash +quantumd quickstart my-first-quantumd-project +~~~ + +Then inspect and independently verify it: + +~~~bash +quantumd doctor my-first-quantumd-project + +quantumd verify-chain \ + my-first-quantumd-project \ + --latest +~~~ -No Google Cloud account is required for local simulation. +No Google Cloud account or IBM Quantum account is required for the local +simulator path. + +## Windows Subsystem for Linux From a WSL terminal: ~~~bash cd ~ -git clone https://github.com/WindDAnalytics/quantumd.git -cd quantumd -python3 -m venv .venv -source .venv/bin/activate -python -m pip install -e . -~~~ +python3.12 -m venv quantumd-alpha +source quantumd-alpha/bin/activate +python -m pip install --upgrade pip -You can then run: +python -m pip download \ + --no-deps \ + --only-binary=:all: \ + --index-url https://test.pypi.org/simple/ \ + quantumd==0.7.4a0 + +python -m pip install \ + ./quantumd-0.7.4a0-py3-none-any.whl -~~~bash quantumd quickstart ~/quantumd-first-run ~~~ -## Public PyPI target +## Install from source for development -The intended public-alpha experience is: +Clone the repository only when contributing or evaluating unreleased changes: ~~~bash -pip install -i https://test.pypi.org/simple/ quantumd -quantumd quickstart +git clone https://github.com/WindDAnalytics/quantumd.git +cd quantumd + +python3.12 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" ~~~ -This documentation does not claim that production PyPI publishing has -occurred until the release acceptance process is complete. The link above is for the pre-release. +Run the development acceptance checks: + +~~~bash +python -m pytest -q +bash scripts/public_alpha_acceptance.sh +~~~ diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 9de3db6..71fc5e5 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -3,6 +3,9 @@ `quantumd quickstart` creates and executes a complete locally governed simulator workflow. +Install the published alpha first by following the +[installation guide](installation.md). + ## Run it ~~~bash @@ -11,13 +14,25 @@ quantumd quickstart ./quantumd-first-run --shots 128 QuantumD will: -1. Initialize a project. -2. Create a project-local P-256 signing identity. -3. Run verification and policy gates. -4. Authorize only `aer-simulator`. -5. Execute the verified workload. -6. Sign the evidence and execution receipt. -7. Verify the evidence chain offline. +1. initialize a project +2. create a project-local P-256 signing identity +3. evaluate verification and policy gates +4. authorize only `aer-simulator` +5. execute the verified workload +6. sign the verification evidence and execution receipt +7. verify the resulting chain offline + +A successful run ends with: + +~~~text +[STATUS] QUANTUMD LOCAL QUICKSTART COMPLETE +Trust mode: LOCAL_DEVELOPMENT +Trust scope: LOCAL_SIMULATION_ONLY +Hardware authorization: PROHIBITED +KMS signing used: False +IBM contacted: False +Hardware action: None +~~~ ## Inspect the trust posture @@ -29,6 +44,8 @@ The expected local posture is: ~~~text Active trust mode: LOCAL_DEVELOPMENT +KMS key configured: False +Local identity valid: True Local trust scope: LOCAL_SIMULATION_ONLY Hardware authorization: PROHIBITED ~~~ @@ -39,16 +56,20 @@ Hardware authorization: PROHIBITED quantumd verify-chain ./quantumd-first-run --latest ~~~ -The verifier performs no network calls for a local chain. +The verifier checks signatures, key lineage, authorization, source and +manifest identities, workload binding, circuit identities, the result hash, +shot count, and execution timing. + +The verifier performs no IBM or KMS calls for a local chain. ## Local identity -The private identity is project-local and excluded from Git. QuantumD -stores it beneath: +The private identity is project-local and excluded from Git. QuantumD stores +it beneath: ~~~text .quantumd/local-trust/ ~~~ -Do not manually replace individual identity files. Partial or mismatched -identity state is rejected rather than silently repaired. +Partial, corrupted, or mismatched identity state is rejected rather than +silently repaired. A local identity cannot authorize IBM hardware. diff --git a/docs/index.md b/docs/index.md index 28f4eef..5e365d1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,11 +12,12 @@ description: Verify every workload. Control every execution. Prove every result. QuantumD verifies quantum workloads, enforces execution policy, signs evidence, and independently verifies what actually ran. -[Start locally](getting-started/quickstart.md){ .md-button .md-button--primary } +[Install the alpha](getting-started/installation.md){ .md-button .md-button--primary } +[Run the quickstart](getting-started/quickstart.md){ .md-button } [Explore the trust model](concepts/trust-modes.md){ .md-button }
-$ quantumd quickstart
+$ quantumd quickstart my-first-quantumd-project
[1/6] Project initialization................ PASS
[2/6] Simulator-only local identity......... PASS
[3/6] Verification and policy gates......... PASS
@@ -25,7 +26,7 @@ $ quantumd quickstart
[6/6] Offline chain verification............ PASS
-**Runs locally · No GCP required · No quantum hardware contacted** +**Runs locally · No GCP required · No IBM account required · Hardware prohibited** @@ -45,40 +46,51 @@ software and quantum execution. The system binds authorization to the exact project, source, manifest, backend, shot count, circuit, result artifact, and execution receipt. -## Start locally +## Install the public alpha -The current public repository supports a source installation and a -simulator-only governed quickstart: +Create an isolated environment, download the exact QuantumD wheel from +TestPyPI, verify its checksum, and install the local artifact: ~~~bash -git clone https://github.com/WindDAnalytics/quantumd.git -cd quantumd - -python -m venv .venv +python3.12 -m venv .venv source .venv/bin/activate -python -m pip install -e . +python -m pip install --upgrade pip + +python -m pip download \ + --no-deps \ + --only-binary=:all: \ + --index-url https://test.pypi.org/simple/ \ + quantumd==0.7.4a0 + +echo \ + "761a865a5aaf655f570fa3ae6f1d0f9b1b09cb89ee5519ac1843b738d251b7d2 quantumd-0.7.4a0-py3-none-any.whl" \ + | sha256sum --check -quantumd quickstart +python -m pip install \ + ./quantumd-0.7.4a0-py3-none-any.whl ~~~ -The local workflow creates a project-local signing identity and uses the -Aer simulator. It does not require a GCP account. +Run the local governed workflow: + +~~~bash +quantumd quickstart my-first-quantumd-project +~~~ ## Evidence, not assertions -Local development produces a compact evidence graph: +Local development produces a compact Evidence Graph: ~~~text -PROJECT ──> QVERIFY ──> QEXEC +PROJECT -> QVERIFY -> QEXEC ~~~ Organization-governed hardware execution extends that chain: ~~~text PROJECT - │ - ▼ -QVERIFY ──> QPLAN ──> QAPPROVAL ──> QSUB ──> QEXEC + | + v +QVERIFY -> QPLAN -> QAPPROVAL -> QSUB -> IBM JOB -> QEXEC ~~~ Each node is bound to its predecessor and can be checked independently. @@ -86,25 +98,21 @@ Each node is bound to its predecessor and can be checked independently. ## Trust modes | Mode | Status | Hardware | -|---|---|---| +| --- | --- | --- | | `LOCAL_DEVELOPMENT` | Available | Prohibited | -| `KMS_GOVERNED` | Available for the existing managed path | Policy controlled | -| `SELF_MANAGED_HARDWARE` | Phase 5B | Planned | +| `KMS_GOVERNED` | Available for the organization-managed path | Policy controlled | +| `SELF_MANAGED_HARDWARE` | Planned | Not yet available | | `UNCONFIGURED` | Denied | Prohibited | -!!! info "Current versus planned" - - QuantumD runs locally today without GCP. GCP-free IBM hardware - execution, encrypted local IBM credentials, and imported signing - identities are Phase 5B deliverables. +!!! info "Local evaluation is intentionally restricted" -## The trust boundary + QuantumD runs locally without GCP or IBM credentials. Local-development + trust is simulator-only and cannot be promoted into hardware authority. -
+## Evaluate the alpha -Generated code remains outside the trusted boundary until QuantumD -verifies the project, applies policy, and creates signed evidence. +QuantumD is recruiting five early technical evaluators. Complete the +installation and quickstart without a live walkthrough, then report where the +experience became confusing, unconvincing, or unnecessarily difficult. -A local-development identity cannot be promoted into hardware authority. - -
+[Read the evaluation guide](alpha-evaluation.md){ .md-button .md-button--primary } diff --git a/docs/releases/v0.7.4-alpha.md b/docs/releases/v0.7.4-alpha.md new file mode 100644 index 0000000..e2b17d7 --- /dev/null +++ b/docs/releases/v0.7.4-alpha.md @@ -0,0 +1,44 @@ +# QuantumD v0.7.4 alpha + +QuantumD `0.7.4a0` is the first release carrying the permanent public-alpha +wheel acceptance contract. + +## Release identity + +~~~text +Version: 0.7.4a0 +Tag: v0.7.4-alpha +Source commit: 3f3f5ec69d0c21f638a0320c66cb114b55f25ba8 +Wheel: quantumd-0.7.4a0-py3-none-any.whl +Wheel SHA256: 761a865a5aaf655f570fa3ae6f1d0f9b1b09cb89ee5519ac1843b738d251b7d2 +~~~ + +## Protected release contract + +The release workflow: + +- enforces the tag-to-package-version contract +- compiles and tests the source +- builds and validates the distributions +- installs the built wheel into an isolated runtime +- authenticates through GitHub OIDC and Workload Identity Federation +- runs a KMS-attested governed release demonstration +- publishes to TestPyPI through trusted publishing + +## Published-package acceptance + +The actual TestPyPI wheel was downloaded into a fresh environment and proved: + +- installation from `site-packages` +- complete CLI availability +- unsigned governed execution fails closed +- local trust remains simulator-only +- poisoned cloud credentials are ignored +- IBM and KMS are not contacted during local verification +- all ten independent evidence-chain checks pass + +## Alpha limitations + +The public quickstart authorizes local Aer simulation only. Self-managed +hardware authority is not yet available. Interfaces and evidence schemas may +change before a stable release. diff --git a/mkdocs.yml b/mkdocs.yml index ce41b25..c76c920 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -64,4 +64,9 @@ nav: - Reference: - CLI Commands: reference/cli.md + - Alpha Evaluation: alpha-evaluation.md + + - Releases: + - v0.7.4 Alpha: releases/v0.7.4-alpha.md + - Roadmap: roadmap.md