1 reporting.discovery

reporting.discovery

Bounded discovery and selection of immutable scientific-report evidence.

Discovery is deliberately explicit and read-only. Callers provide one root and finite traversal ceilings; this module never searches the wider filesystem or writes beside evidence. Candidate markers are admitted only by their domain reader, so a familiar filename alone never makes an artifact usable.

1.1 Classes

Name	Description
BoundCatalogReport	Existing report recipe with one catalog source and section selected.
PreparedCatalogReport	Identity-checked owner evidence ready for one ordinary builder dispatch.
ReportCatalog	Deterministic result of one bounded, explicit-root discovery request.
ReportCatalogEntry	One candidate marker after validation by its authoritative reader.
ReportCatalogLimits	Finite work limits for one explicit discovery request.
ReportCatalogTruncation	Ceiling that prevented a complete scan of the explicit root.

1.1.1 BoundCatalogReport

reporting.discovery.BoundCatalogReport(config, request)

Existing report recipe with one catalog source and section selected.

1.1.1.1 Attributes

Name	Description
config	Validated report config retaining the template’s theme, export policy, and other sections.
request	Section request that builds only the catalog-selected evidence.

1.1.2 PreparedCatalogReport

reporting.discovery.PreparedCatalogReport(
    config,
    request,
    recipe_evidence=None,
    measurement_evidence=None,
    qh_evidence=None,
)

Identity-checked owner evidence ready for one ordinary builder dispatch.

1.1.2.1 Attributes

Name	Description
config	Catalog-bound report configuration frozen for this acquisition.
request	Section request selecting only the acquired catalog evidence.
recipe_evidence	Validated recipe product acquired once, when selected.
measurement_evidence	Validated measurement product acquired once, when selected.
qh_evidence	Validated QH product acquired once, when selected.

1.1.2.2 Methods

Name	Description
build	Build through the canonical builder without reacquiring raw evidence.

1.1.2.2.1 build

reporting.discovery.PreparedCatalogReport.build(root=None)

Build through the canonical builder without reacquiring raw evidence.

1.1.3 ReportCatalog

reporting.discovery.ReportCatalog(
    root,
    entries,
    scanned_file_count,
    skipped_symlink_count,
    truncation,
    scanned_path_count=0,
    registrations=(),
)

Deterministic result of one bounded, explicit-root discovery request.

1.1.3.1 Attributes

Name	Description
root	Absolute non-symlink directory selected by the caller.
entries	Validated and invalid candidates in deterministic marker-path order.
scanned_file_count	Regular files inspected before the scan completed or reached a ceiling.
skipped_symlink_count	Symlink entries ignored without following their targets.
truncation	Sorted ceilings that prevented a complete traversal; empty means complete.
scanned_path_count	Filesystem entries enumerated before completion or path truncation.
registrations	Experiment references, separate from the four buildable/preview report kinds.
truncated	Whether any configured ceiling prevented a complete scan.

1.1.3.2 Methods

Name	Description
to_jsonable	Return the stable machine-readable CLI representation.

1.1.3.2.1 to_jsonable

reporting.discovery.ReportCatalog.to_jsonable()

Return the stable machine-readable CLI representation.

1.1.4 ReportCatalogEntry

reporting.discovery.ReportCatalogEntry(
    path,
    marker_path,
    kind,
    status,
    compatibility,
    content_sha256,
    detail=None,
    recipe_contrasts=(),
)

One candidate marker after validation by its authoritative reader.

1.1.4.1 Attributes

Name	Description
path	Selected evidence path: bundle/QH directory, recipe plan, or measurement summary.
marker_path	Exact marker encountered during the bounded traversal.
kind	Closed evidence family determined by marker name and authoritative validation.
status	Whether the authoritative domain reader admitted the candidate.
compatibility	How the current reporting stack can consume the admitted evidence.
content_sha256	Domain-owned content or snapshot identity, unavailable for invalid candidates.
detail	Validation or compatibility explanation, when one is needed.
recipe_contrasts	Sorted baseline/challenger pairs exposed by a validated recipe product.

1.1.4.2 Methods

Name	Description
to_jsonable	Return a deterministic CLI projection without exposing implementation state.

1.1.4.2.1 to_jsonable

reporting.discovery.ReportCatalogEntry.to_jsonable()

Return a deterministic CLI projection without exposing implementation state.

1.1.5 ReportCatalogLimits

reporting.discovery.ReportCatalogLimits(
    max_depth=6,
    max_files=5000,
    max_entries=100,
    max_paths=10000,
)

Finite work limits for one explicit discovery request.

1.1.5.1 Attributes

Name	Description
max_depth	Maximum directory depth relative to the selected root, including markers at that depth.
max_files	Maximum number of regular files inspected during traversal.
max_entries	Maximum report entries plus registered experiments and their attempts.
max_paths	Maximum number of filesystem entries enumerated across the selected root.

1.1.6 ReportCatalogTruncation

reporting.discovery.ReportCatalogTruncation()

Ceiling that prevented a complete scan of the explicit root.

1.1.6.1 Attributes

Name	Description
DEPTH	At least one directory lay below the configured maximum depth.
FILES	At least one regular file remained after the file ceiling was reached.
ENTRIES	A marker or nested experiment attempt exceeded the global entry ceiling.
PATHS	A directory could not be enumerated within the global traversal-entry ceiling.

1.2 Functions

Name	Description
bind_catalog_entry	Bind one buildable entry to the existing report recipe interface.
discover_report_catalog	Discover supported evidence below one explicit root with finite work.
prepare_catalog_build	Acquire one raw catalog source and prove it still matches the index entry.
read_catalog_bundle	Cold-read one preview-only bundle and reject identity drift since indexing.

1.2.1 bind_catalog_entry

reporting.discovery.bind_catalog_entry(config, entry)

Bind one buildable entry to the existing report recipe interface.

Existing sections of the selected evidence kind are replaced because they referred to a different source. Other source families, sections, theme, evidence status, and export settings remain unchanged. The returned request ensures the ordinary builder acquires only the newly selected section(s).

1.2.2 discover_report_catalog

reporting.discovery.discover_report_catalog(root, *, limits=None)

Discover supported evidence below one explicit root with finite work.

Supported markers are manifest.json for cold report bundles, plan.json for recipe experiments, summary.json for endpoint measurement audits, and assignment.json for finite-horizon QH diagnostics. registration.json adds portable experiment references without opening their optional local rollout stores.

Symlinks are counted and skipped. Validation can read the additional files named by a candidate’s domain contract, but traversal never follows a symlink or escapes the selected root on its own.

1.2.3 prepare_catalog_build

reporting.discovery.prepare_catalog_build(config, entry)

Acquire one raw catalog source and prove it still matches the index entry.

1.2.4 read_catalog_bundle

reporting.discovery.read_catalog_bundle(entry)

Cold-read one preview-only bundle and reject identity drift since indexing.