Research-lane registry API

Module: scpn_quantum_control.analysis.research_lane_registry

This API provides the typed BL-84 catalogue and its exact source-inventory gate. It is deterministic, credential-free, and read-only except for the separate evidence runner writing its requested output files.

Constants

Name	Contract
RESEARCH_LANE_REGISTRY_SCHEMA	Versioned serialization identifier, currently scpn.research-lane-registry.v1
RESEARCH_LANE_REGISTRY_BOUNDARY	Global non-promotion statement applied to every row and report

Enums

ResearchLaneMaturity

Human-reviewed software maturity: RESEARCH, PROTOTYPE, or PRODUCT_CANDIDATE. The last value does not itself productise a module.

ResearchLaneDiffHook

Relationship to differentiable work:

• NONE: no registered differentiable relationship;
• DIAGNOSTIC: usable only as a diagnostic input;
• CANDIDATE: a possible hook requiring separate evidence;
• BOUNDED_COMPOSITION: consumed by an already bounded, separately governed route;
• DEFERRED: blocked behind an owner gate.

ResearchLaneClaimStatus

Strongest claim class carried by the lane itself: RESEARCH_ONLY, DIAGNOSTIC_ONLY, EVIDENCE_BOUNDED, or REFUSE_ONLY. Bounded evidence is still limited to the cited artefact and global boundary.

Records

ResearchLaneRecord

ResearchLaneRecord(
    module: str,
    summary: str,
    maturity: ResearchLaneMaturity,
    diff_hook: ResearchLaneDiffHook,
    claim_status: ResearchLaneClaimStatus,
    promotion_targets: tuple[str, ...] = (),
    evidence_refs: tuple[str, ...] = (),
)

The frozen, slotted record validates its namespace, non-empty summary, duplicate-free target/evidence tuples, evidence requirements, and promotion route requirements. family returns analysis or gauge. registry_grants_productisation, registry_grants_control, and registry_grants_publication_claim always return False. as_dict() emits enum values, lists, and all three explicit denials as JSON-ready primitives.

Construction raises ValueError for malformed or internally inconsistent rows. The governance module cannot register itself.

ResearchLaneInventoryReport

ResearchLaneInventoryReport(
    registered_modules: tuple[str, ...],
    discovered_modules: tuple[str, ...],
    missing_modules: tuple[str, ...],
    orphaned_records: tuple[str, ...],
)

passed is true only when both drift tuples are empty. as_dict() includes sets as sorted lists plus registered/discovered counts.

ResearchLaneRegistryReport

Carries the schema, global boundary, immutable rows, inventory report, and a SHA-256 content digest. as_dict() additionally renders maturity, diff-hook, and claim-status counts. The digest covers the payload before the digest field is added, avoiding self-reference.

Lookup and listing

list_research_lanes()

Returns the immutable tuple in canonical module order. It takes no arguments and performs no discovery.

get_research_lane(module)

Returns the exact reviewed row for a fully qualified module path. Relative names are deliberately not expanded. Raises KeyError when the module is not registered.

Discovery and validation

discover_research_lane_modules(package_root=None)

Scans top-level *.py files in analysis/ and gauge/. package_root must be the directory containing those two packages; when omitted, the installed package root is used. Returns sorted fully qualified names. Raises FileNotFoundError if either package directory is missing.

validate_research_lane_inventory(discovered_modules=None)

Returns an inventory report. Supplying an iterable bypasses filesystem discovery and is useful for CI fixtures or packaged consumers. Duplicate input names are normalized. This function reports drift without raising.

assert_research_lane_inventory(discovered_modules=None)

Returns the passing report or raises RuntimeError containing both the unregistered discovered modules and orphaned rows. Use this form for CI.

Evidence output

build_research_lane_registry_report()

Runs the strict inventory assertion, builds count summaries, canonicalizes the payload as sorted compact JSON, and computes its SHA-256 digest. Raises RuntimeError on inventory drift.

render_research_lane_registry_markdown(report=None)

Renders the full matrix as deterministic Markdown ending in one newline. With no argument it first builds and validates the report. Passing a prebuilt report avoids repeated discovery.

Full autodoc

Governed catalogue of the package's analysis and gauge research lanes.

BL-84 makes the existing deep-analysis stack visible without promoting every importable module into a product or scientific claim. Each immutable row records the module's human-reviewed maturity, relevance to differentiable work, current claim status, optional promotion route, and evidence pointers.

The inventory gate is intentionally strict: every ordinary analysis or gauge module must have exactly one row. Package __init__ modules and this registry's own governance implementation are the only exclusions. A new module therefore fails :func:assert_research_lane_inventory until a reviewer classifies it explicitly.

