Design rationale

The mechanisms indexed here have no paper source. They are the Problem, Method, Plan, Run and Result lifecycle, the checks of a Program and its binding to backend code, resource totals, saved Runs and archives, backend adapters and scoped error evidence. Each row names the failure the mechanism prevents, the invariant it keeps, the code responsible for it (paths relative to src/nwqlib/), the page that documents the rule, and a test in tests/ that fails when the central relation of the row breaks. Paper-derived steps are indexed separately in References.

Records, Plans and Methods

Mechanism	Failure it prevents	Invariant	Code	Documented in	Test that checks it
Content hash	Data attached to the wrong selection	The hash covers the concrete record type and every declared field, including revision ancestry	core/records.py Record	Record contracts	test_core_records.py::test_qualified_record_identity_and_unit_meaning_are_distinct, test_run_lifecycle.py::test_empty_run_rejects_a_method_loader_that_changes_the_selected_plan
Plan selected once	Observations interpreted under a construction they were not measured with	Execution, analysis and archives use the original Plan. A different choice needs a new Plan	core/planning.py Plan	Execute the selected row	test_search.py::test_selected_row_keeps_original_forecast_through_repeated_runs_and_archive
Separate random streams	Backend seed draws shifting the scientific selection	Method and backend streams are spawned independently	core/planning.py RandomStreams	Engineering constants (MAX_RUNTIME_SEED)	test_selected_runtime.py::test_selected_plan_executes_without_replanning_and_reanalysis_shares_data
Ranking from recorded evidence	A Pareto front inconsistent with its values, or rescoring that does new work	The Pareto front is recomputed on validation, and objectives read recorded evidence only	search.py SearchSelection	Rank candidate plans	test_search.py::test_frontier_domain_ties_and_partial_comparability, test_search.py::test_cached_folds_and_supplied_prior_occurrences_survive_rescoring
Trusted registry	An archive string importing arbitrary code	Only an exactly registered factory runs	algorithms/registry.py	Add a Method	test_algorithm_protocol.py::test_registry_loads_only_exact_selected_factory_and_never_source_paths
Author check with a wrong Result	A validator that accepts a scientifically wrong Result	A well-formed wrong Result fails validate_plan, and the valid Result survives a save-and-load round trip	algorithms/authoring.py check_method	Add a Method	test_public_cli.py::test_author_checker_rejects_false_oracle_ineffective_falsifier_and_disabled_pair_check

Programs, blocks and cost rules

Mechanism	Failure it prevents	Invariant	Code	Documented in	Test that checks it
Program check before work	An illegal qubit lifecycle reaching circuit building, resource totals or preparation	Linear lifetimes, coherence epochs, correlation and branch or loop stability are checked for each distinct context of the check	ir/validation.py _Admission	Program checks	test_ir.py::test_coherence_epoch_broken_and_stale_after_reset_or_reallocate
Count before copy	Unbounded work or memory from caller metadata	Each collection that the Program keeps is counted against the planning limits before it is copied	ir/expressions.py walk_kept, with the limits in AdmissionLimits	Engineering constants	test_ir.py::test_stored_collections_reserve_before_copying_their_frontier
Binding to backend code by exact content hash	An equal-looking input attaching a different circuit	Circuit building accepts only the block whose record content hash the Program names	blocks/selection.py SelectedBlock	Compose blocks	test_semantic_blocks.py::test_selected_binding_rejects_unbound_and_incompatible_live_access_before_sdk
One Program for resource totals and circuit building	A resource estimate and a circuit describing different constructions	The resource total and the circuit building read the same named calls and arguments	resources/fold.py, blocks/lowering.py	Execution and storage	test_resource_fold.py::test_same_choice_small_lowered_inventory_and_trillion_repeat
Unknown is not zero	An incomplete estimate looking cheap and complete	Unknown values propagate, and only an exact zero multiplicity removes work	resources/fold.py _Fold	Estimate resources	test_resource_fold.py::test_native_bounds_product_and_control_phase_are_not_zero_or_exact
Proportional limit on resource-total work	A resource total whose work grows faster than the Program it describes	The work of the resource total is at most the larger of max_steps and FOLD_WORK_PER_ADMISSION_STEP times the step count of the Program check	resources/fold.py _Fold	Engineering constants	test_resource_fold.py::test_fold_work_limit_is_proportional_to_program_admission_work
CX formulas matched by Source	A cost bound derived for one construction applied to another	A registered CX formula of a library block, an upper bound on its CX slots before cancellation and routing, applies only when both its cost-law Source and the block's implementation Source equal the corresponding registered Source records	resources/fold.py _Fold.native_cx	Execution and storage	test_resource_fold.py::test_signed_pauli_native_cx_law_is_consumed_at_actual_fold_binding
Block-encoding build follows its routing	A build choosing a different encoding from the one whose cost was estimated	The build uses the implementation that routing selected. The Pauli builder reads the dependency supports the plan selected	subroutines/block_encoding/core.py	Block encoding	test_block_encoding.py::test_f3_qsd_bound_selects_the_realized_lower_cx_route_near_tie
Automatic routing never approximates	A silent structural approximation	Banded routing needs zero detection error, and the Pauli transform removes exact zeros only	subroutines/block_encoding/core.py _plan_block_encoding	Block encoding	test_block_encoding.py::test_default_pauli_and_circulant_selection_keep_small_nonzero_terms
Content-independent CX counts	A CX count that depends on the table values	Exact dependency projection with mux_simp=False keeps the formula equal to the count of the built circuit	subroutines/_multiplexors.py	Block encoding	test_multiplexors.py::test_constant_unitary_tables_keep_the_declared_unsimplified_cx_law

