symq 0.2.0__tar.gz

symq-0.2.0/.gitattributes

@@ -0,0 +1,3 @@
+# Never convert line endings: corpus files, fixtures and evidence data are pinned by SHA-256, and a
+# checkout that rewrites them (Git for Windows with core.autocrlf) would fail the integrity tests.
+* -text

symq-0.2.0/.github/CODEOWNERS

@@ -0,0 +1,3 @@
+# Review ownership. Every change goes through a pull request; nothing is merged without a
+# separate maintainer authorization (see AGENTS.md and CONTRIBUTING.md).
+* @yoch

symq-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/yoch/symq/security/policy
+    about: Do not post exploit details publicly. Follow the security policy instead.

symq-0.2.0/.github/ISSUE_TEMPLATE/correctness.yml

@@ -0,0 +1,57 @@
+name: Correctness or soundness bug
+description: A wrong verdict, a wrong witness, a crash, or an unsupported input that was accepted.
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        A wrong `equivalent` or `different` verdict is the most serious kind of report. Please
+        give the exact inputs: an `inconclusive` or `unsupported` result is not a proof, and a
+        slow run is a performance report, not a correctness bug.
+  - type: input
+    id: version
+    attributes:
+      label: SymQ version or commit SHA
+      description: Output of `python -c "import symq; print(symq.__version__)"`, or the exact commit.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Paste the output of `python -m symq doctor`.
+      render: text
+    validations:
+      required: true
+  - type: dropdown
+    id: layer
+    attributes:
+      label: Layer
+      options:
+        - Core (symq, symq.sat, backends, CLI check/anf/doctor)
+        - symq.experimental (opt-in)
+        - symq.labs (research, no API promise)
+    validations:
+      required: true
+  - type: input
+    id: theorem
+    attributes:
+      label: Theorem and engine
+      description: For example `classical_full` with `zdd-native`, or a SAT contract.
+    validations:
+      required: true
+  - type: textarea
+    id: reproducer
+    attributes:
+      label: Minimal reproducer
+      description: The smallest circuits or files and the exact call or command line. Do not attach private circuits.
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: result
+    attributes:
+      label: Expected and observed result
+      description: Include the verdict, the reason and the witness, if any.
+    validations:
+      required: true

symq-0.2.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,23 @@
+name: Feature or extension request
+description: A new gate, theorem, importer, backend or command.
+labels: [enhancement]
+body:
+  - type: textarea
+    id: statement
+    attributes:
+      label: Statement to prove or task to support
+      description: State the exact theorem or task, its input grammar and what must be refused.
+    validations:
+      required: true
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation and a concrete example
+      description: A public circuit, format or workflow that needs it.
+    validations:
+      required: true
+  - type: textarea
+    id: oracle
+    attributes:
+      label: Independent reference
+      description: How could the result be checked against a simple independent oracle?

symq-0.2.0/.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,15 @@
+name: Question
+description: How to express a verification task, or what a result means.
+labels: [question]
+body:
+  - type: textarea
+    id: question
+    attributes:
+      label: Question
+      description: What are you trying to prove, on which circuits, and what did you try?
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: SymQ version or commit SHA

symq-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+## Scope and theorem
+
+Describe the supported input grammar, ancilla preparation, observed outputs,
+theorem type (classical, SAT contract, strict HMR branch, channel, instrument)
+and what this PR does **not** establish.
+
+## Changes
+
+- Code / documentation:
+- Exact base and head SHA:
+- Dependence on other PRs, if any:
+
+## Tests and evidence
+
+- [ ] Independent reference/oracle and positive/negative mutants (when applicable)
+- [ ] Witness replay and resource/unsupported paths
+- [ ] Python/native/pure-wheel checks as relevant
+- [ ] Exact-head CI link
+- [ ] Raw experiment source/binary hashes, environment and all failure counts (if measured)
+
+## Provenance and publication
+
+- [ ] External code/corpus license and upstream commit verified
+- [ ] No secrets, private fixtures or identifying local paths
+- [ ] Historical measurements not relabeled as new holdout
+- [ ] Research conclusions and API stability stated narrowly
+- [ ] No external publication, release or merge assumed without approval
+
+## Review decision requested
+
+What is the smallest safe integration unit? Document remaining blockers and
+whether this is a maintained-code fix, experimental research, or historical
+archive. See [CONTRIBUTING.md](../CONTRIBUTING.md).

