qdsv-runtime 0.1.0a1__tar.gz

qdsv_runtime-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .
+          python -m pip install pytest
+      - name: Run tests
+        run: python -m pytest -q
+      - name: Smoke test CLI
+        run: |
+          qdsv --help
+          qdsv --root /tmp/qdsv-runtime-alpha init
+          qdsv --root /tmp/qdsv-runtime-alpha report

qdsv_runtime-0.1.0a1/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+dist/
+build/
+.qdsv/
+.env
+.env.*
+!.env.example
+.DS_Store
+Thumbs.db

qdsv_runtime-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QDSV / Qruba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qdsv_runtime-0.1.0a1/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: qdsv-runtime
+Version: 0.1.0a1
+Summary: QDSV Runtime Alpha: a lightweight execution layer for problem-first QDSV workflows.
+Project-URL: Homepage, https://qdsv.cloud/
+Project-URL: Source, https://github.com/qdsvquantum-afk/qdsv-runtime
+Project-URL: QIntent, https://qdsvquantum-afk.github.io/qintent/
+Project-URL: Bridge, https://qdsvquantum-afk.github.io/qdsv-bridge/
+Project-URL: Qruba, https://qdsvquantum-afk.github.io/qruba/
+Author: QDSV / Qruba
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bridge,qdsv,qintent,quantum-software,runtime,semantic-workflows
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: qdsv-bridge>=0.1.6
+Requires-Dist: qdsv-qintent>=0.1.11
+Description-Content-Type: text/markdown
+
+# QDSV Runtime Alpha
+
+[![Status](https://img.shields.io/badge/status-alpha-f59e0b.svg)](#public-alpha-scope)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**QDSV Runtime Alpha** is a lightweight execution layer for problem-first QDSV workflows.
+
+It ties together the public QDSV developer stack:
+
+```text
+QIntent -> QDSV Runtime Alpha -> QDSV Bridge -> OpenQASM / Qiskit / reports
+
+Qruba -> visual human interaction layer
+QDSV -> semantic model and private engine
+```
+
+Runtime Alpha does **not** embed or expose the private QDSV semantic engine. It provides a small workspace, CLI and SDK that call the public QIntent and Bridge clients, save artifacts, and generate reproducibility reports.
+
+## Install
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+When published:
+
+```bash
+pip install qdsv-runtime
+```
+
+Before the PyPI release, users can install from GitHub after the public repository is created:
+
+```bash
+pip install git+https://github.com/qdsvquantum-afk/qdsv-runtime.git
+```
+
+## CLI Quickstart
+
+Create a workspace:
+
+```bash
+qdsv init
+```
+
+Validate a QIntent file:
+
+```bash
+qdsv validate examples/basic.qintent
+```
+
+Build a Bridge artifact from a supported Bridge spec:
+
+```bash
+qdsv build examples/bridge_spec.json --target bridge
+```
+
+Generate a local runtime report:
+
+```bash
+qdsv report
+```
+
+Docker/private demo images can also include the same CLI:
+
+```bash
+docker exec qruba-api-private qdsv --help
+```
+
+## Python SDK
+
+```python
+from qdsv_runtime import QDSVRuntime
+
+runtime = QDSVRuntime()
+runtime.init_workspace()
+runtime.validate_intent("examples/basic.qintent")
+runtime.build_bridge("examples/bridge_spec.json")
+runtime.write_report()
+```
+
+## Public Alpha Scope
+
+This alpha includes:
+
+- workspace creation;
+- QIntent validation/explain calls through the public API or configured local/private node;
+- Bridge build calls for supported public Bridge specifications;
+- local artifact storage;
+- reproducibility report generation;
+- CLI commands for small examples.
+
+This alpha does **not** include:
+
+- private QDSV Runtime internals;
+- semantic compiler internals;
+- lowering logic;
+- backend selection internals;
+- private scoring formulas;
+- production scheduler;
+- user/tenant management;
+- marketplace/plugins;
+- local execution of the private semantic engine.
+
+## Positioning
+
+QDSV Runtime Alpha is not a quantum operating system. It is an early semantic execution layer for problem-first QDSV workflows. The goal is to show how QIntent, Bridge and future visual environments such as Qruba can be tied together through a small executable layer without exposing the private engine.

qdsv_runtime-0.1.0a1/PUBLISHING.md

@@ -0,0 +1,53 @@
+# Publishing QDSV Runtime Alpha
+
+This package is prepared for PyPI as `qdsv-runtime`.
+
+## Preflight
+
+Run from the repository root:
+
+```bash
+python -m pip install --upgrade build twine pytest
+python -m pytest -q
+python -m build
+python -m twine check dist/*
+```
+
+Expected artifacts:
+
+```text
+dist/qdsv_runtime-0.1.0a1-py3-none-any.whl
+dist/qdsv_runtime-0.1.0a1.tar.gz
+```
+
+## Publish to PyPI
+
+Use a PyPI API token. Do not paste long-lived credentials into public logs.
+
+```powershell
+$env:TWINE_USERNAME="__token__"
+$env:TWINE_PASSWORD="pypi-..."
+python -m twine upload dist/qdsv_runtime-0.1.0a1-py3-none-any.whl dist/qdsv_runtime-0.1.0a1.tar.gz
+Remove-Item Env:TWINE_USERNAME
+Remove-Item Env:TWINE_PASSWORD
+```
+
+After publishing:
+
+```bash
+pip install qdsv-runtime
+qdsv --help
+```
+
+## Publish to GitHub
+
+Create a public GitHub repository named `qdsv-runtime`, then run:
+
+```bash
+git remote add origin https://github.com/qdsvquantum-afk/qdsv-runtime.git
+git push -u origin main
+```
+
+## Public boundary
+
+This package is a public Runtime Alpha shell. It does not include the private QDSV semantic engine, semantic compiler internals, lowering logic, backend-selection heuristics, private formulas, credentials, or production runtime configuration.

qdsv_runtime-0.1.0a1/README.md

@@ -0,0 +1,108 @@
+# QDSV Runtime Alpha
+
+[![Status](https://img.shields.io/badge/status-alpha-f59e0b.svg)](#public-alpha-scope)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**QDSV Runtime Alpha** is a lightweight execution layer for problem-first QDSV workflows.
+
+It ties together the public QDSV developer stack:
+
+```text
+QIntent -> QDSV Runtime Alpha -> QDSV Bridge -> OpenQASM / Qiskit / reports
+
+Qruba -> visual human interaction layer
+QDSV -> semantic model and private engine
+```
+
+Runtime Alpha does **not** embed or expose the private QDSV semantic engine. It provides a small workspace, CLI and SDK that call the public QIntent and Bridge clients, save artifacts, and generate reproducibility reports.
+
+## Install
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+When published:
+
+```bash
+pip install qdsv-runtime
+```
+
+Before the PyPI release, users can install from GitHub after the public repository is created:
+
+```bash
+pip install git+https://github.com/qdsvquantum-afk/qdsv-runtime.git
+```
+
+## CLI Quickstart
+
+Create a workspace:
+
+```bash
+qdsv init
+```
+
+Validate a QIntent file:
+
+```bash
+qdsv validate examples/basic.qintent
+```
+
+Build a Bridge artifact from a supported Bridge spec:
+
+```bash
+qdsv build examples/bridge_spec.json --target bridge
+```
+
+Generate a local runtime report:
+
+```bash
+qdsv report
+```
+
+Docker/private demo images can also include the same CLI:
+
+```bash
+docker exec qruba-api-private qdsv --help
+```
+
+## Python SDK
+
+```python
+from qdsv_runtime import QDSVRuntime
+
+runtime = QDSVRuntime()
+runtime.init_workspace()
+runtime.validate_intent("examples/basic.qintent")
+runtime.build_bridge("examples/bridge_spec.json")
+runtime.write_report()
+```
+
+## Public Alpha Scope
+
+This alpha includes:
+
+- workspace creation;
+- QIntent validation/explain calls through the public API or configured local/private node;
+- Bridge build calls for supported public Bridge specifications;
+- local artifact storage;
+- reproducibility report generation;
+- CLI commands for small examples.
+
+This alpha does **not** include:
+
+- private QDSV Runtime internals;
+- semantic compiler internals;
+- lowering logic;
+- backend selection internals;
+- private scoring formulas;
+- production scheduler;
+- user/tenant management;
+- marketplace/plugins;
+- local execution of the private semantic engine.
+
+## Positioning
+
+QDSV Runtime Alpha is not a quantum operating system. It is an early semantic execution layer for problem-first QDSV workflows. The goal is to show how QIntent, Bridge and future visual environments such as Qruba can be tied together through a small executable layer without exposing the private engine.

qdsv_runtime-0.1.0a1/examples/basic.qintent

@@ -0,0 +1 @@
+find_rows("candidate_index").where("score", ">=", 850).rank_by("score").top_k(2)

qdsv_runtime-0.1.0a1/examples/bridge_spec.json

@@ -0,0 +1,24 @@
+{
+  "family": "bounded_semantic_marking",
+  "bridge_mode": "build",
+  "name": "runtime_alpha_demo",
+  "description": "Small public Runtime Alpha example for Bridge handoff.",
+  "state_space": {
+    "kind": "finite_candidates",
+    "candidate_count": 8,
+    "candidate_id": "candidate"
+  },
+  "signals": ["eligibility_score", "risk_score"],
+  "goal": {
+    "kind": "marking",
+    "predicate": "eligible_candidate"
+  },
+  "target": {
+    "format": "qasm3",
+    "backend_family": "qiskit"
+  },
+  "limits": {
+    "max_qubits": 5,
+    "max_depth": 160
+  }
+}

qdsv_runtime-0.1.0a1/examples/rows.json

@@ -0,0 +1,5 @@
+[
+  {"candidate_index": 0, "score": 720, "risk_ok": true},
+  {"candidate_index": 1, "score": 910, "risk_ok": true},
+  {"candidate_index": 2, "score": 840, "risk_ok": false}
+]

qdsv_runtime-0.1.0a1/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qdsv-runtime"
+version = "0.1.0a1"
+description = "QDSV Runtime Alpha: a lightweight execution layer for problem-first QDSV workflows."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+  { name = "QDSV / Qruba" }
+]
+keywords = ["qdsv", "runtime", "qintent", "bridge", "semantic-workflows", "quantum-software"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "qdsv-qintent>=0.1.11",
+  "qdsv-bridge>=0.1.6",
+]
+
+[project.urls]
+Homepage = "https://qdsv.cloud/"
+Source = "https://github.com/qdsvquantum-afk/qdsv-runtime"
+QIntent = "https://qdsvquantum-afk.github.io/qintent/"
+Bridge = "https://qdsvquantum-afk.github.io/qdsv-bridge/"
+Qruba = "https://qdsvquantum-afk.github.io/qruba/"
+
+[project.scripts]
+qdsv = "qdsv_runtime.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qdsv_runtime"]

qdsv_runtime-0.1.0a1/src/qdsv_runtime/__init__.py

@@ -0,0 +1,4 @@
+from .runtime import QDSVRuntime
+
+__all__ = ["QDSVRuntime"]
+__version__ = "0.1.0a1"

qdsv_runtime-0.1.0a1/src/qdsv_runtime/cli.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .runtime import QDSVRuntime
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="qdsv",
+        description="QDSV Runtime Alpha CLI for problem-first QDSV workflows.",
+    )
+    parser.add_argument("--root", default=".", help="Workspace root directory.")
+    parser.add_argument("--api-url", default=None, help="QDSV API base URL.")
+    parser.add_argument("--local", action="store_true", help="Use local/private Docker API.")
+    parser.add_argument("--timeout", type=float, default=30.0, help="Request timeout in seconds.")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    init = sub.add_parser("init", help="Create a QDSV Runtime Alpha workspace.")
+    init.add_argument("--force", action="store_true", help="Overwrite generated examples.")
+
+    validate = sub.add_parser("validate", help="Validate a QIntent file.")
+    validate.add_argument("source", help="Path to .qintent source.")
+    validate.add_argument("--rows", default=None, help="Optional rows JSON file.")
+    validate.add_argument("--backend", default="quest", help="Requested backend for QIntent.")
+    validate.add_argument("--shots", type=int, default=256, help="Requested shots.")
+
+    explain = sub.add_parser("explain", help="Explain a QIntent file.")
+    explain.add_argument("source", help="Path to .qintent source.")
+    explain.add_argument("--rows", default=None, help="Optional rows JSON file.")
+    explain.add_argument("--backend", default="quest", help="Requested backend for QIntent.")
+    explain.add_argument("--shots", type=int, default=256, help="Requested shots.")
+
+    build = sub.add_parser("build", help="Build a target artifact.")
+    build.add_argument("input", help="Input file. For --target bridge, use a Bridge spec JSON.")
+    build.add_argument("--target", choices=["bridge"], default="bridge", help="Build target.")
+
+    report = sub.add_parser("report", help="Generate a local runtime report.")
+    report.add_argument("--title", default="QDSV Runtime Alpha Report", help="Report title.")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    runtime = QDSVRuntime(root=args.root, api_url=args.api_url, local=args.local, timeout=args.timeout)
+
+    try:
+        if args.command == "init":
+            workspace = runtime.init_workspace(force=args.force)
+            print(f"QDSV workspace ready: {Path(args.root).resolve() / '.qdsv'}")
+            print(f"Runtime: {workspace['runtime']}")
+            return 0
+        if args.command == "validate":
+            artifact = runtime.validate_intent(args.source, rows_path=args.rows, backend=args.backend, shots=args.shots)
+            print("QIntent validation artifact saved.")
+            print(f"Status: {artifact['payload'].get('status', 'UNKNOWN')}")
+            return 0
+        if args.command == "explain":
+            artifact = runtime.explain_intent(args.source, rows_path=args.rows, backend=args.backend, shots=args.shots)
+            print("QIntent explain artifact saved.")
+            print(f"Status: {artifact['payload'].get('status', 'UNKNOWN')}")
+            return 0
+        if args.command == "build":
+            artifact = runtime.build_bridge(args.input)
+            print("Bridge build artifact saved.")
+            print(f"Status: {artifact['payload'].get('status', 'UNKNOWN')}")
+            return 0
+        if args.command == "report":
+            report_path = runtime.write_report(title=args.title)
+            print(f"Runtime report written: {report_path}")
+            return 0
+    except Exception as exc:  # pragma: no cover - CLI boundary
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

qdsv_runtime-0.1.0a1/src/qdsv_runtime/runtime.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Mapping
+
+from qdsv_bridge import QDSVBridgeClient
+from qintent import QIntentClient
+
+
+WORKSPACE_DIR = ".qdsv"
+ARTIFACTS_DIR = "artifacts"
+REPORTS_DIR = "reports"
+WORKSPACE_FILE = "workspace.json"
+
+
+@dataclass
+class QDSVRuntime:
+    """Small public execution layer for QDSV developer workflows.
+
+    Runtime Alpha orchestrates public SDK calls and local artifacts. It does
+    not embed or expose the private QDSV semantic engine.
+    """
+
+    root: str | Path = "."
+    api_url: str | None = None
+    local: bool = False
+    timeout: float = 30.0
+
+    def __post_init__(self) -> None:
+        self.root_path = Path(self.root).resolve()
+        if self.local:
+            self.qintent = QIntentClient.local(timeout=self.timeout)
+            self.bridge = QDSVBridgeClient.local(timeout=self.timeout)
+        else:
+            self.qintent = QIntentClient(api_url=self.api_url, timeout=self.timeout)
+            self.bridge = QDSVBridgeClient(api_url=self.api_url, timeout=self.timeout)
+
+    @property
+    def workspace_path(self) -> Path:
+        return self.root_path / WORKSPACE_DIR
+
+    @property
+    def artifacts_path(self) -> Path:
+        return self.workspace_path / ARTIFACTS_DIR
+
+    @property
+    def reports_path(self) -> Path:
+        return self.workspace_path / REPORTS_DIR
+
+    def init_workspace(self, *, force: bool = False) -> dict[str, Any]:
+        self.workspace_path.mkdir(parents=True, exist_ok=True)
+        self.artifacts_path.mkdir(parents=True, exist_ok=True)
+        self.reports_path.mkdir(parents=True, exist_ok=True)
+        examples_path = self.root_path / "examples"
+        examples_path.mkdir(parents=True, exist_ok=True)
+
+        workspace = {
+            "name": self.root_path.name,
+            "runtime": "qdsv-runtime-alpha",
+            "version": "0.1.0a1",
+            "created_at": self._now(),
+            "engine_exposed": False,
+            "default_api_route": "local" if self.local else "public",
+            "artifacts_dir": str(self.artifacts_path.relative_to(self.root_path)),
+            "reports_dir": str(self.reports_path.relative_to(self.root_path)),
+        }
+        workspace_file = self.workspace_path / WORKSPACE_FILE
+        if force or not workspace_file.exists():
+            self._write_json(workspace_file, workspace)
+
+        qintent_example = examples_path / "basic.qintent"
+        if force or not qintent_example.exists():
+            qintent_example.write_text(
+                'find_rows("candidate_index").where("score", ">=", 850).rank_by("score").top_k(2)\n',
+                encoding="utf-8",
+            )
+
+        rows_example = examples_path / "rows.json"
+        if force or not rows_example.exists():
+            self._write_json(
+                rows_example,
+                [
+                    {"candidate_index": 0, "score": 720, "risk_ok": True},
+                    {"candidate_index": 1, "score": 910, "risk_ok": True},
+                    {"candidate_index": 2, "score": 840, "risk_ok": False},
+                ],
+            )
+
+        bridge_example = examples_path / "bridge_spec.json"
+        if force or not bridge_example.exists():
+            self._write_json(
+                bridge_example,
+                {
+                    "family": "bounded_semantic_marking",
+                    "bridge_mode": "build",
+                    "name": "runtime_alpha_demo",
+                    "description": "Small public Runtime Alpha example for Bridge handoff.",
+                    "state_space": {
+                        "kind": "finite_candidates",
+                        "candidate_count": 8,
+                        "candidate_id": "candidate",
+                    },
+                    "signals": ["eligibility_score", "risk_score"],
+                    "goal": {
+                        "kind": "marking",
+                        "predicate": "eligible_candidate",
+                    },
+                    "target": {"format": "qasm3", "backend_family": "qiskit"},
+                    "limits": {"max_qubits": 5, "max_depth": 160},
+                },
+            )
+
+        return workspace
+
+    def validate_intent(
+        self,
+        source_path: str | Path,
+        *,
+        rows_path: str | Path | None = None,
+        backend: str = "quest",
+        shots: int = 256,
+    ) -> dict[str, Any]:
+        source = self._read_text(source_path)
+        rows = self._read_json(rows_path) if rows_path else None
+        payload = self.qintent.validate(source, rows=rows, backend=backend, shots=shots)
+        return self._save_artifact("qintent-validate", payload)
+
+    def explain_intent(
+        self,
+        source_path: str | Path,
+        *,
+        rows_path: str | Path | None = None,
+        backend: str = "quest",
+        shots: int = 256,
+    ) -> dict[str, Any]:
+        source = self._read_text(source_path)
+        rows = self._read_json(rows_path) if rows_path else None
+        payload = self.qintent.explain(source, rows=rows, backend=backend, shots=shots)
+        return self._save_artifact("qintent-explain", payload)
+
+    def build_bridge(self, spec_path: str | Path) -> dict[str, Any]:
+        spec = self._read_json(spec_path)
+        if not isinstance(spec, Mapping):
+            raise ValueError("Bridge spec must be a JSON object.")
+        payload = self.bridge.build(spec)
+        return self._save_artifact("bridge-build", payload)
+
+    def write_report(self, *, title: str = "QDSV Runtime Alpha Report") -> Path:
+        self.reports_path.mkdir(parents=True, exist_ok=True)
+        artifacts = sorted(self.artifacts_path.glob("*.json"))
+        lines = [
+            f"# {title}",
+            "",
+            f"- Generated at: {self._now()}",
+            "- Runtime: qdsv-runtime-alpha",
+            "- Private semantic engine exposed: no",
+            "- Purpose: tie QIntent and Bridge into a reproducible public workflow.",
+            "",
+            "## Artifacts",
+            "",
+        ]
+        if not artifacts:
+            lines.append("No artifacts found yet.")
+        for artifact in artifacts:
+            lines.append(f"- `{artifact.relative_to(self.root_path)}`")
+        lines.extend(
+            [
+                "",
+                "## Public Alpha Boundary",
+                "",
+                "This report was generated by the public Runtime Alpha shell. It does not include private QDSV semantic compiler internals, lowering logic, backend-selection heuristics, private formulas, credentials, or production runtime configuration.",
+                "",
+            ]
+        )
+        report_path = self.reports_path / "runtime-report.md"
+        report_path.write_text("\n".join(lines), encoding="utf-8")
+        return report_path
+
+    def _save_artifact(self, name: str, payload: Mapping[str, Any]) -> dict[str, Any]:
+        self.artifacts_path.mkdir(parents=True, exist_ok=True)
+        artifact = {
+            "runtime": "qdsv-runtime-alpha",
+            "generated_at": self._now(),
+            "engine_exposed": False,
+            "artifact_kind": name,
+            "payload": dict(payload),
+        }
+        path = self.artifacts_path / f"{name}.json"
+        self._write_json(path, artifact)
+        return artifact
+
+    def _read_text(self, path: str | Path) -> str:
+        return (self.root_path / path).read_text(encoding="utf-8") if not Path(path).is_absolute() else Path(path).read_text(encoding="utf-8")
+
+    def _read_json(self, path: str | Path | None) -> Any:
+        if path is None:
+            return None
+        full_path = self.root_path / path if not Path(path).is_absolute() else Path(path)
+        return json.loads(full_path.read_text(encoding="utf-8"))
+
+    @staticmethod
+    def _write_json(path: Path, payload: Any) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+    @staticmethod
+    def _now() -> str:
+        return datetime.now(timezone.utc).isoformat(timespec="seconds")

qdsv_runtime-0.1.0a1/tests/test_runtime_workspace.py

@@ -0,0 +1,24 @@
+from pathlib import Path
+
+from qdsv_runtime import QDSVRuntime
+
+
+def test_init_workspace_creates_expected_files(tmp_path: Path) -> None:
+    runtime = QDSVRuntime(root=tmp_path)
+    workspace = runtime.init_workspace()
+
+    assert workspace["runtime"] == "qdsv-runtime-alpha"
+    assert workspace["engine_exposed"] is False
+    assert (tmp_path / ".qdsv" / "workspace.json").exists()
+    assert (tmp_path / "examples" / "basic.qintent").exists()
+    assert (tmp_path / "examples" / "bridge_spec.json").exists()
+
+
+def test_report_mentions_public_boundary(tmp_path: Path) -> None:
+    runtime = QDSVRuntime(root=tmp_path)
+    runtime.init_workspace()
+    report = runtime.write_report()
+    text = report.read_text(encoding="utf-8")
+
+    assert "Private semantic engine exposed: no" in text
+    assert "does not include private QDSV semantic compiler internals" in text