Input checks

Mechanism	Failure it prevents	Invariant	Code	Documented in	Test that checks it
Immutable copy and hash	Accepted data or its content hash changing after acceptance, for example when a caller's later mutation changes the input of an existing Plan, or when an input stored in another layout shares another input's hash	The accepted array is kept as an immutable copy backed by a bytes object and hashed once with its dtype, shape, order and content	operators/inputs.py _freeze_array, _digest	Input cost controls	test_input_access.py::test_natural_operator_snapshot_and_original_action
Exact Hermitian structure	A tolerance or symmetrization silently replacing a nearly Hermitian matrix by a different operator	Hermiticity is exact equality of the stored values, with no tolerance, and the input is never symmetrized	operators/inputs.py ingest_dense, ingest_sparse, problems/records.py Eigenproblem	Input cost controls	test_input_access.py::test_numeric_conversion_domain_and_exact_structure
Term merging that removes only exact zeros	Small nonzero coefficients disappearing without a record of what was removed	Input checks and conversion remove only sums that are exactly zero. Thresholds on nonzero values are Method controls	operators/_pauli.py combine_terms, pauli_coefficients, operators/_factorized.py FactorizedOperatorProduct.expand	Input cost controls	test_input_access.py::test_pauli_residue_word_order_and_expansion_bound
No implicit densification	Hidden dense memory from a compact input	Input objects never densify sparse, Pauli, Fermion, product or periodic data implicitly. Compact inputs stay compact unless a dense path is selected explicitly	operators/inputs.py OperatorInput.dense_array, sparse_entries, matvec	Input cost controls	test_input_access.py::test_compact_hundred_qubit_inputs_never_allocate_system_data
Physical scale beside direction	A normalization applied twice or lost, so that the magnitude, sign or complex phase of the scientific input is lost	A state is normalized once by a positive norm, and that norm is stored as the physical scale beside the normalized direction	problems/inputs.py PhysicalScale, ingest_vector	Input cost controls	test_input_access.py::test_state_physical_phase_normalizes_once_and_metadata_cannot_rebind
Metadata-only records	A record reattached to data it does not describe, so that work runs on data that was never checked	from_record restores metadata, never access to the numerical data	operators/inputs.py OperatorInput.from_record, problems/inputs.py StateInput.from_record	Input cost controls	test_input_access.py::test_operator_metadata_never_restores_native_access

Runs, run logs and archives

