BLOGE Verify API Reference

This page maps a verification question to the narrowest public entry point. All APIs described here are Preview in BLOGE 0.9.8-RC1.

Entry points

Entry point	Use it for	Required boundary	Result	Important limit
ScenarioVerifier	One Suite, governance, Property, sensitivity, or DSL comparison	Project root, Policy, fresh per-Case bootstrap	VerificationReport or specialized report	Customer bootstrap and operators execute
BlogeScenarioTests	Map a Scenario directory to JUnit 5 dynamic tests	A configured ScenarioVerifier	Stream<DynamicTest>	Global preflight happens before tests are created
DurableVerificationRunner	A retained-session action plan	Compiled Graph, operators, context, durable plan	DurableVerificationReport	One plan at a time; uncooperative timeout poisons the runner
DurableSourceBoundVerifier	Durable source-bound evidence	Durable runner inputs plus source/output binding	Durable result and receipt	Evidence version determines available trust facts
VerificationProjectRunner	Requirement aggregation across Suites in one project	Common selection, governance catalog, complete child cohort	Project report/evidence	Cannot assemble unrelated prior children after the fact
VerificationReactorRunner	Aggregate direct Maven modules	Supported root coordinates and exact module inventory	Reactor report/evidence	Nested/profile-derived reactors are outside this Preview boundary
PairedExecutionCoordinator	Compare two BLOGE toolchains	Frozen Java launcher, business classpath, inputs, and both toolchains	Toolchain comparison evidence	Provider-attested adapters are not BLOGE attribution
VerificationClaims	Derive decision capability from verified evidence	Original artifact, external receipt, correct project root	VerificationClaimAssessment	Does not rerun the candidate bootstrap or operators

ScenarioVerifier method families

Method family	Purpose
verify(...) / analyze(...)	Execute an ordinary Suite and return the verdict/report
Source-bound evidence overloads	Publish a sealed Suite artifact under a frozen source boundary
Governed/versioned methods	Bind business contracts to selected Requirement and Oracle records
Fixture fidelity and isolation methods	Add declared control or environment-isolation evidence
Property and sensitivity methods	Execute bounded generated samples, shrink, relations, or controlled mutants
Oracle independence methods	Run an explicitly bound reference model in a child JVM
compare(...) / compareEvidence(...)	Compare one frozen DSL graph change axis

Use the dedicated report type returned by the selected method. Do not flatten specialized evidence back into an ordinary Suite verdict.

Minimal builder

ScenarioVerifier verifier = ScenarioVerifier.builder()
    .bootstrap(caseContext ->
        VerificationEnvironment.controlled(operatorRegistry))
    .projectRoot(projectRoot)
    .policy(projectRoot.resolve("src/test/bloge/verification-policy.yaml"))
    .build();

For source-bound output, add sourceBoundEvidence(), an ignored outputDirectory(...) inside the project worktree, and the required execution profile. Keep the returned receipt externally and verify it with the matching reader before claim assessment.

Input and plan types

Type	Role
Scenario document	Suite, Cases, graph/context, expectations, Fixture references
Policy document	Assurance floor, required inventory, effect and resource obligations
Fixture document	Call-site or effect-port matching and controlled responses
Governance catalog/context	Versioned Requirement and Oracle selection
DurableVerificationPlan	Finite retained-session action chain and temporal checks
Property plan	Deterministic sample cohort, relation, seed, and optional supported shrink
Comparison plan	One declared change axis with all non-target inputs frozen

Extension SPIs

SPI	Why it exists
VerificationBootstrap	Creates a fresh customer verification environment per Case
VerificationEnvironmentLeaseProvider	Supplies comparable isolated environment leases
VerificationOperatorRegistryForkProvider	Preserves custom registry semantics while giving comparison runs independent forks
VerificationOperatorRegistryFingerprintProvider	Exposes stable identity for stateful custom registries
VerificationOracleReferenceModel	Executes an explicitly bound independent reference-model entry point

An SPI declaration is part of the evidence boundary. It is not proof that undeclared ambient state does not exist.

Reports, evidence, and readers

Layer	Use	Rule
In-memory report	Explain Suite, Case, action, sample, or comparison outcomes	Read status and ordered reason codes
Artifact directory	Store canonical manifest/report/summary/seal files	Keep it in the original ignored worktree output root
External receipt	Pin the exact artifact digest	Do not store it inside the artifact being sealed
Family-specific reader	Recompute source and projection relationships	Reject unknown versions and drift
VerificationClaims	Calculate the strongest supported gate	Consume reader-verified facts; never self-declare capability

Oracle v10/v11 readers may rerun the explicitly bound reference-model child JVM. Other readers validate source-owned artifacts without executing candidate operators or the customer bootstrap.

Schema catalogs

Document or artifact	Catalog
Scenario, Policy, Fixture, governance	VerificationSchemaCatalog
Durable actions	DurableVerificationSchemaCatalog
Durable temporal rules	DurableTemporalSchemaCatalog
Property input	PropertyVerificationSchemaCatalog
Contract sensitivity input	ContractSensitivitySchemaCatalog
Governed project configuration	VerificationGovernedProjectConfigurationSchemaCatalog
Evidence	The family-specific *EvidenceSchemaCatalog listed in Evidence versions

Catalog output is the compatibility source of truth. Do not infer a document shape from a higher numeric version in another family.

Concurrency and timeout rules

• A verifier with an execution profile admits one controlled run at a time.
• JUnit directory execution completes global preflight before any customer Case starts.
• A DurableVerificationRunner handles one retained plan at a time.
• A timeout that cannot stop customer code poisons that runner instance; construct a new one.
• Comparison coordinators share a bounded timeout and terminate visible child descendants.