From 4a18fe6b4979fff86d6c084c36b88128357e1650 Mon Sep 17 00:00:00 2001 From: D Thomas <146stat@gmail.com> Date: Tue, 28 Jul 2026 23:48:09 +0000 Subject: [PATCH] docs: establish public documentation foundation --- .github/workflows/docs.yml | 54 +++++++++ .gitignore | 1 + docs/concepts/evidence-graph.md | 39 +++++++ docs/concepts/trust-boundary.md | 33 ++++++ docs/concepts/trust-modes.md | 48 ++++++++ docs/getting-started/installation.md | 61 +++++++++++ docs/getting-started/quickstart.md | 54 +++++++++ docs/guides/local-simulation.md | 35 ++++++ docs/guides/verifying-a-chain.md | 33 ++++++ docs/index.md | 110 +++++++++++++++++++ docs/providers/ibm-quantum.md | 45 ++++++++ docs/reference/cli.md | 46 ++++++++ docs/roadmap.md | 42 +++++++ docs/stylesheets/extra.css | 157 +++++++++++++++++++++++++++ mkdocs.yml | 67 ++++++++++++ requirements-docs.txt | 1 + 16 files changed, 826 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/concepts/evidence-graph.md create mode 100644 docs/concepts/trust-boundary.md create mode 100644 docs/concepts/trust-modes.md create mode 100644 docs/getting-started/installation.md create mode 100644 docs/getting-started/quickstart.md create mode 100644 docs/guides/local-simulation.md create mode 100644 docs/guides/verifying-a-chain.md create mode 100644 docs/index.md create mode 100644 docs/providers/ibm-quantum.md create mode 100644 docs/reference/cli.md create mode 100644 docs/roadmap.md create mode 100644 docs/stylesheets/extra.css create mode 100644 mkdocs.yml create mode 100644 requirements-docs.txt diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..6865ace --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,54 @@ +name: QuantumD Documentation + +on: + pull_request: + paths: + - "docs/**" + - "mkdocs.yml" + - "requirements-docs.txt" + - ".github/workflows/docs.yml" + + push: + branches: + - main + paths: + - "docs/**" + - "mkdocs.yml" + - "requirements-docs.txt" + - ".github/workflows/docs.yml" + + workflow_dispatch: + +permissions: + contents: read + +jobs: + build: + name: Build documentation + runs-on: ubuntu-latest + + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + cache: pip + cache-dependency-path: requirements-docs.txt + + - name: Install documentation dependencies + run: | + python -m pip install --upgrade pip + python -m pip install -r requirements-docs.txt + + - name: Build documentation strictly + run: python -m mkdocs build --strict + + - name: Upload rendered site + uses: actions/upload-artifact@v4 + with: + name: quantumd-documentation-site + path: site/ + if-no-files-found: error diff --git a/.gitignore b/.gitignore index 2da5eda..514da27 100644 --- a/.gitignore +++ b/.gitignore @@ -30,3 +30,4 @@ fix_*.py **/evidence/reports/ **/evidence/executions/ **/evidence/ibm-smoke/ +site/ diff --git a/docs/concepts/evidence-graph.md b/docs/concepts/evidence-graph.md new file mode 100644 index 0000000..3f18c79 --- /dev/null +++ b/docs/concepts/evidence-graph.md @@ -0,0 +1,39 @@ +# Evidence graph + +The Evidence Graph is the durable record of governed execution. + +## Local graph + +~~~text +QVERIFY ──> QEXEC +~~~ + +`QVERIFY` records the verified project and executable authorization. +`QEXEC` records the executed circuit, backend, shots, result artifact, +and receipt. + +## Managed hardware graph + +~~~text +QVERIFY + │ + ▼ +QPLAN ──> QAPPROVAL ──> QSUB ──> IBM JOB ──> QEXEC +~~~ + +## Core bindings + +The verifier checks that: + +- Cryptographic signatures are valid. +- The signing-key lineage is consistent. +- Authorization binds to the exact verification record. +- Source and manifest identities have not changed. +- Execution binds to the authorized workload. +- Logical and executed circuit identities match the evidence. +- The result artifact hash is correct. +- Observed shots equal authorized shots. +- Authorization predates execution. + +The graph is intended to be verifiable independently of the system that +originally produced it. diff --git a/docs/concepts/trust-boundary.md b/docs/concepts/trust-boundary.md new file mode 100644 index 0000000..cda4210 --- /dev/null +++ b/docs/concepts/trust-boundary.md @@ -0,0 +1,33 @@ +# Trust boundary + +QuantumD treats code generation and governed execution as different +security domains. + +~~~text +UNTRUSTED OR EXTERNAL QUANTUMD TRUST BOUNDARY + +AI-generated code ────────────────> Project verification +Notebook changes ────────────────> Policy evaluation +User configuration ───────────────> Exact workload binding + Signed evidence + Authorized execution + Independent verification +~~~ + +## What crosses the boundary + +A project crosses the boundary only after QuantumD establishes the exact +identity of its source, manifest, target, and execution parameters. + +## What does not cross automatically + +- A generated circuit is not automatically trusted. +- A passing simulation is not hardware authorization. +- A local signing key is not an organization-managed identity. +- An IBM credential is not approval to submit every workload. +- A completed job is not accepted until its result is evidence-bound. + +## Fail-closed behavior + +Missing, mismatched, expired, replayed, or corrupted evidence causes +denial instead of best-effort execution. diff --git a/docs/concepts/trust-modes.md b/docs/concepts/trust-modes.md new file mode 100644 index 0000000..a23b9da --- /dev/null +++ b/docs/concepts/trust-modes.md @@ -0,0 +1,48 @@ +# Trust modes + +QuantumD separates local development from real hardware authority. + +## `UNCONFIGURED` + +No valid signing provider is available. Governed execution is denied. + +## `LOCAL_DEVELOPMENT` + +Available now. + +- Project-local signing identity. +- Aer simulation only. +- Offline verification. +- No GCP requirement. +- No IBM contact. +- Hardware authorization prohibited. + +## `KMS_GOVERNED` + +Available for the existing organization-managed execution path. + +- Organization-controlled signing through Google Cloud KMS. +- Managed approval and evidence lineage. +- IBM hardware execution subject to policy and account access. +- Intended for controlled production workflows. + +When KMS is configured, it takes precedence over local-development trust. + +## `SELF_MANAGED_HARDWARE` + +Planned for Phase 5B. + +This mode will allow a developer to use an encrypted local signing +identity and their own IBM Quantum account without requiring GCP. + +Planned controls include: + +- Explicit hardware enablement. +- Encrypted IBM credential storage. +- Signing-key creation and import. +- Backend and shot limits. +- Cost ceilings. +- Expiring, single-use approval. +- Exact workload and result binding. + +A `LOCAL_DEVELOPMENT` identity will never automatically gain this scope. diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md new file mode 100644 index 0000000..7232f37 --- /dev/null +++ b/docs/getting-started/installation.md @@ -0,0 +1,61 @@ +# Installation + +QuantumD can run in Linux, WSL, Cloud Shell, or another compatible Python +environment. + +## Install from source + +The public repository is the authoritative installation path before the +production PyPI alpha is released. + +~~~bash +git clone https://github.com/WindDAnalytics/quantumd.git +cd quantumd + +python -m venv .venv +source .venv/bin/activate + +python -m pip install --upgrade pip +python -m pip install -e . +~~~ + +Confirm the installation: + +~~~bash +quantumd --help +quantumd doctor . +~~~ + +## WSL + +No Google Cloud account is required for local simulation. + +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 . +~~~ + +You can then run: + +~~~bash +quantumd quickstart ~/quantumd-first-run +~~~ + +## Public PyPI target + +The intended public-alpha experience is: + +~~~bash +pip install quantumd +quantumd quickstart +~~~ + +This documentation does not claim that production PyPI publishing has +occurred until the release acceptance process is complete. diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md new file mode 100644 index 0000000..9de3db6 --- /dev/null +++ b/docs/getting-started/quickstart.md @@ -0,0 +1,54 @@ +# Local quickstart + +`quantumd quickstart` creates and executes a complete locally governed +simulator workflow. + +## Run it + +~~~bash +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. + +## Inspect the trust posture + +~~~bash +quantumd doctor ./quantumd-first-run +~~~ + +The expected local posture is: + +~~~text +Active trust mode: LOCAL_DEVELOPMENT +Local trust scope: LOCAL_SIMULATION_ONLY +Hardware authorization: PROHIBITED +~~~ + +## Verify the chain + +~~~bash +quantumd verify-chain ./quantumd-first-run --latest +~~~ + +The verifier performs no network calls for a local chain. + +## Local identity + +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. diff --git a/docs/guides/local-simulation.md b/docs/guides/local-simulation.md new file mode 100644 index 0000000..b0b0651 --- /dev/null +++ b/docs/guides/local-simulation.md @@ -0,0 +1,35 @@ +# Local simulation + +Local simulation is the safest way to begin with QuantumD. + +## Create a governed project + +~~~bash +quantumd quickstart ./my-quantumd-project --shots 128 +~~~ + +## Diagnose the environment + +~~~bash +quantumd doctor ./my-quantumd-project +~~~ + +## Verify the latest execution + +~~~bash +quantumd verify-chain ./my-quantumd-project --latest +~~~ + +## Security properties + +In `LOCAL_DEVELOPMENT` mode: + +- The only permitted target is `aer-simulator`. +- IBM is not contacted. +- KMS is not contacted. +- No hardware action is taken. +- Evidence is signed locally. +- Verification can be completed offline. + +Local evidence is educational and developmental evidence. It is not a +substitute for organization-managed production authorization. diff --git a/docs/guides/verifying-a-chain.md b/docs/guides/verifying-a-chain.md new file mode 100644 index 0000000..7a7ef21 --- /dev/null +++ b/docs/guides/verifying-a-chain.md @@ -0,0 +1,33 @@ +# Verify an evidence chain + +Use the independent chain verifier to confirm that an execution remains +cryptographically and logically intact. + +## Latest execution + +~~~bash +quantumd verify-chain ./my-project --latest +~~~ + +## What success means + +A successful verification establishes that: + +- The required signatures validate. +- The signing lineage is internally consistent. +- Authorization and verification records refer to the same workload. +- The project source and manifest remain unchanged. +- The executed circuit and result remain bound to the receipt. +- The shot count and execution sequence satisfy policy. + +## Offline local verification + +Local projects cache the public key needed to verify their evidence. + +The private signing key is not required to perform verification. + +## Failure + +Treat any failed check as an evidence-integrity incident. Do not modify +records to make them pass. Preserve the project and inspect the failing +node and its predecessor. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..28f4eef --- /dev/null +++ b/docs/index.md @@ -0,0 +1,110 @@ +--- +title: Governed Quantum Execution +description: Verify every workload. Control every execution. Prove every result. +--- + +
+ +
Governed quantum execution
+ +# Trust every quantum run. + +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 } +[Explore the trust model](concepts/trust-modes.md){ .md-button } + +
+$ quantumd quickstart
+[1/6] Project initialization................ PASS
+[2/6] Simulator-only local identity......... PASS
+[3/6] Verification and policy gates......... PASS
+[4/6] Governed Aer execution................ PASS
+[5/6] Signed evidence and trust scope....... PASS
+[6/6] Offline chain verification............ PASS +
+ +**Runs locally · No GCP required · No quantum hardware contacted** + +
+ +
+ 32 TESTS PASSED + LOCAL CHAIN VERIFIED + HARDWARE AUTHORITY PROHIBITED + KMS CONTACTED: FALSE + IBM CONTACTED: FALSE +
+ +## AI can generate quantum code. QuantumD makes execution accountable. + +QuantumD places a verification and governance boundary between generated +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 + +The current public repository supports a source installation and a +simulator-only governed quickstart: + +~~~bash +git clone https://github.com/WindDAnalytics/quantumd.git +cd quantumd + +python -m venv .venv +source .venv/bin/activate +python -m pip install -e . + +quantumd quickstart +~~~ + +The local workflow creates a project-local signing identity and uses the +Aer simulator. It does not require a GCP account. + +## Evidence, not assertions + +Local development produces a compact evidence graph: + +~~~text +PROJECT ──> QVERIFY ──> QEXEC +~~~ + +Organization-governed hardware execution extends that chain: + +~~~text +PROJECT + │ + ▼ +QVERIFY ──> QPLAN ──> QAPPROVAL ──> QSUB ──> QEXEC +~~~ + +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 | +| `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. + +## The trust boundary + +
+ +Generated code remains outside the trusted boundary until QuantumD +verifies the project, applies policy, and creates signed evidence. + +A local-development identity cannot be promoted into hardware authority. + +
diff --git a/docs/providers/ibm-quantum.md b/docs/providers/ibm-quantum.md new file mode 100644 index 0000000..fd94c24 --- /dev/null +++ b/docs/providers/ibm-quantum.md @@ -0,0 +1,45 @@ +# IBM Quantum + +QuantumD has an existing governed IBM execution path and a planned +portable path. + +## Current managed path + +The current organization-managed workflow uses: + +- IBM Quantum access for backend discovery and execution. +- Google Secret Manager for the IBM credential. +- Google Cloud KMS for governed signing. +- Signed planning, approval, submission, and execution evidence. + +This path remains available and must not be weakened by local-development +features. + +## Phase 5B portable path + +Phase 5B will add a GCP-free workflow for developers using WSL or another +trusted local environment. + +Planned commands include: + +~~~text +quantumd provider add ibm +quantumd provider test ibm +quantumd provider list + +quantumd trust create +quantumd trust import +quantumd trust list +~~~ + +These commands are not documented as available until implementation and +acceptance testing are complete. + +## Planned separation of responsibility + +The IBM credential will authenticate access to IBM Quantum. + +The QuantumD signing identity will authorize the exact governed plan, +approval, submission, and execution. + +Possessing an IBM credential alone will not bypass QuantumD policy. diff --git a/docs/reference/cli.md b/docs/reference/cli.md new file mode 100644 index 0000000..840e82d --- /dev/null +++ b/docs/reference/cli.md @@ -0,0 +1,46 @@ +# CLI commands + +## Available local commands + +### `quantumd quickstart` + +Creates and executes a complete simulator-only governed project. + +~~~bash +quantumd quickstart [PROJECT_PATH] --shots 128 +~~~ + +### `quantumd doctor` + +Reports installation readiness, simulator availability, trust mode, +identity validity, and hardware authority. + +~~~bash +quantumd doctor [PROJECT_PATH] +~~~ + +### `quantumd verify-chain` + +Independently verifies the latest or selected evidence chain. + +~~~bash +quantumd verify-chain [PROJECT_PATH] --latest +~~~ + +## Existing managed commands + +QuantumD also includes governed verification, planning, approval, +submission, reconciliation, chain inspection, and adversarial testing +workflows used by the current KMS-governed path. + +Consult `quantumd --help` and each command's `--help` output for the +exact interface in the installed version. + +## Planned Phase 5B commands + +The following interface is directional and not yet a released contract: + +~~~text +quantumd provider add|test|list|remove +quantumd trust create|import|list +~~~ diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..1a62cfa --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,42 @@ +# Roadmap + +## Phase 5A — Governed local quickstart + +**Status: complete and merged** + +- Local project initialization. +- Project-local P-256 signing. +- Simulator-only authorization. +- Governed Aer execution. +- Signed verification and execution evidence. +- Independent offline chain verification. +- Trust-mode diagnostics. +- Hardware authorization prohibited. + +## Phase 5B — Provider and trust portability + +**Status: planned** + +- Encrypted local IBM credential storage. +- IBM provider add, test, list, and remove commands. +- Self-managed hardware signing identities. +- Signing-key creation and import. +- GCP-free IBM planning and execution. +- Explicit hardware enablement. +- Cost, backend, shot, and expiration controls. +- Clean WSL acceptance testing. + +## Enterprise trust providers + +**Status: future** + +- AWS KMS. +- Azure Key Vault. +- HashiCorp Vault. +- PKCS#11 and enterprise HSMs. +- Organization policy and multi-party approvals. + +## Release principle + +Planned capabilities remain labeled as planned until their code, +security invariants, packaging, and external acceptance all pass. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..1a0df24 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,157 @@ +:root { + --quantumd-void: #050505; + --quantumd-surface: rgba(15, 15, 20, 0.72); + --quantumd-cyan: #00f0ff; + --quantumd-green: #10b981; + --quantumd-red: #ef4444; + --quantumd-silver: #9ca3af; +} + +[data-md-color-scheme="slate"] { + --md-default-bg-color: var(--quantumd-void); + --md-default-fg-color: #f5f7fa; + --md-default-fg-color--light: var(--quantumd-silver); + --md-primary-fg-color: #050505; + --md-accent-fg-color: var(--quantumd-cyan); + --md-code-bg-color: #090b10; + --md-code-fg-color: #dce7ef; + --md-typeset-a-color: var(--quantumd-cyan); +} + +body { + background: + linear-gradient(rgba(0, 240, 255, 0.018) 1px, transparent 1px), + linear-gradient(90deg, rgba(0, 240, 255, 0.018) 1px, transparent 1px), + var(--quantumd-void); + background-size: 48px 48px; +} + +.md-header, +.md-tabs { + background: rgba(5, 5, 5, 0.94); + backdrop-filter: blur(16px); + border-bottom: 1px solid rgba(0, 240, 255, 0.16); +} + +.md-main__inner { + max-width: 1440px; +} + +.md-typeset h1, +.md-typeset h2, +.md-typeset h3 { + letter-spacing: -0.025em; + font-weight: 700; +} + +.md-typeset h1 { + color: #ffffff; +} + +.md-typeset code { + border: 1px solid rgba(0, 240, 255, 0.10); +} + +.md-typeset pre > code { + border: 0; +} + +.quantumd-kicker { + color: var(--quantumd-cyan); + font-family: monospace; + font-size: 0.74rem; + font-weight: 700; + letter-spacing: 0.16em; + text-transform: uppercase; +} + +.quantumd-hero { + margin: 2rem 0 2.5rem; + padding: 2rem; + background: linear-gradient( + 135deg, + rgba(0, 240, 255, 0.075), + rgba(15, 15, 20, 0.72) + ); + border: 1px solid rgba(0, 240, 255, 0.22); + border-radius: 14px; + box-shadow: 0 0 36px rgba(0, 240, 255, 0.06); + backdrop-filter: blur(14px); +} + +.quantumd-hero h1 { + margin-bottom: 0.4rem; + font-size: clamp(2.4rem, 6vw, 4.8rem); + line-height: 0.98; +} + +.quantumd-hero p { + max-width: 820px; + color: #c4ccd5; + font-size: 1.05rem; +} + +.quantumd-terminal { + margin: 1.5rem 0; + padding: 1rem 1.2rem; + overflow-x: auto; + color: #d9faff; + background: rgba(3, 6, 10, 0.94); + border: 1px solid rgba(0, 240, 255, 0.28); + border-radius: 10px; + box-shadow: inset 0 0 28px rgba(0, 240, 255, 0.025); + font-family: monospace; +} + +.quantumd-proof { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(190px, 1fr)); + gap: 0.75rem; + margin: 1.5rem 0 2.5rem; +} + +.quantumd-proof span { + padding: 0.85rem 1rem; + color: #d8e2ea; + background: var(--quantumd-surface); + border: 1px solid rgba(0, 240, 255, 0.14); + border-radius: 8px; + font-family: monospace; + font-size: 0.72rem; + text-align: center; + letter-spacing: 0.06em; +} + +.quantumd-proof .pass { + color: var(--quantumd-green); + border-color: rgba(16, 185, 129, 0.30); +} + +.quantumd-proof .deny { + color: var(--quantumd-red); + border-color: rgba(239, 68, 68, 0.30); +} + +.quantumd-boundary { + padding: 1rem 1.25rem; + background: var(--quantumd-surface); + border-left: 3px solid var(--quantumd-cyan); + border-radius: 0 8px 8px 0; +} + +.md-button--primary { + color: #001014 !important; + background: var(--quantumd-cyan) !important; + border-color: var(--quantumd-cyan) !important; + box-shadow: 0 0 20px rgba(0, 240, 255, 0.18); +} + +.md-button:not(.md-button--primary) { + border-color: rgba(0, 240, 255, 0.52); +} + +@media screen and (max-width: 600px) { + .quantumd-hero { + padding: 1.25rem; + } +} diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..ce41b25 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,67 @@ +site_name: QuantumD +site_description: Verification, governance, and evidence for quantum execution. +site_url: https://docs.quantumd.ai + +repo_name: WindDAnalytics/quantumd +repo_url: https://github.com/WindDAnalytics/quantumd +edit_uri: edit/main/docs/ + +copyright: Copyright © QuantumD + +theme: + name: material + language: en + palette: + scheme: slate + primary: black + accent: cyan + features: + - navigation.tabs + - navigation.sections + - navigation.top + - search.suggest + - search.highlight + - content.code.copy + - content.code.annotate + +plugins: + - search + +markdown_extensions: + - admonition + - attr_list + - md_in_html + - pymdownx.details + - pymdownx.inlinehilite + - pymdownx.superfences + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + +extra_css: + - stylesheets/extra.css + +nav: + - Home: index.md + + - Getting Started: + - Installation: getting-started/installation.md + - Local Quickstart: getting-started/quickstart.md + + - Core Concepts: + - Trust Modes: concepts/trust-modes.md + - Trust Boundary: concepts/trust-boundary.md + - Evidence Graph: concepts/evidence-graph.md + + - Guides: + - Local Simulation: guides/local-simulation.md + - Verify an Evidence Chain: guides/verifying-a-chain.md + + - Providers: + - IBM Quantum: providers/ibm-quantum.md + + - Reference: + - CLI Commands: reference/cli.md + + - Roadmap: roadmap.md diff --git a/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 0000000..d3504c7 --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1 @@ +mkdocs-material==9.7.7