Mechanism	Failure it prevents	Invariant	Code	Documented in	Test that checks it
One Run per execution	Two records disagreeing on spent work or provenance	One run_id holds the reserved work, outcomes and exposure	_prepared_execution.py Run	Execution and storage	test_run_lifecycle.py::test_repeated_submit_keeps_each_explicit_owner
Reserve before work	A reused random draw or a duplicate submission after a crash	The counted work, random state and intent are committed to the run log before the external call	_prepared_execution.py prepare_experiment, Run._begin_submission, _submit_host	Execution and storage	test_static_runtime.py::test_failed_static_preparation_keeps_original_seed_and_rejects_implicit_rebuild
An unrecoverable outcome stays uncertain	A hidden failure, a refund or a resubmission of work the provider may have run	Such an attempt stays uncertain and counted against the limits, and it is never resubmitted or refunded. Because its in-process output is unavailable, a reopened synchronous Aer submission with no locator is marked failed with results_consumed=True, which prevents another retrieval attempt, and continuation raises the recovery error with that attempt's identity	_prepared_execution.py Run._fail_attempt, Run._restore, Run._restore_submissions, Run._raise_unrecoverable_outcome	Run on a backend	test_controller_frontiers.py::test_lost_submission_ack_keeps_uncertainty_without_replay
Original identifiers on pending work	A replacement job, or data associated with the wrong attempt	A reopened Run keeps the locator, attempts, item ordinals, random state and collection order	_prepared_execution.py refresh_submissions, submit_detached, Run._restore, _remote_preparation.py _advance	Continue an interrupted run	test_run_archive.py::test_pending_copy_preserves_original_locator_rng_exposure_and_once_only_collection
Atomic outcome	An observation without its exposure, or an array without the record of its measurement	Outcome rows and arrays commit in one transaction	_prepared_execution.py Run._finish_attempt, Run._flush_publications, _run_journal.py LocalJournal.commit	Execution and storage	test_run_journal.py::test_array_and_completed_observation_publish_in_one_atomic_transition
Delta checkpoints	Checkpoint cost growing with history, or a half-written checkpoint	Only changed fields and cache rows are written, in one transaction	_prepared_execution.py Run.checkpoint, _run_archive.py write_caches, finish_caches	Execution and storage	test_run_lifecycle.py::test_checkpoint_writes_only_changed_fields_and_restores_the_whole_state
Reopen without replay	New work or changed results when an archive, a Run or a Result is opened	Loading never plans, builds circuits, measures or analyzes	_run_archive.py load, _prepared_execution.py Run._restore, saved_evidence.py load_result	Continue an interrupted run	test_run_archive.py::test_completed_archive_keeps_numerical_caches_arrays_and_result_without_reexecution
Header checks with lazy arrays	Wrong reads from a corrupt header, or a full read on every load	The headers of saved input arrays and of a standalone Result's saved arrays are always checked. A header or layout mismatch is rejected, and array values are not read	saved_evidence.py load_data, _choice_archive.py ArchiveFiles.read_state, read_operator	Save, load and reanalyze results	test_saved_evidence.py::test_saved_array_layout_corruption_rejects_without_scientific_reanalysis
Metadata-only report	A report that imports Method code or computes	read_report reads JSON only	saved_evidence.py read_report	Save, load and reanalyze results	test_saved_cli.py::test_read_report_preserves_current_identity_and_never_loads_method_or_arrays
Unit bound where observation chunks meet preparation records	An exact Pauli expectation outside [-1, 1] beyond the roundoff of the executed circuit	The unit bound of exact readout, in which the simulator computes the expectation without shot sampling (shots=None), subject to numerical rounding, is checked where an observation chunk meets its preparation record, that is, where it is decoded from backend output, and before a Result is saved	execution.py ObservationChunk.validate_unit_bound, called by _prepared_execution.py _quantum_chunk and saved_evidence.py _validate_recorded_data	Engineering constants (exact_probability_window)	test_qpe_correction.py::test_excess_expectation_is_checked_against_its_circuit_window_when_created_and_saved
Remote preparation intents	A duplicate upload or compilation	The intent is saved before the SDK call, and the acknowledged identity is kept	_remote_preparation.py _advance	Execution and storage	test_remote_preparation.py::test_remote_intents_and_acknowledgements_resume_original_preparation
One process per run log	Two processes interleaving transitions of one Run	An exclusive advisory lock is taken before the database opens and held until close	_run_journal.py LocalJournal	Execution and storage	test_archive_boundaries.py::test_journal_lock_and_lost_folder_have_owned_context
Orphan cache reclamation	Uncommitted cache files from an interrupted checkpoint filling the data allowance, or deletion of a Plan input	Only unreferenced files in the reserved cache namespace are removed, under the lock and before the bytes of the saved files are counted	_run_archive.py restore_caches, finish_caches	Execution and storage	test_run_archive.py::test_reopen_cleans_uncommitted_cache_before_capacity_and_preserves_owned_inputs
UCGate storage container	A saved circuit that Qiskit's QPY loader cannot rebuild	A circuit with a UCGate is stored in a prefixed container that keeps the table, controls and flags. Other circuits stay raw QPY	_qpy_archive.py encode_circuit, decode_circuit	Qiskit UCGate compatibility	test_qpy_archive.py::test_native_ucgate_qpy_limitation_canary, test_compact_ucgate_roundtrip_preserves_nominal_action

