feat: add PostgreSQL quantum DB integration

.gitignore

@@ -0,0 +1,25 @@
+# Python/editor/local state
+__pycache__/
+*.py[cod]
+.venv/
+.env
+.env.*
+!.env.example
+.DS_Store
+*.sqlite3
+*.log
+*.sock
+
+# Generated experiment outputs and large local datasets
+results/
+outputs/
+artifacts/
+train-test-data/
+systems/quantum_db/outputs/
+systems/quantum_db/results/
+systems/quantum_db/artifacts/
+
+# Native build products
+*.o
+*.dylib
+*.so

README.md

@@ -171,6 +171,21 @@ Reproducibility checklist:
 3. Use the same backend (`origin_wukong`).
 4. Archive the merged JSON report as the analysis source of truth.
 
+## PostgreSQL Quantum DB integration
+
+The PostgreSQL-authoritative sidecar, TN/Qute execution contracts, PGXS extension, and large-scale benchmarks live in
+[`systems/quantum_db/`](systems/quantum_db/). Its README is the canonical operating guide for this subsystem:
+
+```bash
+cd systems/quantum_db
+python3 -m unittest discover -s tests -v
+python3 scripts/qdb_e2e_smoke.py
+```
+
+The integration preserves this repository's original Grover experiment at the top level. It adds a separate
+`PostgreSQL → sidecar → TN/Qute/Grover → PostgreSQL recheck` path and does not commit API keys, SQLite state, native
+build products, or generated reports.
+
 ## Notes
 
 - Wall time includes cloud submission, compilation or mapping, queueing, execution, and result retrieval.

systems/quantum_db/.env.example

@@ -0,0 +1,5 @@
+QDB_SOCKET=/tmp/qdb.sock
+QDB_STATE=outputs/qdb_jobs.sqlite3
+QDB_QCLOUD_BACKEND=WK_C180
+QDB_PYTHON=python3
+# ORIGINQC_API_KEY=

systems/quantum_db/.gitignore