symq-0.2.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+# Keeps the SHA-pinned GitHub Actions and the bounded development tools (ruff, mypy) current.
+# The package itself has no runtime dependency.
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      dev-tools:
+        patterns: ['*']
+    commit-message:
+      prefix: build
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ['*']
+    commit-message:
+      prefix: ci

symq-0.2.0/.github/workflows/affine-basis-study.yml

@@ -0,0 +1,54 @@
+name: Affine basis and cache study
+on:
+  pull_request:
+    paths:
+      - 'src/symq/labs/affine_basis_study.py'
+      - 'src/symq/labs/affine_phase.py'
+      - 'src/symq/labs/dyadic_phase.py'
+      - 'src/symq/resources.py'
+      - 'src/symq/phase.py'
+      - 'src/symq/phase_oracle.py'
+      - 'benchmarks/affine_basis*.py'
+      - 'tests/test_affine_basis*.py'
+      - 'tests/testkit/affine_basis_oracle.py'
+      - 'docs/guide/affine-basis-study.md'
+      - '.github/workflows/affine-basis-study.yml'
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: affine-basis-study-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  qualification:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    env:
+      SYMQ_SKIP_NATIVE: '1'
+      SYMQ_TEST_REQUIRE: checkout
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.12'
+          cache: pip
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff check .
+      - run: >-
+          python -m pytest -q tests/test_affine_basis_study.py
+          tests/test_affine_basis_qualification.py tests/test_affine_phase.py
+          tests/test_public_docs.py tests/test_public_api.py
+      - run: >-
+          python -m benchmarks.affine_basis --repetitions 3
+          --output evidence/affine-basis.json
+      - run: >-
+          python -m benchmarks.affine_basis_summary evidence/affine-basis.json
+          --output evidence/affine-basis-summary.json
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: always()
+        with:
+          name: affine-basis-study-evidence
+          path: evidence/
+          if-no-files-found: error

symq-0.2.0/.github/workflows/affine-phase.yml

@@ -0,0 +1,45 @@
+name: Affine phase research
+on:
+  pull_request:
+    paths:
+      - 'src/symq/labs/affine_phase.py'
+      - 'src/symq/labs/dyadic_phase.py'
+      - 'src/symq/phase.py'
+      - 'src/symq/resources.py'
+      - 'tests/test_affine_phase*.py'
+      - 'tests/testkit/affine_phase_oracle.py'
+      - 'benchmarks/affine_phase.py'
+      - 'docs/guide/affine-phase.md'
+      - '.github/workflows/affine-phase.yml'
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: affine-phase-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  qualification:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      SYMQ_REQUIRE_NATIVE: '1'
+      SYMQ_TEST_REQUIRE: native,sat,checkout
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.12'
+          cache: pip
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff check .
+      - run: >-
+          python -m pytest -q tests/test_affine_phase.py
+          tests/test_affine_phase_qualification.py tests/test_phase8_research.py
+          tests/test_public_docs.py tests/test_public_api.py
+      - run: python -m benchmarks.affine_phase --repetitions 3 --output evidence/affine-phase.json
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: always()
+        with:
+          name: affine-phase-evidence
+          path: evidence/
+          if-no-files-found: error

symq-0.2.0/.github/workflows/affine-target-table.yml

@@ -0,0 +1,45 @@
+name: Affine target table research
+on:
+  pull_request:
+    paths:
+      - 'src/symq/labs/affine_table.py'
+      - 'src/symq/labs/anchored_stream.py'
+      - 'src/symq/labs/anchored_kraus.py'
+      - 'src/symq/labs/kraus_graph.py'
+      - 'src/symq/resources.py'
+      - 'benchmarks/affine_table.py'
+      - 'tests/test_affine_table.py'
+      - 'tests/test_affine_table_independent.py'
+      - 'tests/testkit/affine_loader_cases.py'
+      - 'tests/testkit/table_channel_oracle.py'
+      - 'docs/labs/affine-target-tables.md'
+      - '.github/workflows/affine-target-table.yml'
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  qualification:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      SYMQ_TEST_REQUIRE: sat
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.12'
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff check .
+      - run: python -m pytest -q tests/test_affine_table.py tests/test_affine_table_independent.py tests/test_anchored_stream.py tests/test_kraus_graph.py tests/test_anchored_independent.py
+      - run: |
+          mkdir -p evidence
+          git rev-parse HEAD > evidence/commit.txt
+          git rev-parse 'HEAD^{tree}' > evidence/tree.txt
+          git diff --exit-code
+          python -m benchmarks.affine_table --programs 100 --output evidence/affine-target-table.json
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: always()
+        with:
+          name: affine-target-table-evidence
+          path: evidence/
+          if-no-files-found: error