Backend adapters and device profiles

Adapter methods named below live in each adapter module under backends/: ibm_runtime.py, ionq.py, nexus.py, nwqsim.py and slurm.py.

Mechanism	Failure it prevents	Invariant	Code	Documented in	Test that checks it
One create request per saved intent	A duplicate job after a lost acknowledgement	NWQLib never retries a create request	_prepared_execution.py submit_detached, each adapter's launch	Execution and storage	test_ionq_backend.py::test_one_post_lost_ack_stays_uncertain_and_never_resubmits
Label reconciliation	Binding another job, or resubmitting	At most one job is bound, and no match leaves the submission uncertain	each adapter's reconcile	Execution and storage	test_slurm.py::test_ambiguous_accounting_never_selects_first_job
Partial refresh	A later item's failure losing earlier results	The results of earlier items are saved once before the original exception is raised	each adapter's refresh	Execution and storage	test_ibm_backend.py::test_later_pub_failure_preserves_prior_result_and_skips_its_decode_on_resume
Cancellation is a request	Assuming a cancellation or a refund	Exposure stays counted until the provider status confirms the cancellation	each adapter's cancel	Run on a backend	test_slurm_integration.py::test_cancel_original_job_is_sent_once_across_interrupted_request
One decoder per adapter	Silent bit reordering	Count keys cover global bits with bit 0 rightmost	_decode in ibm_runtime.py, ionq.py and nexus.py, backends/qiskit_aer.py _submit_aer_execution, backends/nwqsim.py NWQSimBackend._result	Execution and storage	test_ibm_backend.py::test_sampler_joint_registers_preserve_shot_alignment_and_logical_bit_order
Readout and capability checked before work	Paying for a request that cannot run	A mismatch rejects before preparation or submission	each adapter's target_for and admit_batch	Execution and storage	test_run_lifecycle.py::test_readout_refusal_names_selected_target_before_native_preparation
Per-axis assessment	One failing axis hiding a bound, or a prediction read as a guarantee	Each axis has its own outcome, and predictions stay conditional	backends/assessment.py	Check device fit and run time	test_profile_assessment.py::test_upper_memory_envelope_is_not_a_proved_failure
Telemetry residual	A residual attributed to the wrong forecast	Only a pre-bound, completed, same-scope pairing yields a residual	backends/telemetry.py align_telemetry	Check device fit and run time	test_profile_telemetry.py::test_scope_configuration_and_original_intent_association
Auxiliary child process	A hung or noisy compiled library blocking the caller	A deadline and a cap on captured output apply, and results are returned only on a clean exit	backends/_auxiliary_process.py run_auxiliary	Estimate fault-tolerant resources	test_nwqec_compilation.py::test_auxiliary_timeout_or_capture_limit_reaps_child

Error evidence

Mechanism	Failure it prevents	Invariant	Code	Documented in	Test that checks it
Component-scoped assessment	A sampling bound read as total accuracy	assess combines only the listed error sources and keeps each scope	evidence/error_model.py ErrorModel.assess	Check against a tolerance	test_error_model.py::test_new_criterion_keeps_original_context_and_component_scope
Witnessed support	A numerical estimate passing as a proof	Only witnessed evidence of kind proved_relation or certified_bound satisfies a criterion, and an observed value stays inconclusive	evidence/error_model.py supported	Error evidence internals	test_error_model.py::test_invalid_bounds_frames_and_associations_reject_before_missing_evidence
A replacing bound carries its own confidence	Old evidence relabeled with a new confidence	A replacing bound never inherits the confidence it displaces	evidence/error_model.py ErrorModel.assess	Check against a tolerance	test_error_model.py::test_replacing_bound_never_inherits_displaced_confidence
Facts bound to their options	A revised threshold answered by facts computed for another	Each check fact carries the content hashes of its options and its CheckSpec	evidence/error_model.py Certificate.with_verification	Check accuracy and verify a result	test_verification_catalogue.py::test_actual_scalar_energy_shift_and_saved_results
Domain check before status	An impossible value reported as FAIL or INCONCLUSIVE	A value outside the quantity's domain is rejected	evidence/error_model.py _admit_check_value	Error evidence internals	test_error_model.py::test_check_domain_and_signed_metric_are_distinct_from_evidence_status
Covariance from data IDs	Double counting, or independence that was never established	Covariance follows the shared data IDs	evidence/statistics.py linear_variance	Error evidence internals	test_error_model.py::test_covariance_counts_actual_variables_and_keeps_conditioning
Independent count sources	Likelihood evidence counted twice	One fixed sampling stream supplies one set of counts	_counts.py CountsSources	Finite Pauli expectation	test_expectation_inference.py::test_shared_stream_preserves_marginal_union_bound_but_not_product_independence
Exact arithmetic limit	Unbounded rational growth	Integer sizes are bounded before exact arithmetic runs	evidence/_work.py ExactArithmetic	Error evidence internals	test_error_model.py::test_exact_integer_guard_precedes_arithmetic_and_preserves_small_cases

