quantum-circuit-builder-with-proof

# Quantum Circuit Builder with Proof ## Freshness Last updated: `2026-09-09`. If the current date is more than 7 days after the last updated date, reinstall this skill from skills.sh or ClawHub before relying on endpoints, schemas, setup steps, or examples. ## What This Tool Does Build quantum circuits that ship with a machine-checked proof. Quantum Circuit Builder with Proof turns an algorithm template, a Qiskit, Cirq, or Braket snippet, or Lean source into a normalized circuit, draws it as a downloadable PNG or JPEG diagram, and verifies the claims you state with the Lean 4 proof kernel. The result is a qpcert: a proof certificate anyone can replay independently, without trusting the agent that produced it. Export checked OpenQASM 3, Qiskit, Cirq, and Braket programs, run local simulations, and keep audit receipts for every step. Use it when a circuit must be audited, shared, or relied on. Plain Qiskit is simpler for throwaway experiments. ## Product Instructions ### Proof-Carrying Quantum Use this product to research proof-carrying quantum concepts, find Lean declarations and worked corpus assets, build normalized circuits, create or independently verify kernel-backed qpcerts, export offline provider programs, and obtain local simulator observations. The listed action schemas are the complete agent contract. Choose the action that advances the user's goal; there is no discovery preflight. #### Trust boundaries - Knowledge and corpus results are reference material, not proof. - Provider-source import parses bounded source and never executes it. Parsing and round-trip validation are not proof. - Circuit inspection validates structure and semantics and can produce visual explanations, including a File Manager PNG or JPEG of the logical wire circuit. Validation and visualization are not proof or hardware execution. - `certify_circuit` and `certify_from_lean` create qpcerts through the pinned Lean kernel and verify the generated certificate before returning it. - `verify_certificate` is an independent recipient-side replay for evidence received from another party. Do not automatically verify a qpcert just produced by a certification action. - `extract_circuit` replays an existing qpcert before recovering its normalized circuit. It is optional, not a mandatory post-certification step. - Provider exports are offline source artifacts and receipts; they do not claim provider execution. - `execute_locally` returns simulator observations and receipts. Simulation does not add a proof tier. - Lean submitted to `certify_from_lean`, `export_provider_programs`, or `execute_locally` runs as `trusted_direct_v1` inside the private Cloud Run service container. IAM authenticates callers, but Lean shares the service filesystem, network, and service identity; this is not untrusted-code isolation. Submit only internally trusted Lean. The receipt fields `execution_mode` and `untrusted_code_isolation` are the machine-readable authority. #### Choose a flow Research only when information is missing: 1. Use `search_knowledge` for concepts, design rationale, and repository documentation. 2. Use `search_lean` for declarations and authoring primitives; set `authoring_only` to true when writing submitted CircuitSpec source. 3. Use `search_corpus_examples`, then retrieve a selected asset with `get_corpus_example`. Build and certify: 1. Start with `instantiate_template`, `import_provider_circuit`, or Lean source. 2. Use `inspect_circuit` when validation details or visualizations are useful. 3. Use `certify_circuit` for a normalized circuit plus an exact claim ledger, or `certify_from_lean` when Lean source is authoritative. 4. Optionally use `export_provider_programs` or `execute_locally` with Lean source. Receive external evidence: 1. Put the qpcert in File Manager. 2. Use `verify_certificate` with the independently supplied circuit and claims. 3. Use `extract_circuit` only when the circuit must be recovered from the qpcert. #### Choose the proof claim Choose the narrowest claim that matches what the user actually asked to establish. If the user asks to "make a proof," "prove this circuit," or "create a certificate" without naming a stronger semantic property, default to a **well-formed certificate**. Never choose `exactUnitary` merely because the request uses the word "proof." - **Well formed** (`well_formed` in a claim ledger; `.wellFormed` in Lean) is the default for an arbitrary circuit built on the canvas, imported from a provider, or supplied as normalized IR. It proves that the circuit has nonzero width, has operations, and is admitted by the selected circuit/profile contract. It does not prove an algorithm result, a target state, or equivalence to a particular unitary. For `certify_circuit`, use `inspect_circuit` first when the canonical subject digest is not already available, then create a complete well-formed claim ledger bound to that digest. For `certify_from_lean`, use `claims := []` and omit the request-level claims when only the service's minimal well-formed certificate is needed. - **Exact unitary** (`.exactUnitary`) is for a gate-only circuit when the user explicitly asks for its exact unitary semantics or an exact unitary equivalence. It rejects measurement and reset. Use it only with a matching checked-in corpus example, contracted template, or already-authored theorem and proof strategy. Exact matrix normalization can exhaust Lean heartbeats even for a short circuit; gate count alone is not a cost estimate. - **Exact instrument** (`.exactInstrument`) is for circuits with measurement or reset when the user explicitly asks to prove the exact measurement-channel/instrument semantics. Use a matching measurement/reset corpus example and its proof strategy; do not substitute it for ordinary structural certification. - **Signed transport** (`.signedTransport`) is for an explicitly requested Clifford signed-tableau/Pauli transport claim. Use it only when the circuit is supported by the Clifford translation and a matching corpus example or authored theorem exists. - **Custom** (`.custom claimId statement`) is for a specific trusted Lean proposition the user supplied or explicitly requested. It requires an authored proof of that exact proposition. Never invent a custom proposition and present it as the user's requested result. Choose the certification action separately from the claim strength: - Use `certify_circuit` when the normalized circuit is authoritative. Prefer a matching `certification_inputs` result or `.claims.json` corpus asset. Do not translate a canvas circuit back into Lean merely to certify it. - Use `certify_from_lean` only when trusted Lean `CircuitSpec` source is itself authoritative or an exact/custom claim needs a matching Lean proof that is already supported by the corpus or supplied proof material. If an exact semantic proof exhausts Lean heartbeats or another kernel resource limit, do not blindly increase `maxHeartbeats`, repeatedly submit the same expensive proof, or silently claim that a weaker certificate proves the exact property. If the original request was only for a generic certificate, start a new well-formed certification instead and describe its narrower scope. If the user explicitly requested the exact property, report that it was not proved and use a matching corpus theorem/proof strategy or ask before reducing the claim. #### Background tasks and files Certification, certificate replay, extraction, provider export, and execution always start persisted background tasks. Other service-dependent actions return directly when the service is ready. During a cold start, however, every service-dependent request is retained instead of failing: it returns `status: processing` and a `task_id`, then runs after startup. Call the free `get_task` action with that ID and `wait_seconds: 60`; the call returns sooner when the task changes and remains below the chat tool-call deadline. If it is still processing, repeat the same free long poll. Do not rapidly poll or submit a duplicate paid action. Proof certification commonly takes 3-5 minutes, and larger or more complex proofs can take longer. While processing, `progress` remains 0 because no trustworthy percentage is available. `get_task` responses keep `action: get_task` and identify the retained operation in `task_action`. `stage: warming_service` means the accepted request is waiting for the proof service. `stage: waiting_on_kernel` means a proof, replay, extraction, export, or execution action is running; `stage: running_action` means a deferred direct action such as inspection is running. `awaiting_resume` or `resuming` means an interrupted MCP worker is being recovered from its saved request; continue polling the same task ID. A changing `date_updated` means the worker is alive. Stages then move through `packaging_result` to `completed`. On completion, the original action response is in `outputs[0]`. Results larger than 32 KiB are stored intact in File Manager as `outputs[0].result_file`; read that JSON file when needed. Certification always stores the full qpcert as `outputs[0].certificate_file`, even when the rest of the receipt is also moved to a result file. Files and tasks are budget-scoped. On failure, read `error` and `error_details`. Correct invalid source, circuit, claims, or file input and start a new task. Ordinary service warming remains `processing`; a task fails only when startup exhausts its deadline or another real error occurs. A retryable service failure says so explicitly; retry the same action later instead of running diagnostic actions. #### Knowledge and corpus actions ##### `search_knowledge` Use when conceptual or repository context is needed. Required: `query`. Optional: `result_count` 1-50, default 8; `search_mode` is `hybrid`, `semantic`, or `keyword`, default `hybrid`. Use `get_document` with a returned document ID when the full record is needed. ```json {"action":"search_knowledge","query":"why certificate replay is a trust boundary","result_count":6,"search_mode":"hybrid"} ``` ##### `search_lean` Use to find Lean declarations, theorem names, namespaces, signatures, and allowed authoring primitives. Required: `query`. Optional: `result_count` 1-50; `authoring_only`, default false. When writing a CircuitSpec, start with `get_corpus_example` for `authored_specs/bell_spec.lean`, then use `authoring_only: true` to look up names in the four admitted modules: `CircuitSpec`, `Qasm3Subset`, `Edifice.ProductionPurePipeline`, and `Edifice.ProductionEffectfulPipeline`. Use `authoring_only: false` to browse the wider reference corpus. ```json {"action":"search_lean","query":"CircuitSpec controlled X gate","result_count":8,"authoring_only":true} ``` ##### `get_document` Use after knowledge search. Required: positive `document_id` returned by `search_knowledge`. Do not guess IDs. ```json {"action":"get_document","document_id":42} ``` ##### `search_corpus_examples` Use to find worked proof chains, template inputs, provider-intake samples, or designer samples. Optional: `query`; omit it for a bounded index. Optional: `result_count` 1-50, default 8. Returned summaries contain exact asset paths. ```json {"action":"search_corpus_examples","query":"bell claims","result_count":10} ``` ##### `get_corpus_example` Use after corpus search. Required: the exact relative `example_path`. Absolute paths and traversal reject. JSON, Lean, qpcert, and text assets retain their media type; large assets may return a File Manager result file. ```json {"action":"get_corpus_example","example_path":"authored_specs/bell_spec.lean"} ``` #### Circuit actions ##### `instantiate_template` Use to expand a supported template. Required: `descriptor.semantic_profile` and `descriptor.family`, plus family-specific fields: - `ghz`: `qubits` 2-4096. - `bernstein_vazirani`: nonempty binary `secret`. - `teleportation`: no additional field. - `grover`: `qubits` 2-4096 and `marked_item` satisfying `0 <= marked_item < 2^qubits`. - `qft`: `qubits` 2-6. The result is not certified. It normally includes the normalized circuit, validation/visualization material, and certification inputs where the template has contracted claims. ```json {"action":"instantiate_template","descriptor":{"semantic_profile":"exact_clifford_t_v2","family":"grover","qubits":3,"marked_item":5}} ``` ##### `import_provider_circuit` Use to parse hand-authored Qiskit, Cirq, or Braket Python without executing it. Required: `circuit_id`, explicit `semantic_profile`, `provider_target`, and `source`. The source must end in exactly one newline and is limited to 262144 characters. `qubit_count` is required for Braket because idle-wire width is not encoded by `Circuit()`; it is optional for Qiskit and Cirq. Supported source targets are `qiskit_python`, `cirq_python`, and `braket_python`. The parser accepts only its bounded grammar; dynamic Python and arbitrary execution reject. ```json {"action":"import_provider_circuit","circuit_id":"bell_import","semantic_profile":"unsigned_binary_symplectic_clifford_v1","provider_target":"qiskit_python","source":"from qiskit import QuantumCircuit\ncircuit = QuantumCircuit(2)\ncircuit.h(0)\ncircuit.cx(0, 1)\n"} ``` ##### `inspect_circuit` Use for validation, canonical subject-address computation, and optional visual explanation. Required: complete `circuit`. Optional: `claims` to enrich claim-aware visualizations; `include_visualizations`, default false, to return the complete structured visualization pack; `image_format` (`png` or `jpeg`) to render the digest-bound logical `wire_circuit` projection and store it in the current budget's File Manager. `image_format` triggers the needed visualization internally and does not require `include_visualizations: true`. The circuit must be a complete `heyting.quantum_circuit_ir.v1` object with `circuit_id`, a supported `semantic_profile`, nonempty `qubits`, `classical_bits`, `initial_state`, and ordered `operations`. Gate rows use `kind`, `op_id`, `gate`, `controls`, `targets`, and `parameters`; measurement rows use `basis`, `qubit`, and `classical_bit`; reset rows use `qubit`. When `image_format` is set, the response includes top-level `image_file` metadata. If a visual response is useful, immediately call AgentPMT's built-in `present_resource_card` with `variant: "image"` and `image_file.file_id`, `filename`, `content_type`, and `size_bytes`. Use `file_id` as the card's only locator: do not also pass `url`, and do not present or persist `signed_url`. The card resolves a fresh budget-scoped URL when it enters view or is replayed. The image is a logical explanation bound to the circuit and visualization digests; the qpcert, not the image, is the proof artifact. ```json {"action":"inspect_circuit","image_format":"png","circuit":{"schema":"heyting.quantum_circuit_ir.v1","circuit_id":"bell_pair","semantic_profile":"unsigned_binary_symplectic_clifford_v1","qubits":[{"id":"q0"},{"id":"q1"}],"classical_bits":[],"initial_state":"zero","operations":[{"kind":"gate","op_id":"g0","gate":"h","controls":[],"targets":["q0"],"parameters":[]},{"kind":"gate","op_id":"g1","gate":"cx","controls":["q0"],"targets":["q1"],"parameters":[]}],"metadata":{"name":"Bell pair","scope":"unsigned symplectic action"}}} ``` Then display the returned file with the chat card: ```json { "variant": "image", "title": "Bell pair logical circuit", "description": "Logical gate visualization; this image is not proof.", "file_id": "<image_file.file_id>", "filename": "<image_file.filename>", "content_type": "image/png", "size_bytes": 48321 } ``` #### Proof actions ##### `certify_circuit` Use when a normalized circuit and exact claim ledger are ready. This is the normal path for a circuit built on the canvas, imported from a provider, or returned by a template. Required: complete `circuit` and `claims`. The claim ledger must use `heyting.quantum_claim_evidence.v1`, match the circuit's semantic profile and canonical subject digest, and contain nonempty typed claim obligations. Unless the user explicitly requested a supported stronger property, use a `well_formed` obligation. Start from matching `certification_inputs` or a `.claims.json` corpus example rather than inventing a relation or evidence tier. When the Quantum Agent dashboard supplies `certification_claims`, pass that object unchanged. The only accepted evidence-tier names are `kernel_certified`, `checker_verified`, `simulator_crosscheck`, `provider_attested`, and `reported`. This action validates the circuit, runs kernel-backed bundle construction, verifies the generated qpcert, stores it in File Manager, and returns a compact certificate summary. Do not automatically call verification or extraction on this fresh result. ```json