symq-0.2.0/.github/workflows/anchored-kraus.yml

@@ -0,0 +1,36 @@
+name: Anchored Kraus symbolic research
+on:
+  pull_request:
+    paths:
+      - 'src/symq/labs/anchored_kraus.py'
+      - 'benchmarks/anchored_kraus.py'
+      - 'tests/test_anchored_kraus.py'
+      - 'docs/labs/research-outlook-20261102.md'
+      - '.github/workflows/anchored-kraus.yml'
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  qualification:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.12'
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff check .
+      - run: python -m pytest -q tests/test_anchored_kraus.py tests/test_hmr_table_contract.py
+      - run: |
+          mkdir -p evidence
+          git rev-parse HEAD > evidence/commit.txt
+          git rev-parse 'HEAD^{tree}' > evidence/tree.txt
+          git diff --exit-code
+          python -m benchmarks.anchored_kraus --programs 400 --output evidence/anchored-kraus.json
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: always()
+        with:
+          name: anchored-kraus-evidence
+          path: evidence/
+          if-no-files-found: error

symq-0.2.0/.github/workflows/backward-ancilla.yml

@@ -0,0 +1,50 @@
+name: Backward ancilla research
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'src/symq/labs/backward_ancilla.py'
+      - 'src/symq/experimental/hybrid.py'
+      - 'src/symq/resources.py'
+      - 'benchmarks/backward_ancilla.py'
+      - 'benchmarks/corpus/qualtran/**'
+      - 'tests/test_backward_ancilla*.py'
+      - '.github/workflows/backward-ancilla.yml'
+  pull_request:
+    paths:
+      - 'src/symq/labs/backward_ancilla.py'
+      - 'src/symq/experimental/hybrid.py'
+      - 'src/symq/resources.py'
+      - 'benchmarks/backward_ancilla.py'
+      - 'benchmarks/corpus/qualtran/**'
+      - 'tests/test_backward_ancilla*.py'
+      - '.github/workflows/backward-ancilla.yml'
+permissions:
+  contents: read
+concurrency:
+  group: backward-ancilla-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  qualification:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.12'
+          cache: pip
+      - run: python -m pip install -e '.[dev]'
+        env:
+          SYMQ_SKIP_NATIVE: '1'
+      - run: >-
+          python -m pytest -q tests/test_backward_ancilla.py
+          tests/test_backward_ancilla_qualification.py
+          tests/test_hybrid_channel_research.py tests/test_public_docs.py
+      - run: python -m benchmarks.backward_ancilla --repetitions 3 --output evidence/backward-ancilla.json
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: always()
+        with:
+          name: backward-ancilla-evidence
+          path: evidence/
+          if-no-files-found: error

symq-0.2.0/.github/workflows/channel-certificates.yml

@@ -0,0 +1,48 @@
+name: HMR certificate research
+on:
+  pull_request:
+    paths:
+      - 'src/symq/**'
+      - 'tests/test_channel_certificate*.py'
+      - 'benchmarks/channel_certificate.py'
+      - 'benchmarks/corpus/**'
+      - 'docs/guide/channel-certificates.md'
+      - 'pyproject.toml'
+      - '.github/workflows/channel-certificates.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'src/symq/**'
+      - 'tests/test_channel_certificate*.py'
+      - 'benchmarks/channel_certificate.py'
+      - 'benchmarks/corpus/**'
+      - '.github/workflows/channel-certificates.yml'
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: research-channel-certificates-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  qualification:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    env:
+      SYMQ_SKIP_NATIVE: '1'
+      SYMQ_TEST_REQUIRE: checkout
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.12'
+          cache: pip
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -q tests/test_channel_certificate.py tests/test_channel_certificate_qualification.py tests/test_channel_criterion.py tests/test_public_api.py
+      - name: Reproduce bounded development qualification
+        run: python -m benchmarks.channel_certificate --repetitions 3 --output evidence/channel-certificates.json
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: always()
+        with:
+          name: channel-certificates-evidence
+          path: evidence/
+          if-no-files-found: error