Registry membership is catalogue evidence only. It grants no productisation, control, hardware, differentiability, advantage, criticality, topology, consciousness, clinical, or publication claim. Promotions remain governed by their own backlog and evidence packages.

ResearchLaneMaturity

Bases: str, Enum

Human-reviewed implementation maturity.

RESEARCH marks exploratory scientific code. PROTOTYPE marks a bounded reusable diagnostic whose public contract or evidence is not yet a product gate. PRODUCT_CANDIDATE marks a stable candidate or a module already composed by a separately governed product; it is not a promotion by this registry.

ResearchLaneDiffHook

Bases: str, Enum

Relationship between a lane and differentiable-control work.

ResearchLaneClaimStatus

Bases: str, Enum

Strongest claim class currently carried by a lane's own evidence.

ResearchLaneRecord dataclass

Immutable human classification for one importable research module.

Parameters

module Fully qualified module path under scpn_quantum_control.analysis or scpn_quantum_control.gauge. summary Narrow description of what the current implementation can provide. The summary is not a scientific validation claim. maturity Human-reviewed implementation maturity. diff_hook Relationship to separately governed differentiable-control work. claim_status Strongest claim class admitted by the module's current evidence. promotion_targets Backlog routes that may consume the lane. A route suffixed planned or deferred-owner-gate is explicitly not a completed promotion. evidence_refs Repository-relative evidence or governance pointers. Empty tuples are expected for research-only and diagnostic-only lanes.

Notes

PRODUCT_CANDIDATE and EVIDENCE_BOUNDED remain non-promotional here. Callers must consult the referenced product/evidence package before making any stronger claim.

family property

Return analysis or gauge from the fully qualified module.

registry_grants_productisation property

Return False because catalogue membership is non-promotional.

registry_grants_control property

Return False because BL-84 grants no actuation authority.

registry_grants_publication_claim property

Return False because BL-84 is not publication evidence.

__post_init__()

Reject blank, out-of-scope, duplicate, or permissive records.

as_dict()

Return a deterministic JSON-ready row with explicit denials.

ResearchLaneInventoryReport dataclass

Comparison between registered rows and modules found on disk.

missing_modules are importable modules without a human classification. orphaned_records are registry rows whose implementation no longer exists. Both conditions fail the gate.

passed property

Return whether discovery and the immutable registry match exactly.

as_dict()

Return deterministic JSON-ready inventory evidence.

ResearchLaneRegistryReport dataclass

Complete BL-84 catalogue, inventory gate, counts, and digest.

as_dict()

Return the complete deterministic report as JSON-ready data.

list_research_lanes()

Return all human-reviewed lanes in canonical module order.

Returns

tuple[ResearchLaneRecord, ...] The immutable registry. The tuple and its records may be safely shared between callers.

get_research_lane(module)

Return the exact row for module or fail closed.

Parameters

module Fully qualified module path. Package-relative values are not expanded implicitly because that could hide namespace mistakes.

Raises

KeyError If no human-reviewed registry row matches module.

discover_research_lane_modules(package_root=None)

Discover ordinary analysis and gauge modules from source files.

Parameters

package_root Directory containing the analysis and gauge packages. When omitted, discovery uses the installed scpn_quantum_control package containing this module.

Returns

tuple[str, ...] Sorted fully qualified module paths. __init__.py and this registry implementation are excluded by policy.

Raises

FileNotFoundError If either required package directory is absent.

validate_research_lane_inventory(discovered_modules=None)

Compare discovered modules with the human-reviewed registry.

Parameters

discovered_modules Optional explicit discovery result for testing or packaged consumers. When omitted, :func:discover_research_lane_modules scans the current package. Duplicate values are normalized before comparison.

Returns

ResearchLaneInventoryReport Exact registered/discovered sets plus missing and orphaned entries. Inspect :attr:ResearchLaneInventoryReport.passed or call :func:assert_research_lane_inventory for exception semantics.

assert_research_lane_inventory(discovered_modules=None)

Return a passing inventory report or raise a drift error.

Raises

RuntimeError If a discovered module lacks a row or a row has no implementation.

build_research_lane_registry_report()

Build the deterministic BL-84 report after enforcing inventory parity.

Returns

ResearchLaneRegistryReport Complete catalogue and SHA-256 content digest.

Raises

RuntimeError If the source inventory and reviewed rows differ.

render_research_lane_registry_markdown(report=None)

Render a reviewable Markdown catalogue from registry state.

Parameters

report Optional prebuilt report. When omitted, the inventory gate runs before rendering.

Returns

str Deterministic Markdown ending with a newline.