Application Honesty API

scpn_quantum_control.applications.honesty_kits is the public BL-63 policy surface for immutable domain claim boundaries and deterministic evidence. scpn_quantum_control.applications.dataset_catalog owns the complementary packaged-artifact privacy audit.

These APIs validate software metadata and versioned local artifacts only. They do not certify domain fidelity, clinical use, facility prediction, operational control, hardware performance, or quantum advantage. For the guided workflow and extension rules, read Domain Application Honesty Kits.

Honesty-kit policy records

scpn_quantum_control.applications.honesty_kits

Fail-closed claim and data boundaries for domain-facing applications.

The objects in this module do not certify domain validity. They make the opposite boundary explicit: each kit identifies the small software route that is supported, the data origin admitted by that route, and the claims that remain forbidden. The built-in registry covers the BL-63 power-grid, Josephson, EEG-like, and ITER-inspired application families.

All returned records are immutable and JSON-ready. The audit functions are local and deterministic; they do not read credentials, contact providers, submit hardware work, or inspect private datasets.

ApplicationSupportStatus

Bases: str, Enum

Public support grade for a domain-facing application route.

BOUNDED_RESEARCH means that the named software path is tested for its documented small benchmark, while SIMULATION_ONLY requires generated inputs and forbids measured-domain interpretation.

ApplicationDataOrigin

Bases: str, Enum

Admitted input provenance for an honesty kit.

DomainApplicationHonestyKit dataclass

Immutable claim boundary for one domain-facing application family.

Parameters

kit_id Stable machine identifier for the kit. domain_tag Non-promotional domain label used in reports and user interfaces. title Human-readable kit name. support_status Whether the route is a bounded research benchmark or simulation-only. data_origin Provenance class admitted by this kit. synthetic_only True when measured or curated domain data must not enter the route. dataset_ids Packaged public catalogue identifiers governed by the kit. An empty tuple means that the route generates its inputs in code. source_modules Import paths implementing the bounded route. allowed_uses Positive, narrowly worded descriptions of supported software use. caveats Scientific and operational limitations that callers must preserve. claims_forbidden Explicit claims that this kit never authorises. forecasting_tags BL-37 simulation-only tags that may be cross-referenced. These tags do not convert a synthetic forecast into domain evidence.

Notes

Construction validates the internal policy relationships. In particular, a synthetic-only kit cannot declare curated input data or packaged dataset identifiers, and every kit must retain at least one forbidden claim.

publication_safe property

publication_safe: bool

Return False because a kit is not domain-publication evidence.

__post_init__

__post_init__() -> None

Validate the fail-closed relationships between policy fields.

as_dict

as_dict() -> dict[str, Any]

Return a JSON-ready representation with explicit non-claim fields.

ApplicationHonestyAuditReport dataclass

Deterministic aggregate of honesty kits and dataset privacy checks.

Parameters

kits Validated built-in honesty-kit records. dataset_privacy Catalogue privacy audit rows. Each row has already loaded and validated the corresponding packaged QPUDataArtifact.

passed property

passed: bool

Return whether every built-in kit and dataset privacy row is valid.

__post_init__

__post_init__() -> None

Reject empty, duplicate, or incomplete aggregate reports.

content_digest

content_digest() -> str

Return a SHA-256 digest of the canonical report payload.

as_dict

as_dict() -> dict[str, Any]

Return the canonical JSON evidence payload including its digest.

list_domain_application_honesty_kits

list_domain_application_honesty_kits() -> tuple[
    DomainApplicationHonestyKit, ...
]

Return all built-in BL-63 honesty kits in stable registry order.

get_domain_application_honesty_kit

get_domain_application_honesty_kit(
    kit_id: str,
) -> DomainApplicationHonestyKit

Return one built-in honesty kit by stable identifier.

Parameters

kit_id Exact identifier returned by :func:list_domain_application_honesty_kits.

Raises

KeyError If kit_id is unknown. The error includes the known identifiers.

get_domain_application_honesty_kit_for_dataset

get_domain_application_honesty_kit_for_dataset(
    dataset_id: str,
) -> DomainApplicationHonestyKit

Return the unique kit governing a packaged dataset identifier.

Synthetic-only kits intentionally have no packaged dataset identifiers and therefore cannot be resolved through this function.

Raises

KeyError If no built-in kit governs dataset_id. RuntimeError If registry corruption assigns the same dataset to multiple kits.

build_application_honesty_audit_report

build_application_honesty_audit_report() -> (
    ApplicationHonestyAuditReport
)

Build deterministic local evidence for every kit and catalogue row.

Returns

ApplicationHonestyAuditReport Immutable report with a canonical content digest.

Notes

The audit loads only versioned packaged application artifacts. It performs no network access and never opens a user-supplied or private dataset.

render_application_honesty_audit_markdown

render_application_honesty_audit_markdown(
    report: ApplicationHonestyAuditReport,
) -> str

Render a human-readable Markdown evidence report.

Parameters

report Validated report returned by :func:build_application_honesty_audit_report.

Packaged-dataset privacy records

scpn_quantum_control.applications.dataset_catalog.ApplicationBenchmarkDescriptor dataclass

Metadata and privacy boundary for a packaged benchmark artifact.

contains_personal_data describes the packaged file, not every possible external input accepted by a third-party plugin. The built-in catalogue is intentionally restricted to curated public constants and small matrices with no raw participant, clinical, SCADA, or proprietary facility records.

path property

Absolute path to the packaged artifact.

scpn_quantum_control.applications.dataset_catalog.ApplicationBenchmarkPrivacyAudit dataclass

One successful packaged-dataset privacy audit row.

Parameters

dataset_id Stable packaged dataset identifier. source_mode Validated artifact provenance mode. privacy_classification Descriptor classification for the packaged bytes. contains_personal_data Whether the packaged artifact contains personal data. Built-in rows must remain False. privacy_boundary Exact licence/provenance note bound to the artifact metadata. artifact_hashes Validated SHA-256 custody hashes embedded in the artifact. passed Always True for returned rows; mismatches raise instead of returning an ambiguous partial result.

as_dict()

Return a JSON-ready audit row with defensive hash copying.

scpn_quantum_control.applications.dataset_catalog.audit_application_benchmark_privacy()

Audit every packaged application artifact against its privacy descriptor.

Returns

tuple[ApplicationBenchmarkPrivacyAudit, ...] One immutable, JSON-ready success row per catalogue descriptor.

Notes

This audit reads only files beneath data/public_application_benchmarks. It never traverses external paths, downloads data, or treats a curated matrix as raw domain evidence. Any mismatch raises immediately.