@@ -0,0 +1,44 @@
+# Python bytecode and virtual environments
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+env/
+
+# macOS and editors
+.DS_Store
+.idea/
+.vscode/
+
+# Secrets and local runtime state
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.sqlite3
+*.sqlite3-*
+*.sock
+*.pid
+*.log
+
+# Native PostgreSQL build outputs
+pg_extension/*.o
+pg_extension/*.dylib
+pg_extension/*.so
+pg_extension/*.bc
+pg_extension/regression.diffs
+
+# Generated reports and local outputs
+/outputs/*
+!/outputs/.gitkeep
+/results/*
+!/results/.gitkeep
+/artifacts/*
+!/artifacts/README.md
+
+# Large local corpus and historical duplicate
+/train-test-data/
+/storage-main 2/
+pyqpanda3_docs.json

systems/quantum_db/Makefile

@@ -0,0 +1,18 @@
+PYTHON ?= python3
+
+.PHONY: test sidecar large-scale pg-smoke pg-hybrid
+
+test:
+	$(PYTHON) -m unittest discover -s tests -v
+
+sidecar:
+	$(PYTHON) -m qdb.server --socket $${QDB_SOCKET:-/tmp/qdb.sock} --state $${QDB_STATE:-outputs/qdb_jobs.sqlite3}
+
+large-scale:
+	$(PYTHON) scripts/qdb_large_scale_benchmark.py --sizes $${QDB_SIZES:-10000,100000,1000000} --output $${QDB_OUTPUT:-outputs/qdb_large_scale}
+
+pg-smoke:
+	PG_CONFIG=$${PG_CONFIG:-pg_config} bash scripts/qdb_postgres_e2e_smoke.sh
+
+pg-hybrid:
+	PG_CONFIG=$${PG_CONFIG:-pg_config} bash scripts/qdb_postgres_hybrid_probe.sh

systems/quantum_db/README.md

@@ -0,0 +1,92 @@
+# Quantum DB
+
+Quantum DB is a research prototype that keeps PostgreSQL authoritative while using a local Python sidecar for TN and
+quantum candidate telemetry. Quantum/TN outputs are advisory only; PostgreSQL rechecks the original predicates before
+returning SQL rows.
+
+## Components
+
+- `qdb/`: Unix-socket sidecar, relational IR, routing, jobs, candidate contract, and large-scale benchmark.
+- `pg_extension/`: PostgreSQL 16 PGXS extension and `QuantumDBScan` custom scan.
+- `qute/`: C0–C3 query execution contracts and simulator backends.
+- `data_plane/`, `control_plane/`, `interface/`, `protocol/`, `infra/`: TN/quantum and integration layers.
+- `scripts/`, `tests/`, `config/`, `docs/`: reproducible entry points, regression tests, examples, and evidence.
+
+Detailed Git policy: [docs/REPOSITORY_LAYOUT.md](docs/REPOSITORY_LAYOUT.md).
+
+## Quick start
+
+Python 3.11+ is required. The base project has no mandatory third-party Python dependency; pyQPanda3 is optional for
+Wukong execution.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e .
+make test
+```
+
+Start the sidecar locally:
+
+```bash
+qdb-sidecar --socket /tmp/qdb.sock --state outputs/qdb_jobs.sqlite3
+```
+
+Run the no-credential smoke tests:
+
+```bash
+python3 scripts/qdb_e2e_smoke.py
+python3 scripts/qdb_large_scale_benchmark.py --sizes 10000,100000,1000000 --output outputs/qdb_large_scale
+```
+
+The large-scale report uses exact streaming traversal as its authority and reports sampling/HLL/TN estimates
+separately.
+
+## PostgreSQL
+
+Build the extension using PostgreSQL 16 development headers:
+
+```bash
+make -C pg_extension PG_CONFIG=/path/to/pg_config
+make -C pg_extension install PG_CONFIG=/path/to/pg_config
+PG_CONFIG=/path/to/pg_config make pg-smoke
+```
+
+Configure PostgreSQL with:
+
+```conf
+shared_preload_libraries = 'quantum_db'
+quantum_db.socket_path = '/tmp/qdb.sock'
+```
+
+Registered datasets reject `INSERT`, `UPDATE`, `DELETE`, and `TRUNCATE` until unregistered.
+
+## Wukong
+
+Never commit `ORIGINQC_API_KEY`, `.env`, SQLite state, native binaries, or generated hardware output. Export the token
+only in the sidecar shell:
+
+```bash
+export ORIGINQC_API_KEY='<set only in your shell>'
+export QDB_PYTHON=/path/to/pyqpanda-env/bin/python
+export QDB_QCLOUD_BACKEND=WK_C180
+bash scripts/qdb_wukong_preflight.sh
+```
+
+The explicit hardware path is:
+
+```bash
+export QDB_ALLOW_HARDWARE=1
+PG_CONFIG=/path/to/pg_config make pg-hybrid
+```
+
+It requires a finished QCloud job, a cloud job ID, binary counts, and a counts total equal to the shot count.
+
+## Upload checklist
+
+1. Run `make test` and `git diff --check`.
+2. Stage only source, tests, docs, configuration examples, and PostgreSQL SQL/C files.
+3. Keep the large `train-test-data/` corpus outside ordinary Git or use Git LFS.
+4. Do not add `storage-main 2/`.
+5. Add a license before making a public repository; no license is assumed here.

systems/quantum_db/README_QDB.md

@@ -0,0 +1,172 @@
+# Quantum DB PostgreSQL integration (detailed guide)
+
+> Start with [README.md](README.md). This file retains detailed PostgreSQL and Wukong operating notes.
+
+This directory contains the primary implementation. `storage-main 2` is a historical copy and is not used.
+
+PostgreSQL remains authoritative for SQL semantics, joins, aggregates, MVCC, and predicate rechecks. The
+`quantum_db` extension registers immutable datasets and wraps their base scans with a `QuantumDBScan` custom
+scan. The Python sidecar provides routing, TN/quantum candidate generation, durable jobs, and pyQPanda3/QCloud
+execution. Candidate keys are never treated as final SQL results.
+
+## Local development
+
+```bash
+python3 -m qdb.server --socket /tmp/qdb.sock --state outputs/qdb_jobs.sqlite3
+make -C pg_extension
+make -C pg_extension install
+```
+
+The extension build requires PostgreSQL 16 server development files. Configure
+`shared_preload_libraries = 'quantum_db'` and restart PostgreSQL so every session installs the planner hook.
+Then:
+
+```sql
+CREATE EXTENSION quantum_db;
+SELECT qdb_register_dataset('public.my_table', 'id', ARRAY['value']);
+SELECT qdb_explain('/*+ QDB_AUTO */ SELECT * FROM public.my_table WHERE value = 10');
+```
+
+The isolated PostgreSQL 16.14 validation record is in `docs/postgres_validation.md`.
+
+Set `quantum_db.socket_path` when the sidecar does not use `/tmp/qdb.sock`. Registered datasets reject
+INSERT, UPDATE, DELETE, and TRUNCATE until `qdb_unregister_dataset` is called.
+
+For Wukong, set `ORIGINQC_API_KEY` only in the sidecar environment and set `QDB_QCLOUD_BACKEND=WK_C180`
+(or the backend name provided by the installed pyQPanda3 release). Tokens are not persisted.
+Use the versioned `hardware.preflight` RPC with `{"allow_hardware": true}` to request a non-submitting capability
+check; it refuses to run without both explicit authorization and a sidecar-only token.
+It also reports `HARDWARE_SDK_UNAVAILABLE` before any network action when `pyqpanda3` cannot be imported.
+
+After the SDK and its native libraries are available, the supported entry point is:
+
+```bash
+export ORIGINQC_API_KEY='paste-the-current-key-here'
+export QDB_PYTHON=/tmp/qdb-pyqpanda-env/bin/python
+export QDB_QCLOUD_BACKEND=WK_C180
+bash scripts/qdb_wukong_preflight.sh
+```
+
+The script starts a temporary local sidecar, invokes only `hardware.preflight`, redacts its temporary log on failure,
+and removes all state afterwards. It does not submit a Wukong job.
+
+After a successful preflight, run the explicitly authorized 64-shot smoke probe with:
+
+```bash
+bash scripts/qdb_wukong_probe.sh
+```
+
+It waits for the QCloud result before returning and prints the remote job ID, shots, counts, non-secret metadata, and
+target-state analysis (observed proportion, Wilson 95% interval, and enrichment over a uniform baseline).
+The probe uses exactly eight rows with one marked address (`0x0`). Its current `grover-oracle-diffuser-v1`
+contract is a three-qubit, two-iteration Grover circuit decomposed into `U3 + CZ`; its ideal marked-state
+probability is about 94.5%. It is a hardware correctness/calibration probe, not a general quantum SQL accelerator.
+For other snapshot widths or multiple marked addresses, the sidecar retains its ideal/advisory probe and does not
+submit a misleading real-hardware circuit.
+
+`QDB_WUKONG_SHOTS` controls statistical precision (not the physical marked-state probability), while
+`QDB_GROVER_ITERATIONS` accepts `1` or `2`. A 256-shot run makes the target proportion much easier to estimate.
+On current hardware, compare both iteration counts because one iteration halves the CZ budget (12 instead of 24)
+while reducing the ideal probability from 94.5% to 78.1%:
+
+```bash
+QDB_WUKONG_SHOTS=256 QDB_GROVER_ITERATIONS=1 bash scripts/qdb_wukong_probe.sh
+QDB_WUKONG_SHOTS=256 QDB_GROVER_ITERATIONS=2 bash scripts/qdb_wukong_probe.sh
+```
+
+By default the probe sends its eight synthetic rows inline. To exercise the sidecar's durable SQLite dataset store,
+register the rows first and run the same query from that immutable snapshot:
+
+```bash
+QDB_PROBE_STORAGE=1 QDB_WUKONG_SHOTS=256 QDB_GROVER_ITERATIONS=1 bash scripts/qdb_wukong_probe.sh
+```
+
+This validates `JobStore` dataset registration/readback, but it does not exercise PostgreSQL's `qdb.datasets` or
+`QuantumDBScan`; use `scripts/qdb_postgres_e2e_smoke.sh` for the PostgreSQL integration path.
+
+On Apple Silicon, the currently packaged `pyqpanda3` wheel links to Homebrew's `libidn2`, `openssl@3`, and `zstd`.
+Install the runtime libraries once before using the virtual environment:
+
+```bash
+brew install libidn2 openssl@3 zstd
+```
+
+Run offline tests with `python3 -m unittest discover -s tests -v`. They use no network or quantum credits.
+
+The backend-neutral research framework and first-round status are documented in
+`docs/architecture_plan.md` and `docs/first_round_status.md`. Run its reproducible smoke benchmark with:
+
+```bash
+python3 -m qute.benchmark.runner --config qute/benchmark/configs/smoke.json --output outputs/qute_smoke
+```
+
+## Current execution contract
+
+`QuantumDBScan` is deliberately fail-safe: it scans only candidate keys supplied by the sidecar when the response
+asserts a complete *superset* from an immutable classical snapshot, the snapshot version matches, the artifact
+checksum matches, and PostgreSQL recheck is required. Physical candidate filtering is currently limited to
+built-in `bool`, `int2`, `int4`, and `int8` equality predicates. Text/collated values, numeric/time values,
+range operators, NULL tests, expressions, and unsupported clauses retain the native PostgreSQL scan. Any missing
+or malformed contract, stale checksum, unavailable sidecar, or unsupported predicate also performs native exact
+evaluation. JOIN, COUNT, and GROUP BY therefore keep PostgreSQL semantics. Quantum/TN estimates are advisory
+until they can provide a formally complete candidate superset; they cannot by themselves remove SQL rows.
+Registered snapshots use an atomic `begin → 256-row pages → commit` Unix-RPC upload. PostgreSQL makes one locked
+streaming pass to derive the row count/checksum and a second locked streaming pass to upload pages, so neither the
+sidecar request limit nor a full-table JSONB aggregation caps registration memory. QCloud jobs are optional and are only submitted
+after explicit hardware authorization for either a validated `quantum_ir` or a bounded probe. For routed asynchronous jobs, the sidecar now builds a bounded TN-Page (`QDB_TN`/hybrid) and/or executes
+a bounded Grover-style `QMEASURE` probe on the ideal simulator. Passing `run_qpanda_probe=true` additionally compiles
+and runs its `U3 + CZ` IR through the pyQPanda3 adapter's local fallback. If the sidecar is configured for QCloud, a
+real-device submission additionally requires `allow_hardware=true` together with `run_qpanda_probe=true` (or an explicit
+`quantum_ir`); this prevents ordinary routed SQL from consuming hardware quota. These probe outputs are explicit telemetry:
+they are never permitted to remove a classical snapshot candidate or bypass PostgreSQL recheck. `qdb_submit`, `qdb_status`,
+`qdb_result`, and successful `qdb_cancel` calls mirror the observed sidecar lifecycle into `qdb.jobs` for SQL-side
+audit; SQLite remains the durable executor state until a shared job store is introduced.
+Cancellation is terminal: a late cloud failure or completion cannot overwrite a persisted `cancelled` job state.
+
+Run a sidecar-only end-to-end smoke test (Unix RPC, dataset/job lifecycle, automatic route, candidates, and exact
+Qute query contract) with:
+
+```bash
+python3 scripts/qdb_e2e_smoke.py
+```
+
+Run large-scale streaming traversal, predicate-cardinality, distinct-cardinality (HLL), uniform sampling, Qute C0
+sample counting, and TN-page sampling experiments without using QCloud quota:
+
+```bash
+python3 scripts/qdb_large_scale_benchmark.py --sizes 10000,100000,1000000 --output outputs/qdb_large_scale
+```
+
+The report retains exact streaming counts as the authority and reports sampling/HLL error separately; it does not
+label an estimate as exact SQL output.
+
+With a PostgreSQL 16 development installation, run the complete temporary-cluster path with:
+
+```bash
+PG_CONFIG=/path/to/pg_config bash scripts/qdb_postgres_e2e_smoke.sh
+```
+
+It installs the extension into the selected PostgreSQL prefix, then creates and removes only a temporary cluster.
+
+To add the three participating acceleration components to one explicitly authorized Wukong probe, use a registered
+eight-row snapshot with one marked row. `QDB_PROBE_COMPONENTS=hybrid` activates both the TN page and the Grover
+telemetry; `QDB_PROBE_QUTE=1` records QuteEngine's C0 exact count validation in the same sidecar job:
+
+```bash
+QDB_PYTHON=/path/to/pyqpanda-env/bin/python \
+QDB_PROBE_STORAGE=1 QDB_PROBE_COMPONENTS=hybrid QDB_PROBE_QUTE=1 \
+QDB_WUKONG_SHOTS=256 QDB_GROVER_ITERATIONS=1 \
+bash scripts/qdb_wukong_probe.sh
+```
+
+For the full `PostgreSQL → registered snapshot → sidecar (TN + Qute + Grover) → PostgreSQL Custom Scan/recheck`
+experiment, the following command creates a disposable cluster and sends exactly one real-device job. It is guarded by
+`QDB_ALLOW_HARDWARE=1`; it never stores the API key in PostgreSQL, SQLite, output, or source files.
+The script fails unless the result contains `qcloud_sdk`, a cloud job ID, `JobStatus.FINISHED`, binary counts, and a
+counts total equal to the returned shot count.
+
+```bash
+QDB_PYTHON=/path/to/pyqpanda-env/bin/python QDB_ALLOW_HARDWARE=1 \
+QDB_WUKONG_SHOTS=256 QDB_GROVER_ITERATIONS=1 \
+PG_CONFIG=/path/to/pg_config bash scripts/qdb_postgres_hybrid_probe.sh
+```

systems/quantum_db/config/quantum_db.example.json

@@ -0,0 +1,10 @@
+{
+  "socket_path": "/tmp/qdb.sock",
+  "state_path": "outputs/qdb_jobs.sqlite3",
+  "backend_name": "qpanda3-sim",
+  "qcloud_backend_name": "WK_C180",
+  "num_qubits": 180,
+  "max_circuit_depth": 500,
+  "workers": 2,
+  "api_token_env": "ORIGINQC_API_KEY"
+}