Iterative Methods and saved choices

Mechanism	Failure it prevents	Invariant	Code	Documented in	Test that checks it
Checkpointed adaptive iterations	Interruption duplicating paid work, or a restart drawing a new point	The seed, point and sequence are saved before external work, and each completed attempt updates the iteration state once	algorithms/gcim/adapt_acquisition.py drive_adapt, algorithms/qpe/controller.py, algorithms/lanczos/workflow.py	Continue an interrupted run	test_run_archive.py::test_exact_adapt_resumes_reused_native_readout_without_replaying_acquisitions, test_qpe_selected.py::test_rwpe_completed_pending_resume_has_same_trajectory
Saved outer record of the QHD layers	A resumed augmented-Lagrangian run or box refinement that repeats completed rounds or levels, continues on another backend, or is continued by two processes at once	Completed rounds and levels are written to controller.json through a temporary file that is then renamed, and their work is counted once. Resume holds the directory's exclusive lock and uses the recorded backend. It reads the Results of completed rounds and levels from their Runs without running them again, and an unfinished round or level continues its recorded Run, if it has one, instead of getting a new one	algorithms/qhd/_durable.py Directory, _controller, saved_result, reopen	QHD guide	test_qhd_resume.py::test_a_run_interrupted_between_rounds_resumes_without_repeating_them, test_qhd_resume.py::test_resume_refuses_another_backend_another_layer_and_a_second_controller
Refusal before a Run	Preparing in advance settings that depend on outcomes not yet observed, or leaving a Run folder behind for a refused request	prepare(plan, settings="all") asks the Method's prepare_all_refusal before a Run exists. RWPE, Lanczos with SensitivitySampling and ADAPT refuse	scientist.py _prepare_plan, algorithms/protocol.py Method.prepare_all_refusal	Run on a backend	test_prepared_execution.py::test_prepare_all_settings_refuses_outcome_dependent_controllers
One parameterized query space	An adaptive trajectory that is unknown when the Plan is made	Every adaptive query is a canonical point of one selected Program	algorithms/gcim/adapt.py _construction	the _construction docstring	test_adapt_gcim.py::test_query_completeness_and_exact_point_identity
QPE signal generation	Wrong powers, quadrature signs or query sampling multiplicities	The generated Hadamard tests implement the selected powers and their sampling multiplicities	algorithms/qpe/method.py _quantum_program	QPE guide	test_qpe_selected.py::test_exact_trajectory_signals_equal_independent_powers, test_qpe_campaigns.py::test_qpe_counts_resolve_an_independent_eigenvalue
Selected-data serialization	A changed numerical approximation after saving and loading	Loading restores the selected coefficient, quadrature and PREP arrays without selecting them again. The periodic Strang payload is used as saved	algorithms/lchs/archive.py, algorithms/lchs/parameters.py selected_identity	LCHS guide	test_lchs_primary.py::test_lchs_archive_preserves_selected_numerical_data, test_lchs_primary.py::test_selected_identity_encoding_distinguishes_mapping_nesting, test_lchs_periodic.py::test_periodic_archive_preserves_plan_and_solution
Refusal instead of a changed approximation	Unbounded construction of dense arrays, or a silently coarser model	Planning refuses and never alters the grid, Duhamel nodes or tolerance	algorithms/lchs/parameters.py select_parameters	LCHS guide	test_lchs_select_synthesis.py::test_dense_select_slot_cap_refuses_at_planning_before_native_construction
Planned versus executed search work	Planned trials read as executed quantum work	Executed counts stay within the planned upper bound	algorithms/qls/norm_search.py, algorithms/qls/host_planning.py search_envelope, algorithms/qls/method.py	QLS guide	test_qls_primary.py::test_named_classical_norm_model_records_actual_work_and_user_replay