From 7a7c631a8b5b870ade1e585a3c170ad834d5ad96 Mon Sep 17 00:00:00 2001 From: TimeLordRaps Date: Sun, 27 Sep 2026 22:02:02 -0700 Subject: [PATCH 1/6] Document v2 candidate on public site --- docs/DOCUMENTATION_HOSTING.md | 61 ++++++++++++++++++----------------- docs/guides.html | 13 ++++++++ docs/index.html | 6 ++++ scripts/build_docs_portal.py | 10 +++++- tests/test_docs_portal.py | 7 ++++ 5 files changed, 67 insertions(+), 30 deletions(-) diff --git a/docs/DOCUMENTATION_HOSTING.md b/docs/DOCUMENTATION_HOSTING.md index 4f5fee6..d6fdc94 100644 --- a/docs/DOCUMENTATION_HOSTING.md +++ b/docs/DOCUMENTATION_HOSTING.md @@ -1,14 +1,26 @@ # Documentation hosting -The documentation portal targets `https://verifier-standard.com/`. The corporate -site is `https://vstd-labs.com/`. Hosting configuration is an operational state; -the existence of this guide does not establish that either site is deployed. +The public documentation is assembled by the GitHub Pages workflow from the +qualified `main` commit. The documentation domain is +`https://verifier-standard.com/`; the corporate site is `https://vstd-labs.com/`. +Publishing a source branch does not update either public site. + +On 2026-09-27, public responses from the GitHub Pages address and the documentation +domain both reported documentation version `1.5.0` and source commit +`fc2a20c68d01920eda7e4e1bf14dfbcb334a7634`. The domain response carried +Cloudflare headers. These observations establish the served coordinates at that +time, not the account-side routing rule or future propagation. The separate +Cloudflare Pages preview at `verifier-standard-docs.pages.dev` still reported a +`1.3.0` documentation build and is not a current-release source. ## Build and inspect Build from the public repository using the -[repository walkthrough](REPOSITORY_WALKTHROUGH.md). The portal generator records -both the current source coordinate and the commit behind release tag `v1.5.0`. +[repository walkthrough](REPOSITORY_WALKTHROUGH.md). GitHub Pages uses +`scripts/build_pages.py` and records its exact source in +`documentation-coordinate.json` and the deployment manifest. The separate portal +generator records both the current source coordinate and the commit behind release +tag `v1.5.0`. Release documentation is built from that tag in a separate process. Equivalence between the tag and the published distribution remains a release-process dependency; the portal build does not silently claim to establish it. @@ -22,30 +34,21 @@ The generated search index stays with the site. Search queries stay in the browser. Code-copy buttons use the browser clipboard only when clicked. The color theme preference is stored locally when browser storage is available. -## Prepare Cloudflare Pages - -Use a dedicated Pages project named `verifier-standard-docs`, separate from the -corporate deployment. Upload the **contents** of the portal build directory so -`index.html` is at the deployment root. All required assets are local to the -build. The `_headers` file adds browser security response headers. - -Validate the preview before changing the domain: homepage, search, mobile -navigation, released reference, source reference, guide links, and schema routes. -Record `portal-coordinate.json` and the archive digest with the deployment receipt. - -## Cut over the domain +## Check the domain after GitHub Pages promotion -The domain previously served a permanent corporate redirect. After the -documentation preview is working, disable that specific redirect, bind -`verifier-standard.com` through Pages Custom domains, and inspect the exact -existing domain-name-system records before replacing a conflicting web record. -Do not purge the zone or modify mail records as part of a documentation cutover. +First confirm the GitHub Pages address serves the +expected `main` source commit and documentation version. Then check the same +coordinate, homepage, a deep guide, +reference page, and browser certificate at `verifier-standard.com`. A matching coordinate +is a routing check, not proof that every page is byte-identical or that the +Cloudflare account configuration was inspected. Investigate any mismatch in the +existing authenticated Edge session before changing routing. -Check the certificate, apex response, deep documentation paths, search index, and -version links from the public domain. Browsers may retain the previous permanent -redirect; test with a fresh request as well as an existing browser session. -If cutover fails, restore the previous web record and redirect configuration -using the pre-change snapshot, leaving the preview available for diagnosis. +If an intentional routing change is needed, inspect the exact Cloudflare web +records and rules, save their previous state, and validate a preview before +cutover. Leave mail records and unrelated redirects untouched. Verify the +public route again after the change; restore the saved web configuration if it +fails. A stale Pages preview must not be promoted as the current documentation. ## Preserve published identifiers @@ -58,5 +61,5 @@ Keep the current package's documentation metadata unchanged until the new domain is publicly reachable and validated. Update that metadata in a later authorized release change, rather than promising an unavailable documentation endpoint. -Publishing the public repository, uploading a build, and cutting over a domain -are distinct operations. Follow the maintainer's authorization for each one. +Publishing the public repository, promoting GitHub Pages, and changing a domain +route are distinct operations. Follow the maintainer's authorization for each one. diff --git a/docs/guides.html b/docs/guides.html index e0d0b33..4bfb8b1 100644 --- a/docs/guides.html +++ b/docs/guides.html @@ -81,6 +81,19 @@

Start here

+
+

Version 2.0.0 candidate source

+

This work is unreleased. These pages describe the current repository source; + the published 1.5.0 package and its reference remain separate.

+ +
+

Normative specifications

@@ -889,7 +891,7 @@

AssuranceLedger class

- + @@ -897,22 +899,22 @@

AssuranceLedger class

- + - - + + - - + + - - - - + + + +
MethodSummary
admissibility_blocking_conflicts(self) -> 'tuple[ConflictRecord, ...]'Return conflicts whose effect still blocks a clean TRUST route.
compose_guilt(self, ancestor_id: 'str', descendant_id: 'str', obligation: 'ObligationCoordinate', proposition: 'BoundProposition', *, localization_event_digest: 'str', responsibility_component_digest: 'str', applicability_component_digest: 'str', violation_component_digest: 'str', session: 'VerificationSession', recorded_at: 'str') -> 'DiagnosticAttribution'Compose technical GUILT from three exact, separately earned components.
current_status(self, artifact_id: 'str') -> 'ArtifactStatus'
current_status(self, artifact_id: 'str') -> 'ArtifactStatus'No method docstring is declared.
current_transformation_status(self, transformation_id: 'str') -> 'str'Return a transformation's additive current status projection.
current_trust_events(self) -> 'tuple[AssuranceEvent, ...]'Return recursively current edge-local TRUST records.
diagnose(self, kind: 'DiagnosticKind', ancestor_id: 'str', descendant_id: 'str', proposition: 'Optional[BoundProposition]', *, session: 'VerificationSession', recorded_at: 'str') -> 'DiagnosticAttribution'Compute BLAME, or fail closed for legacy opaque GUILT calls.
establish_obligation_applicability(self, artifact_id: 'str', obligation: 'ObligationCoordinate', proposition: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Evaluate whether one exact obligation applies to one exact artifact.
establish_obligation_violation(self, ancestor_id: 'str', descendant_id: 'str', obligation: 'ObligationCoordinate', proposition: 'BoundProposition', *, localization_event_digest: 'str', applicability_component_digest: 'str', session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Evaluate violation after exact applicability and deviation localization.
establish_responsibility(self, ancestor_id: 'str', descendant_id: 'str', proposition: 'BoundProposition', *, localization_event_digest: 'str', session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Evaluate one separately bound material-contribution component.
events(self) -> 'tuple[AssuranceEvent, ...]'
events(self) -> 'tuple[AssuranceEvent, ...]'No method docstring is declared.
impacted_descendants(self, artifact_id: 'str') -> 'tuple[str, ...]'Return the deduplicated recorded forward impact set, not a verdict.
localize_cause(self, ancestor_id: 'str', descendant_id: 'str', proposition: 'BoundProposition', *, rust_event_digest: 'str', session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Bind one ancestor to one exact passing descendant-deviation event.
materialize_current_graph(self) -> 'ProvenanceHypergraph'Create a derived current view; never mutate the historical graph.
project_challenges(self, challenges: 'ChallengeLedger', *, recorded_at: 'str') -> 'tuple[AssuranceEvent, ...]'Project challenge state into an additive current Graph overlay.
record_conflict(self, conflict: 'ConflictRecord', proposition: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Add mechanism-established current conflict evidence without rewriting Graph.
record_rot(self, artifact_id: 'str', resulting_status: 'ArtifactStatus', proposition: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'
record_rust(self, descendant_id: 'str', deviation: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'
record_rot(self, artifact_id: 'str', resulting_status: 'ArtifactStatus', proposition: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'No method docstring is declared.
record_rust(self, descendant_id: 'str', deviation: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'No method docstring is declared.
record_status_projection(self, artifact_id: 'str', proposition: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Record a mechanism-checked current-status projection additively.
record_trust(self, target_id: 'str', source_ids: 'Iterable[str]', proposition: 'BoundProposition', *, transformation_id: 'str', prerequisite_trust_event_digests: 'Iterable[str]' = (), session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'
resolutions(self) -> 'tuple[ConflictResolution, ...]'
record_trust(self, target_id: 'str', source_ids: 'Iterable[str]', proposition: 'BoundProposition', *, transformation_id: 'str', prerequisite_trust_event_digests: 'Iterable[str]' = (), session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'No method docstring is declared.
resolutions(self) -> 'tuple[ConflictResolution, ...]'No method docstring is declared.
resolve_conflict(self, conflict_id: 'str', selected_value: 'str', proposition: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'ConflictResolution'Adjudicate one value without equating selection with admissibility.
rust_concentration(self) -> 'tuple[StructuralConcentration, ...]'
to_dict(self) -> 'dict[str, Any]'
unresolved_conflicts(self) -> 'tuple[ConflictRecord, ...]'
verify_hash_chain(self) -> 'bool'
rust_concentration(self) -> 'tuple[StructuralConcentration, ...]'No method docstring is declared.
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
unresolved_conflicts(self) -> 'tuple[ConflictRecord, ...]'No method docstring is declared.
verify_hash_chain(self) -> 'bool'No method docstring is declared.
@@ -921,8 +923,8 @@

BoundProposition class

Exact proposition, evidence, mechanism, trust-root, and bound binding.

Defined in verifier.core.evidence

- - + +
MethodSummary
digest(self) -> 'str'
to_dict(self) -> 'dict[str, Any]'
digest(self) -> 'str'No method docstring is declared.
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
@@ -938,8 +940,8 @@

CertificationPolicy class

External mechanism admission and resource policy, not certificate authority.

Defined in verifier.core.grounded_certification

- - + +
MethodSummary
digest(self) -> 'str'
to_dict(self) -> 'dict[str, Any]'
digest(self) -> 'str'No method docstring is declared.
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
@@ -948,7 +950,7 @@

CertificationRequest class

Exact claim and individual evidence propositions; no supplied outcomes.

Defined in verifier.core.grounded_certification

- +
MethodSummary
to_dict(self) -> 'dict[str, Any]'
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
@@ -957,7 +959,7 @@

ControlSurfaceContext class

External planning context; only schema and interaction mode affect matches.

Defined in verifier.interoperability.control_surface

- +
MethodSummary
to_dict(self) -> 'dict[str, Any]'
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
@@ -966,8 +968,8 @@

DecisionCertificate class

Canonical grounded decision certificate (GDC) blocks for the bounded checker.

Defined in verifier.core.certificate

- - + +
MethodSummary
digest(self) -> 'str'
to_dict(self) -> 'dict[str, Any]'
digest(self) -> 'str'No method docstring is declared.
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
without_hints(self) -> "'DecisionCertificate'"Hint-stripped form.
@@ -984,7 +986,7 @@

EvidenceBounds class

Resource ceilings enforced before invoking a domain mechanism.

Defined in verifier.core.evidence

- +
MethodSummary
to_dict(self) -> 'dict[str, int]'
to_dict(self) -> 'dict[str, int]'No method docstring is declared.
@@ -993,10 +995,10 @@

EvidenceStore class

In-memory content-addressed evidence store with collision/fork refusal.

Defined in verifier.core.evidence

- + - +
MethodSummary
add(self, payload: 'bytes') -> 'str'
add(self, payload: 'bytes') -> 'str'No method docstring is declared.
export_base64(self, references: 'Sequence[str]') -> 'dict[str, str]'Export exact evidence bytes for portable, offline mechanism replay.
import_base64(self, payloads: 'Mapping[str, str]') -> 'None'Import a portable bundle and refuse every reference/byte mismatch.
resolve(self, reference: 'str') -> 'bytes'
resolve(self, reference: 'str') -> 'bytes'No method docstring is declared.
@@ -1018,7 +1020,7 @@

MechanismAdmission class

Checker-selected executable and trust roots for one exact obligation.

Defined in verifier.core.grounded_certification

- +
MethodSummary
to_dict(self) -> 'dict[str, Any]'
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
@@ -1040,7 +1042,7 @@

NativeCertificationMechanism class

Execute bounded claim-record, geometry and decision-certificate checks.

Defined in verifier.core.certification_mechanisms

- +
MethodSummary
evaluate(self, binding: 'BoundProposition', evidence: 'Sequence[bytes]') -> 'MechanismDecision'
evaluate(self, binding: 'BoundProposition', evidence: 'Sequence[bytes]') -> 'MechanismDecision'No method docstring is declared.

@@ -1049,7 +1051,7 @@

NativeDomainAdapter class

Executable mechanism for one domain; registration supplies no implicit authority.

Defined in verifier.domains.certification

- +
MethodSummary
evaluate(self, binding: 'BoundProposition', evidence: 'Sequence[bytes]') -> 'MechanismDecision'
evaluate(self, binding: 'BoundProposition', evidence: 'Sequence[bytes]') -> 'MechanismDecision'No method docstring is declared.
@@ -1058,8 +1060,8 @@

ObligationCoordinate class

Exact technical obligation and the declared scope in which it applies.

Defined in verifier.data.assurance

- - + +
MethodSummary
digest(self) -> 'str'
to_dict(self) -> 'dict[str, Any]'
digest(self) -> 'str'No method docstring is declared.
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
@@ -1068,7 +1070,7 @@

PlatformComparisonResult class

Machine-readable diagnostic result; this object is not a VSTD receipt.

Defined in verifier.core.platform_comparison

- +
MethodSummary
to_dict(self) -> 'dict[str, Any]'
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
@@ -1083,7 +1085,7 @@

ProfileObligation class

A separately checked proposition with explicit prerequisite obligations.

Defined in verifier.core.profile_obligations

- +
MethodSummary
to_dict(self) -> 'dict[str, Any]'
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
@@ -1092,20 +1094,20 @@

ProvenanceHypergraph class

N-ary Hypergraph structure for dataset, training, and artifact lineage.

Defined in verifier.data.models

- - - - - + + + + + - + - + - +
MethodSummary
add_artifact(self, artifact: 'ArtifactNode') -> 'str'
add_conflict(self, conflict: 'ConflictRecord') -> 'str'
add_contributor(self, contributor: 'ContributorSpec') -> 'str'
add_rights(self, rights: 'RightsSpec') -> 'str'
add_transformation(self, transform: 'TransformationHyperedge') -> 'str'
add_artifact(self, artifact: 'ArtifactNode') -> 'str'No method docstring is declared.
add_conflict(self, conflict: 'ConflictRecord') -> 'str'No method docstring is declared.
add_contributor(self, contributor: 'ContributorSpec') -> 'str'No method docstring is declared.
add_rights(self, rights: 'RightsSpec') -> 'str'No method docstring is declared.
add_transformation(self, transform: 'TransformationHyperedge') -> 'str'No method docstring is declared.
ancestors(self, artifact_ids: 'Iterable[str]') -> 'set[str]'Backward reachability closure across transformation hyperedges.
blast_radius(self, revoked_artifact_id: 'str') -> 'list[str]'Compute the forward blast radius of affected downstream artifacts when one node is revoked.
compute_completeness(self) -> 'CompletenessMetrics'
compute_completeness(self) -> 'CompletenessMetrics'No method docstring is declared.
descendants(self, artifact_ids: 'Iterable[str]') -> 'set[str]'Forward reachability closure across transformation hyperedges.
has_conflict(self, subject_id: 'str') -> 'bool'
has_conflict(self, subject_id: 'str') -> 'bool'No method docstring is declared.
incoming_hyperedges(self, artifact_id: 'str') -> 'list[TransformationHyperedge]'Hyperedges that produce artifact_id as an output.
outgoing_hyperedges(self, artifact_id: 'str') -> 'list[TransformationHyperedge]'Hyperedges that consume artifact_id as an input.
root_sources(self) -> 'set[str]'Artifacts with zero incoming hyperedges (genesis roots).
to_dict(self) -> 'dict[str, Any]'
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
validate_structure(self, *, allow_legacy_identifier_overlap: 'bool' = False) -> 'list[str]'Return deterministic errors for the implemented graph surface.
verify_acyclicity(self, artifact_ids: 'Optional[Iterable[str]]' = None) -> 'bool'Check whether all or a selected artifact-induced subgraph contains cycles.
@@ -1122,8 +1124,8 @@

SurfaceAnalysis class

Deterministic report over only the supplied, declared geometry.

Defined in verifier.interoperability.control_surface

- - + +
MethodSummary
canonical_json_bytes(self) -> 'bytes'
to_dict(self) -> 'dict[str, Any]'
canonical_json_bytes(self) -> 'bytes'No method docstring is declared.
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
@@ -1139,7 +1141,7 @@

SurfaceHole class

One structured diagnostic derived from an existing geometry blocker.

Defined in verifier.interoperability.control_surface

- +
MethodSummary
to_dict(self) -> 'dict[str, Any]'
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
@@ -1155,8 +1157,8 @@

VerificationGeometry class

Defined in verifier.core.geometry

- - + +
MethodSummary
assess_closure(self) -> 'ClosureAssessment'Assess declared closure and higher-order self-closure separately.
canonical_digest(self) -> 'str'
to_dict(self) -> 'dict[str, Any]'
canonical_digest(self) -> 'str'No method docstring is declared.
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
validate(self) -> 'list[str]'Return structural and epistemic errors; an empty list means valid.
@@ -1166,9 +1168,9 @@

VerificationSession class

Resolve evidence and rerun only explicitly registered mechanisms.

Defined in verifier.core.evidence

- + - +
MethodSummary
evaluate(self, binding: 'BoundProposition') -> 'EvaluatedProposition'
evaluate(self, binding: 'BoundProposition') -> 'EvaluatedProposition'No method docstring is declared.
evaluate_compound(self, bindings: 'Sequence[BoundProposition]') -> 'tuple[EvaluatedProposition, ...]'Run one compound mechanism invocation over separately bound propositions.
register(self, mechanism: 'VerificationMechanism') -> 'None'
register(self, mechanism: 'VerificationMechanism') -> 'None'No method docstring is declared.
registered_mechanisms(self) -> 'tuple[VerificationMechanism, ...]'Snapshot caller-registered capabilities for an isolated evidence replay.
@@ -1184,11 +1186,11 @@

VstdReceipt class

Mutable in-memory model of a canonically digested VSTD-1 claim receipt.

Defined in verifier.core.receipt

- + - - - + + +
MethodSummary
compute_and_set_digest(self) -> 'str'
compute_and_set_digest(self) -> 'str'No method docstring is declared.
get_stable_payload(self) -> 'dict[str, Any]'Extract only deterministic, location-independent fields for canonical hashing.
save_to_directory(self, out_dir: 'Path') -> 'Path'
to_dict(self) -> 'dict[str, Any]'
verify_digest_integrity(self) -> 'bool'
save_to_directory(self, out_dir: 'Path') -> 'Path'No method docstring is declared.
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
verify_digest_integrity(self) -> 'bool'No method docstring is declared.
@@ -1197,7 +1199,7 @@

WitnessBundle class

Claim-bound identities, ordered separation assertions, and corroborations.

Defined in verifier.core.witness

- +
MethodSummary
to_dict(self) -> 'dict[str, Any]'
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
diff --git a/scripts/build_reference.py b/scripts/build_reference.py index 92e73ff..c1229a6 100644 --- a/scripts/build_reference.py +++ b/scripts/build_reference.py @@ -6,9 +6,10 @@ Generate the public CLI and top-level API reference page from the live implementation. -Nothing on the generated page is hand-written prose about behaviour: every command, -option, top-level export, signature, and listed pipeline edge is read out of the -importable package at build time. `scripts/check_presentation.py` and +CLI names and options come from the argument parser; top-level Python names and +signatures come from the importable package. The pipeline map is a selected, +manually described set of import-checked dispatch targets, and summaries come +from source docstrings. `scripts/check_presentation.py` and `tests/test_presentation_surface.py` regenerate this file and fail closed when the committed page drifts from the code.""" @@ -356,9 +357,10 @@ def _api_section() -> str: member_signature = f"{member_name}{inspect.signature(member)}" except (TypeError, ValueError): member_signature = member_name + method_summary = _summary(member) or "No method docstring is declared." rows += ( f"{_esc(member_signature)}" - f"{_esc(_summary(member))}\n" + f"{_esc(method_summary)}\n" ) if rows: members = ( @@ -478,19 +480,21 @@ def render() -> str:
Reference · {_esc(source_coordinate)} · {_esc(standard)} {_esc(standard_status)}
-

Inspect the whole pipeline.

+

Inspect the supported surface.

Terms used below: hash-based message authentication code (HMAC); International Organization for Standardization (ISO); JavaScript Object Notation (JSON); Secure Hash Algorithm 256-bit (SHA-256); and YAML Ain't Markup Language (YAML).

-

Every command, argument, top-level export, and listed dispatch edge below - is read out of the installed package when this page is built, by - scripts/build_reference.py, and the presentation tests fail closed when the - committed page drifts — so it cannot describe behaviour the implementation no - longer has.

+

The command and argument inventory comes from the parser; the Python + export inventory and signatures come from verifier.__all__ at build time. + The pipeline map selects import-checked implementation targets. Summaries come from + source docstrings or the map's reviewed prose. Presentation tests detect generated + page drift from these sources; they do not prove the described behaviour correct.

This page states the declared public surface of one implementation. It - does not establish that any individual claim checked by these commands is true, nor that - an external implementation exists.

+ does not cover experimental direct submodule imports. A method marked "No method + docstring is declared" has a signature here but no descriptive contract. The page + does not establish that an individual claim checked by these commands is true, nor + that an external implementation exists.

Pipeline map CLI reference @@ -502,7 +506,7 @@ def render() -> str:
Pipeline
-

Command to implementation, without a gap.

+

Selected command-to-implementation paths.

Each entry point below is imported while this page is built. A rename, move, or deletion fails the build instead of publishing a stale map.

{_pipeline_section()}
From 0f33a9a7e8ca0e9932011814614f2ad54adbe502 Mon Sep 17 00:00:00 2001 From: TimeLordRaps Date: Mon, 28 Sep 2026 00:18:45 -0700 Subject: [PATCH 3/6] docs: refresh source feature inventory for portal changes --- docs/PR_SOURCE_FEATURES.json | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/PR_SOURCE_FEATURES.json b/docs/PR_SOURCE_FEATURES.json index 6d6eee9..689ee0d 100644 --- a/docs/PR_SOURCE_FEATURES.json +++ b/docs/PR_SOURCE_FEATURES.json @@ -66,10 +66,12 @@ }, { "path": "scripts/build_docs_portal.py", - "sha256": "53a94ff7af277afe5d029ee8a8b127ce012340a57c22984a0891953aa9009231", - "symbols": [], - "summary": "Pins the documentation portal release links to version 1.5.0 and its recorded commit.", - "limits": "This is a link/source pin for the already dated release and does not make the 2.0.0 candidate public." + "sha256": "d6175601af86f7fb67db283d5829423630a45fda9b97cb2fd7d6ce493394fd4b", + "symbols": [ + "navigation" + ], + "summary": "Builds separate published 1.5.0 and unreleased source documentation editions with edition-aware navigation and search.", + "limits": "The published edition stays pinned to its recorded release source; this build does not deploy the candidate, certify its claims, or verify account-side domain routing." }, { "path": "scripts/build_formation_corpus.py", @@ -126,13 +128,14 @@ }, { "path": "scripts/build_reference.py", - "sha256": "c49dc9eae7211ad8aa8db4c559c38a077549b0eaf3e78e0edf5a1d8d6ec242e6", + "sha256": "a8dd6a8b1fa74c1e9d2cc5428e55725dcc73cad2525684ff1944a0cc850823ad", "symbols": [ + "_api_section", "_cli_section", "render" ], - "summary": "Adds start, explain, certification, and publish command entries to the generated reference pipeline, renames Graph terminology, and renders parser fallback defaults without GitHub runner metadata.", - "limits": "The generated reference describes registered calls and environment-free fallback defaults; it does not run the commands, override runtime GitHub defaults, or prove a submission was accepted." + "summary": "Generates command and argument inventory from the parser and supported Python exports from verifier.__all__; import-checks a selected pipeline map and marks missing method docstrings.", + "limits": "The selected map and source summaries are descriptions, not behavior proofs. Experimental direct submodules and methods lacking docstrings remain outside full descriptive coverage." }, { "path": "scripts/build_silo_composition_fixture.py", From a8015ccb1c1d8005c0176ad9e45d6cae42672740 Mon Sep 17 00:00:00 2001 From: TimeLordRaps Date: Mon, 28 Sep 2026 01:21:48 -0700 Subject: [PATCH 4/6] Make v2 candidate the primary documentation edition --- docs/FIRST_RECEIPT.md | 12 ++---- docs/INSTALLATION.md | 29 ++++++++----- docs/NEWCOMER_GUIDE.md | 9 ++-- docs/PR_SOURCE_FEATURES.json | 32 ++++++++++++-- docs/QUICKSTART.md | 9 ++-- docs/guides.html | 18 ++++---- docs/index.html | 22 +++++----- docs/tutorials/PUBLISH_A_SILO.md | 5 ++- docs/tutorials/SEAL_AN_ARTIFACT.md | 6 +-- scripts/build_docs_portal.py | 67 +++++++++++++++++++++-------- scripts/portal/home.html.in | 13 +++--- scripts/portal/portal.js | 2 +- scripts/portal/release-home.html.in | 16 +++++++ tests/test_docs_portal.py | 25 ++++++++--- tests/test_presentation_surface.py | 6 ++- 15 files changed, 186 insertions(+), 85 deletions(-) create mode 100644 scripts/portal/release-home.html.in diff --git a/docs/FIRST_RECEIPT.md b/docs/FIRST_RECEIPT.md index 0267189..8ea77f5 100644 --- a/docs/FIRST_RECEIPT.md +++ b/docs/FIRST_RECEIPT.md @@ -2,18 +2,14 @@ This walkthrough uses the Verifier Standard (VSTD) generic-run example: a small word-frequency computation with declared input and output files. It requires Git -and the [released package installation](INSTALLATION.md). +and the [v2.0.0 candidate source installation](INSTALLATION.md). ## Get the matching example -Use the example from the same release as the installed package: +Use the example from the same v2.0.0 candidate checkout as the installed source. +Run the commands below from that checkout's root. -```bash -git clone --branch v1.5.0 --depth 1 https://github.com/TimeLordRaps/verifier.git verifier-example -cd verifier-example -``` - -This checkout is a release snapshot, not a development branch. The example lives +The site's source coordinate identifies the candidate revision. The example lives under `examples/generic_run/`. Its manifest names the command, inputs, outputs, claim scope, limitations, and falsification conditions. diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index ef60c64..a186972 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -3,11 +3,13 @@ Verifier implements the Verifier Standard (VSTD), a verification-domain language for portable, bounded, refutable evidence about computational claims. -## Install the released package +## Install the v2.0.0 candidate source Use Python 3.10 or newer in a fresh virtual environment. The base runtime has no -required third-party dependencies. These instructions pin release **1.5.0** from -the Python Package Index (PyPI). +required third-party dependencies. Use the v2.0.0 source revision identified in +the GitHub Pages `documentation-coordinate.json` or the portal preview's +`portal-coordinate.json`. Version 2.0.0 is not yet a +published Python Package Index (PyPI) release. From that source checkout: ```bash python -m venv .venv @@ -28,12 +30,12 @@ source .venv/bin/activate Install and inspect the version: ```bash -python -m pip install verifier-standard==1.5.0 +python -m pip install . python -c "import verifier; print(verifier.__version__)" vstd --help ``` -The version command should print `1.5.0`. The distribution name is +The version command should print `2.0.0` for this candidate source. The distribution name is `verifier-standard`; the Python import is `verifier`; the cross-platform command is `vstd`. On Windows, the name `verifier` can resolve to Windows Driver Verifier, so use `vstd` for this package. @@ -70,11 +72,18 @@ See the [API stability policy](API_STABILITY.md) before depending on an export. ## Choose a documentation coordinate -The documentation portal provides a released `1.5.0` reference generated from the -corresponding Git tag and a separate current repository reference. Repository -source can include commands that the released distribution does not yet contain. -Use the version selector or the **Package reference · 1.5.0** navigation group when -working with the package above. +The root documentation and generated reference describe the v2.0.0 candidate +source. They are tied to the repository revision in the site's build metadata. +Read the [candidate scope and migration guide](V2_CANDIDATE.md) and +[open contradictions](../TIME.md) before relying on candidate behavior. + +The separately built portal preview has a version selector and a tagged archive +for the published `1.5.0` package. If you need that release, install +`verifier-standard==1.5.0` from PyPI and use its tagged +[GitHub release](https://github.com/TimeLordRaps/verifier/releases/tag/v1.5.0) +and corresponding reference. The GitHub Pages build does not include the portal +archive. +Do not mix examples or API coverage across these coordinates. To work on repository changes, follow the [repository walkthrough](REPOSITORY_WALKTHROUGH.md). Avoid mixing an editable diff --git a/docs/NEWCOMER_GUIDE.md b/docs/NEWCOMER_GUIDE.md index accd810..43ca8eb 100644 --- a/docs/NEWCOMER_GUIDE.md +++ b/docs/NEWCOMER_GUIDE.md @@ -53,10 +53,13 @@ VSTD elevates `UNKNOWN` to a first-class, honorable result: You do not need complicated tools or heavy frameworks to use VSTD. The reference library has **zero required third-party dependencies**—it runs on standard Python 3.10+. -### Step 1: Install `verifier-standard` +### Step 1: Install v2.0.0 candidate source + +Use the v2.0.0 source checkout identified by the documentation site's source +coordinate. This version has not been published to the Python Package Index. ```bash -python -m pip install "verifier-standard==1.5.0" +python -m pip install . ``` ### Step 2: Inspect the library @@ -67,7 +70,7 @@ Open a Python interactive shell: import verifier print(verifier.__version__) -# '1.5.0' +# Confirm this matches the candidate source coordinate. print(verifier.__standard__) # 'VSTD-5' diff --git a/docs/PR_SOURCE_FEATURES.json b/docs/PR_SOURCE_FEATURES.json index 689ee0d..8e4f874 100644 --- a/docs/PR_SOURCE_FEATURES.json +++ b/docs/PR_SOURCE_FEATURES.json @@ -66,12 +66,15 @@ }, { "path": "scripts/build_docs_portal.py", - "sha256": "d6175601af86f7fb67db283d5829423630a45fda9b97cb2fd7d6ce493394fd4b", + "sha256": "682f99741c9bb216666395de907c8f6ffea4ffaa139f4466484bf79a10a59499", "symbols": [ - "navigation" + "build", + "home", + "navigation", + "shell" ], - "summary": "Builds separate published 1.5.0 and unreleased source documentation editions with edition-aware navigation and search.", - "limits": "The published edition stays pinned to its recorded release source; this build does not deploy the candidate, certify its claims, or verify account-side domain routing." + "summary": "Makes v2.0.0 candidate source the portal root and default search scope, while rendering a separate tagged 1.5.0 homepage and release navigation.", + "limits": "The release edition stays pinned to its tag; the portal remains a preview artifact and does not replace the GitHub Pages deployment, certify v2 claims, or verify domain routing." }, { "path": "scripts/build_formation_corpus.py", @@ -274,6 +277,27 @@ "summary": "Adds a direct-execution import fallback for the release-version classifier when extracting dated changelog notes.", "limits": "The fallback fixes local module resolution; it does not create a release or validate upstream publication." }, + { + "path": "scripts/portal/home.html.in", + "sha256": "dd685bcecbf2347614f7e5fc7f29039661ba71ff8579e0bdbc525824d1564d86", + "symbols": [], + "summary": "Makes the portal landing page lead to the unreleased v2.0.0 source reference and local source installation.", + "limits": "The generated reference lists current exports, but landing-page links do not establish complete API explanations or release readiness." + }, + { + "path": "scripts/portal/portal.js", + "sha256": "005ff90cbebdbb897a0b9fc6fd701bea1702c45417cf767952c542d22445f9c5", + "symbols": [], + "summary": "Labels search results by v2.0.0 candidate source or released 1.5.0 archive.", + "limits": "Search labels depend on the generated edition index and do not verify the underlying technical claims." + }, + { + "path": "scripts/portal/release-home.html.in", + "sha256": "872b784c5bd91fc74ff1ea4853ad464dd728caecaf9963ba92469d168e1c2ca6", + "symbols": [], + "summary": "Preserves the tagged 1.5.0 package homepage in its separate archive edition.", + "limits": "The tagged source build does not prove equivalence to the published distribution or future archive availability." + }, { "path": "scripts/preflight.py", "sha256": "ac3c0327aa75d806048ebf768667d9ba34bda1a287a1e9e0c70d78e812710303", diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index caad8b3..a943845 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -2,14 +2,15 @@ > Reader aid: [concept glossary and primary precedents](CONCEPTS_AND_PRECEDENTS.md). -## 1. Install the public source +## 1. Install the v2.0.0 candidate source VSTD requires Python 3.10–3.13. The base runtime has no required third-party -dependencies. +dependencies. Use the v2 candidate checkout identified by the documentation +site's source coordinate. The default branch may not yet contain this candidate +while its release pull request is under review. ```bash -git clone https://github.com/TimeLordRaps/verifier.git -cd verifier +# From the v2.0.0 candidate checkout python -m pip install . ``` diff --git a/docs/guides.html b/docs/guides.html index 4bfb8b1..3082dad 100644 --- a/docs/guides.html +++ b/docs/guides.html @@ -4,12 +4,12 @@ - + - VSTD guides and standards + Verifier Standard v2.0.0 candidate guides @@ -35,7 +35,7 @@
-
Public documentation
+
Verifier Standard v2.0.0 candidate source

Find the exact boundary.

This page links the maintained guides and specifications without restating them. Normative requirements live under standard/; guides and @@ -43,11 +43,11 @@

Find the exact boundary.

Interoperability material below uses Supply Chain Integrity, Transparency, and Trust (SCITT).

Documentation coordinate: - verifier-standard 1.5.0, released 2026-09-18. The assembled site also - carries machine-readable build metadata; - the versioned release - artifacts preserve this coordinate. Normative ownership remains under - standard/.

+ v2.0.0 candidate source, under review and not yet published as a + package. The assembled site carries + machine-readable build metadata. + The published 1.5.0 release remains a separate + edition. Normative ownership remains under standard/.

Start with the quickstart Read the specifications @@ -60,7 +60,7 @@

Find the exact boundary.

Start here

  • Quickstart — install, inspect, capture, validate, and refute.
    • -
  • Install Verifier — supported interpreters, the published release, and a source checkout.
    • +
  • Install Verifier — supported interpreters, the v2 candidate source, and the published archive.
  • Your first receipt — plan, run, validate, and refute one generic run end to end.
  • Typical use cases — ten situations, the mechanism for each, and what each one leaves unestablished.
  • Seal an artifact — freeze, seal, thaw, and detect a changed byte.
    • diff --git a/docs/index.html b/docs/index.html index d825a09..01fcba1 100644 --- a/docs/index.html +++ b/docs/index.html @@ -4,12 +4,12 @@ - + - VSTD — portable, bounded, refutable + Verifier Standard v2.0.0 candidate documentation @@ -35,7 +35,7 @@
    -
    Verification language for computational work
    +
    Verifier Standard v2.0.0 candidate source

    Make the claim challengeable.

    VSTD packages bounded computational claims with their evidence, checking mechanisms, limits, refutation conditions, provenance, and @@ -122,16 +122,18 @@

    Useful without pretending to be total.

    Current implementation status

    VSTD is a maintainer-led alpha project specification. Compatibility VSTD-4 and Graph paths remain NOT_ESTABLISHED candidates. Separate evidence-bound VSTD-4, VSTD-5, Graph-profile, and assurance-event paths rerun exact registered mechanisms from embedded evidence; no real external witness is claimed by this repository. The project has no demonstrated external adoption, independent implementation, interoperability deployment, or third-party security review.

    Artifact-control boundary: freeze preserves exact bytes and sealing is not encryption. A thaw sidecar alone is unkeyed metadata and remains NOT_ESTABLISHED; clean or dirty status requires the actual supplied parent to verify as sealed with every recorded parent coordinate matching. This current comparison does not authenticate the historical copy operation or external continuity.

    -

    Release coordinate: - verifier-standard 1.5.0, released 2026-09-18. Use the - versioned GitHub release - for published artifacts and citation coordinates.

    -

    Version 2.0.0 candidate: The current repository source is - under review and is not a published package. Read the +

    Documentation coordinate: + v2.0.0 candidate source. The current repository source is + under review and is not a published package. The site's source revision is + recorded in its footer and build metadata. Read the candidate scope and migration guide, grounded certification guide, and open repository contradictions before using - candidate behavior. The released 1.5.0 package does not inherit these additions.

    + candidate behavior.

    +

    Published archive: + verifier-standard 1.5.0, released 2026-09-18, has a + separate versioned artifacts and citation coordinates. + The released package does not inherit v2 candidate additions.

    Review the maturity table Report an ambiguity or counterexample diff --git a/docs/tutorials/PUBLISH_A_SILO.md b/docs/tutorials/PUBLISH_A_SILO.md index 49b42f9..9580d68 100644 --- a/docs/tutorials/PUBLISH_A_SILO.md +++ b/docs/tutorials/PUBLISH_A_SILO.md @@ -18,8 +18,11 @@ Retained artifacts are never executed by any command here. ## Set up +From the v2.0.0 candidate source checkout identified by this site's source +coordinate, install the optional sealing dependency: + ```bash -python -m pip install "verifier-standard[seal]==1.5.0" +python -m pip install ".[seal]" openssl genpkey -algorithm Ed25519 -out publisher-private.pem ``` diff --git a/docs/tutorials/SEAL_AN_ARTIFACT.md b/docs/tutorials/SEAL_AN_ARTIFACT.md index 9116968..59a147f 100644 --- a/docs/tutorials/SEAL_AN_ARTIFACT.md +++ b/docs/tutorials/SEAL_AN_ARTIFACT.md @@ -7,16 +7,16 @@ copy, and then changes that copy so the runtime reports a different verdict. The steps matter most: a mechanism that never reports a negative result has not been shown to detect anything. -Every command below belongs to the published `vstd artifact` surface, and none of them +Every command below belongs to the `vstd artifact` surface, and none of them executes the artifact's contents. It requires the -[released package installation](../INSTALLATION.md). +[v2.0.0 candidate source installation](../INSTALLATION.md). ## Install the sealing extra Sealing uses Ed25519 signatures, which come from the optional `seal` dependency: ```bash -python -m pip install "verifier-standard[seal]==1.5.0" +python -m pip install ".[seal]" vstd artifact --help ``` diff --git a/scripts/build_docs_portal.py b/scripts/build_docs_portal.py index c54d0ab..76acbbc 100644 --- a/scripts/build_docs_portal.py +++ b/scripts/build_docs_portal.py @@ -142,10 +142,45 @@ def navigation(prefix: str, output: Path) -> list[tuple[str, list[tuple[str, str def route(path: str) -> str: return prefix + path if (output / (prefix + path)).exists() else path + if not prefix: + return [ + ("Start here", [("Introduction", "index.html"), + ("Install v2.0.0 candidate source", "docs/INSTALLATION.html"), + ("Your first receipt", "docs/FIRST_RECEIPT.html"), + ("Typical use cases", "docs/USE_CASES.html")]), + ("v2.0.0 source reference", [("Commands", "reference.html#cli"), + ("Python exports", "reference.html#api"), + ("Python API guide", "docs/PYTHON_API_GUIDE.html"), + ("API stability", "docs/API_STABILITY.html")]), + ("Version 2.0.0 candidate", [ + ("Candidate scope and migration", "docs/V2_CANDIDATE.html"), + ("Grounded certification", "docs/GROUNDED_CERTIFICATION.html"), + ("Gate automation", "docs/GATE_AUTOMATION.html"), + ("Open contradictions", "project/TIME.html"), + ]), + ("Tutorials", [("Seal an artifact", "docs/tutorials/SEAL_AN_ARTIFACT.html"), + ("Publish a silo", "docs/tutorials/PUBLISH_A_SILO.html")]), + ("Understand the model", [("Concepts & precedents", "docs/CONCEPTS_AND_PRECEDENTS.html"), + ("Claims & limits", "docs/CLAIMS_AND_LIMITS.html"), + ("Numbered profiles", "standard/index.html"), + ("All guides", "guides.html")]), + ("Work in the repository", [("Repository walkthrough", "docs/REPOSITORY_WALKTHROUGH.html"), + ("Component catalog", "components/index.html"), + ("Architecture", "docs/ARCHITECTURE.html"), + ("Experiments", "experiments/index.html")]), + ("Published archive · " + RELEASE, [("Release introduction", RELEASE_PATH + "index.html"), + ("Release commands", RELEASE_PATH + "reference.html#cli"), + ("Release Python exports", RELEASE_PATH + "reference.html#api")]), + ("Contribute", [("Contribution guidelines", "project/CONTRIBUTING.html"), + ("Security reporting", "project/SECURITY.html"), + ("Roadmap", "project/ROADMAP.html"), + ("Changelog", "project/CHANGELOG.html")]), + ] + groups = [ ("Start here", [("Introduction", prefix + "index.html"), - ("Install Verifier", "docs/INSTALLATION.html"), - ("Your first receipt", "docs/FIRST_RECEIPT.html"), + ("Install Verifier", route("docs/INSTALLATION.html")), + ("Your first receipt", route("docs/FIRST_RECEIPT.html")), ("Typical use cases", route("docs/USE_CASES.html"))]), ("Tutorials", [("Seal an artifact", route("docs/tutorials/SEAL_AN_ARTIFACT.html")), ("Publish a silo", route("docs/tutorials/PUBLISH_A_SILO.html")), @@ -167,18 +202,16 @@ def route(path: str) -> str: ("Roadmap", "project/ROADMAP.html"), ("Changelog", "project/CHANGELOG.html")]), ] - if not prefix: - groups.insert(4, ("Version 2.0.0 candidate", [ - ("Candidate scope and migration", "docs/V2_CANDIDATE.html"), - ("Grounded certification", "docs/GROUNDED_CERTIFICATION.html"), - ("Gate automation", "docs/GATE_AUTOMATION.html"), - ("Open contradictions", "project/TIME.html"), - ])) return groups -def home() -> str: - return (ASSETS / "home.html.in").read_text(encoding="utf-8").replace("{{release}}", RELEASE).replace("{{release_path}}", RELEASE_PATH) +def home(stable: bool) -> str: + template = "release-home.html.in" if stable else "home.html.in" + content = (ASSETS / template).read_text(encoding="utf-8") + if stable: + for section in ("docs/", "project/"): + content = content.replace('href="@/' + section, 'href="@/{{release_path}}' + section) + return content.replace("{{release}}", RELEASE).replace("{{release_path}}", RELEASE_PATH) def shell(content: str, *, route: str, title: str, outline: list[tuple[str, str]], @@ -200,11 +233,11 @@ def navlink(label: str, target: str) -> str: "".join(navlink(name, target) for name, target in entries) + "
" for label, entries in groups) toc = "".join(f'{html.escape(label)}' for anchor, label in outline) - coordinate = "Released package " + RELEASE if stable else "Repository documentation" + coordinate = "Released package " + RELEASE if stable else "v2.0.0 candidate source" other = route.removeprefix(RELEASE_PATH) if stable else RELEASE_PATH + route if not (output / other).is_file(): other = "index.html" if stable else RELEASE_PATH + "index.html" - version_links = navlink("Released " + RELEASE, route if stable else other) + navlink("Repository source", other if stable else route) + version_links = navlink("v2.0.0 candidate source", other if stable else route) + navlink("Released " + RELEASE + " archive", route if stable else other) source = REPOSITORY + "/tree/" + source_ref known = [target for _, entries in groups for _, target in entries if "#" not in target] next_link = "" @@ -234,12 +267,12 @@ def navlink(label: str, target: str) -> str:
{coordinate}
{version_links}
{sidebar}
Verifier Standard (VSTD)
Open source · Apache-2.0
Documentation/{html.escape(title)}
-
{coordinate}{'Source pinned to ' + RELEASE_TAG if stable else 'May include additions beyond the released package'}
+
{coordinate}{'Source pinned to ' + RELEASE_TAG if stable else 'Unreleased source; inspect the source coordinate and open contradictions before use'}
{content}
{next_link}
-

Type to search.

 -''' +

Type to search.

 +''' def search_entries(content: str, route: str, title: str) -> list[dict[str, str]]: @@ -294,7 +327,7 @@ def build(output: Path, *, base_url: str = SITE) -> dict[str, object]: lambda m: 'href="' + "../" * depth + prefix + m.group(1) + '"', page) content, title, outline = prepare_content(page) if route in ("index.html", RELEASE_PATH + "index.html"): - content = home() + content = home(bool(prefix)) content = content.replace('href="@/', 'href="' + "../" * depth) title = "Introduction" outline = [("start-building", "Start building"), ("explore", "Explore the documentation"), ("claim-boundaries", "Know what a result means")] diff --git a/scripts/portal/home.html.in b/scripts/portal/home.html.in index 3b3ab42..458d2c1 100644 --- a/scripts/portal/home.html.in +++ b/scripts/portal/home.html.in @@ -1,15 +1,16 @@ - -
VERIFIER STANDARD · DEVELOPER DOCUMENTATION
+ +
VERIFIER STANDARD · VERSION 2.0.0 CANDIDATE SOURCE

Make computational claims
checkable.

Capture a computation. Bind its artifacts to a precise claim. Give someone else a bounded way to inspect, reproduce, or refute it.

-

Verifier is the Python reference implementation of the Verifier Standard (VSTD), a verification-domain language for portable, bounded, refutable evidence about computational claims.

-
Start with Verifier Explore the Python reference
-
FROM PACKAGE TO FIRST CHECK

A small place to start.

Install from the Python Package Index (PyPI). Run the defensive demo before capturing your own computation.

Follow the receipt walkthrough
Terminal Python 3.10+
python -m pip install verifier-standard=={{release}}
+
Verifier is the Python reference implementation of the Verifier Standard (VSTD), a verification-domain language for portable, bounded, refutable evidence about computational claims. These pages describe unreleased v2.0.0 candidate source; the published 1.5.0 package has a separate archive.

+
Start with v2 source Explore the v2 Python reference
+
FROM V2 SOURCE TO FIRST CHECK

A small place to start.

Use the v2 candidate checkout identified by this site's source coordinate. Install it locally, then run the defensive demo before capturing your own computation.

Follow the receipt walkthrough
Terminal Python 3.10+
# In the v2.0.0 candidate source checkout
+python -m pip install .
 vstd demo
 vstd --help
Distribution: verifier-standard · Import: verifier · Command: vstd

Find your path

Learn → inspect → contribute

Understand the model ↗

Claims, evidence, coordinates, and the limits that give a result its meaning.

CONCEPTS & PRECEDENTS -

Use the package ↗

Generated command-line interface (CLI) and Python application programming interface (API) references, pinned to release {{release}}.

RELEASED REFERENCE +

Inspect v2 source ↗

Generated command-line interface (CLI) and Python application programming interface (API) references for the current candidate checkout.

V2 CANDIDATE REFERENCE

Explore the repository ↗

Trace a command into its implementation, examples, tests, and normative source.

REPOSITORY WALKTHROUGH

Make a contribution ↗

Bring a counterexample, improve a guide, or tighten a declared verification boundary.

CONTRIBUTOR GUIDE

Know what a result means.

A successful check supports its named proposition under its declared conditions. It does not establish every surrounding claim. Missing evidence stays UNKNOWN.

Read the claims and limits →
diff --git a/scripts/portal/portal.js b/scripts/portal/portal.js index 9388d08..0282c73 100644 --- a/scripts/portal/portal.js +++ b/scripts/portal/portal.js @@ -85,7 +85,7 @@ anchor.className = 'search-result'; anchor.href = root + entry.url; const title = document.createElement('strong'); title.textContent = entry.title; - const meta = document.createElement('small'); meta.textContent = (entry.edition === 'release' ? 'Released package' : 'Repository source') + ' · ' + entry.page; + const meta = document.createElement('small'); meta.textContent = (entry.edition === 'release' ? 'Released 1.5.0 archive' : 'v2.0.0 candidate source') + ' · ' + entry.page; const snippet = document.createElement('p'); const at = Math.max(0, entry.text.toLowerCase().indexOf(tokens[0]) - 55); snippet.textContent = (at ? '…' : '') + entry.text.slice(at, at + 170) + (entry.text.length > at + 170 ? '…' : ''); diff --git a/scripts/portal/release-home.html.in b/scripts/portal/release-home.html.in new file mode 100644 index 0000000..3b3ab42 --- /dev/null +++ b/scripts/portal/release-home.html.in @@ -0,0 +1,16 @@ + +
VERIFIER STANDARD · DEVELOPER DOCUMENTATION
+

Make computational claims
checkable.

+

Capture a computation. Bind its artifacts to a precise claim. Give someone else a bounded way to inspect, reproduce, or refute it.

+

Verifier is the Python reference implementation of the Verifier Standard (VSTD), a verification-domain language for portable, bounded, refutable evidence about computational claims.

+
Start with Verifier Explore the Python reference
+
FROM PACKAGE TO FIRST CHECK

A small place to start.

Install from the Python Package Index (PyPI). Run the defensive demo before capturing your own computation.

Follow the receipt walkthrough
Terminal Python 3.10+
python -m pip install verifier-standard=={{release}}
+vstd demo
+vstd --help
Distribution: verifier-standard · Import: verifier · Command: vstd
+

Find your path

Learn → inspect → contribute
+

Understand the model ↗

Claims, evidence, coordinates, and the limits that give a result its meaning.

CONCEPTS & PRECEDENTS +

Use the package ↗

Generated command-line interface (CLI) and Python application programming interface (API) references, pinned to release {{release}}.

RELEASED REFERENCE +

Explore the repository ↗

Trace a command into its implementation, examples, tests, and normative source.

REPOSITORY WALKTHROUGH +

Make a contribution ↗

Bring a counterexample, improve a guide, or tighten a declared verification boundary.

CONTRIBUTOR GUIDE
+

Know what a result means.

A successful check supports its named proposition under its declared conditions. It does not establish every surrounding claim. Missing evidence stays UNKNOWN.

Read the claims and limits →
+
Building with Verifier?

Explore the company and business inquiries at VSTD Labs.

Visit VSTD Labs ↗
diff --git a/tests/test_docs_portal.py b/tests/test_docs_portal.py index 92cbef1..9c0423c 100644 --- a/tests/test_docs_portal.py +++ b/tests/test_docs_portal.py @@ -132,22 +132,33 @@ def test_task_guides_are_navigable_and_do_not_claim_release_coverage(site: Path) assert (site / PORTAL.RELEASE_PATH / route).is_file() groups = dict(PORTAL.navigation("", site)) - assert [target for _, target in groups["Tutorials"]] == [ - "docs/tutorials/SEAL_AN_ARTIFACT.html", - "docs/tutorials/PUBLISH_A_SILO.html", - "docs/PYTHON_API_GUIDE.html", + assert groups["v2.0.0 source reference"][:2] == [ + ("Commands", "reference.html#cli"), + ("Python exports", "reference.html#api"), ] + assert ("Python API guide", "docs/PYTHON_API_GUIDE.html") in groups["v2.0.0 source reference"] assert ("Typical use cases", "docs/USE_CASES.html") in groups["Start here"] + assert groups["Published archive · 1.5.0"][0] == ("Release introduction", PORTAL.RELEASE_PATH + "index.html") candidate = groups["Version 2.0.0 candidate"] assert ("Candidate scope and migration", "docs/V2_CANDIDATE.html") in candidate assert ("Open contradictions", "project/TIME.html") in candidate assert "Version 2.0.0 candidate" not in dict(PORTAL.navigation(PORTAL.RELEASE_PATH, site)) - assert "Version 2.0.0 candidate" in (site / "index.html").read_text(encoding="utf-8") - assert "Version 2.0.0 candidate" not in (site / PORTAL.RELEASE_PATH / "index.html").read_text(encoding="utf-8") + current_home = (site / "index.html").read_text(encoding="utf-8") + release_home = (site / PORTAL.RELEASE_PATH / "index.html").read_text(encoding="utf-8") + assert "v2.0.0 candidate source" in current_home + assert 'href="reference.html#api"' in current_home + assert 'href="releases/1.5.0/reference.html#api"' not in current_home.split('
', 1)[1] + assert 'value="repository" selected' in current_home + assert 'python -m pip install .' in current_home + assert "verifier-standard==1.5.0" not in current_home + assert "Version 2.0.0 candidate" not in release_home + assert 'value="release" selected' in release_home + assert 'verifier-standard==1.5.0' in release_home + assert 'href="../../releases/1.5.0/docs/INSTALLATION.html"' in release_home released = dict(PORTAL.navigation(PORTAL.RELEASE_PATH, site)) - for _, target in released["Tutorials"] + [released["Start here"][-1]]: + for _, target in released["Tutorials"] + released["Start here"][1:]: assert target.startswith(PORTAL.RELEASE_PATH) entries = json.loads((site / "search-index.json").read_text(encoding="utf-8")) diff --git a/tests/test_presentation_surface.py b/tests/test_presentation_surface.py index 9fdcea1..04dc320 100644 --- a/tests/test_presentation_surface.py +++ b/tests/test_presentation_surface.py @@ -464,8 +464,10 @@ def test_pages_artifact_serves_every_canonical_schema_id(tmp_path: Path) -> None } for page in (output / "index.html", output / "guides.html"): text = page.read_text(encoding="utf-8") - assert "released 2026-09-18" in text - assert "unreleased candidate" not in text.lower() + assert "v2.0.0 candidate source" in text + assert "1.5.0" in text + assert text.index("v2.0.0 candidate source") < text.index("1.5.0") + assert "not a published package" in text or "not yet published as a" in text sources = sorted( ( *ROOT.joinpath("receipts/schema").glob("*.json"), From e4661dc5a5ce1e6653cbfa55d468f19e42d03658 Mon Sep 17 00:00:00 2001 From: TimeLordRaps Date: Mon, 28 Sep 2026 02:04:11 -0700 Subject: [PATCH 5/6] docs: complete supported v2 API member reference --- docs/API_MEMBER_SUMMARIES.json | 94 +++++++++++++++ docs/PR_SOURCE_FEATURES.json | 8 +- docs/PYTHON_API_GUIDE.md | 5 +- docs/reference.html | 182 ++++++++++++++++------------- scripts/build_reference.py | 78 +++++++++++-- tests/test_presentation_surface.py | 47 ++++++++ 6 files changed, 314 insertions(+), 100 deletions(-) create mode 100644 docs/API_MEMBER_SUMMARIES.json diff --git a/docs/API_MEMBER_SUMMARIES.json b/docs/API_MEMBER_SUMMARIES.json new file mode 100644 index 0000000..515d23b --- /dev/null +++ b/docs/API_MEMBER_SUMMARIES.json @@ -0,0 +1,94 @@ +{ + "schema_version": 1, + "source_files": { + "src/verifier/artifact_control/__init__.py": { + "ArtifactVerification.sealed": "Report whether this verification result's state is SEALED.", + "ArtifactVerification.to_dict": "Serialize the observed freeze, guard, seal, anchor, errors, and warnings." + }, + "src/verifier/core/certificate.py": { + "DecisionCertificate.digest": "Return the canonical digest of this certificate's serialized fields, including hints.", + "DecisionCertificate.to_dict": "Serialize the certificate header, formula, grounding, decision block, and hints." + }, + "src/verifier/core/certification_mechanisms.py": { + "NativeCertificationMechanism.evaluate": "Check one supported native obligation against retained evidence; unsupported inputs stay UNKNOWN.", + "NativeCertificationMechanism.mechanism_digest": "Return a digest binding the listed native source modules to their current file bytes." + }, + "src/verifier/core/evidence.py": { + "BoundProposition.digest": "Return the canonical digest of this proposition's serialized binding.", + "BoundProposition.from_dict": "Reconstruct a bound proposition and its evidence bounds from a mapping.", + "BoundProposition.to_dict": "Serialize the exact subject, mechanism, evidence, trust roots, bounds, and parameters of this proposition.", + "EvidenceBounds.to_dict": "Serialize the item-count and byte-count ceilings for bound evidence.", + "EvidenceStore.add": "Retain exact payload bytes and return their content reference, rejecting other types or a digest collision.", + "EvidenceStore.resolve": "Return retained bytes only when the reference exists and the bytes still match its digest.", + "VerificationSession.evaluate": "Evaluate a bound proposition against registered mechanism and retained evidence; unmet prerequisites yield UNKNOWN.", + "VerificationSession.register": "Register a mechanism by identifier and digest, refusing substitution under an existing identifier." + }, + "src/verifier/core/geometry.py": { + "VerificationGeometry.canonical_digest": "Return the SHA-256 hex digest of the geometry's sorted compact JSON bytes.", + "VerificationGeometry.to_dict": "Serialize the geometry's declared coordinates and relations as JSON-compatible values." + }, + "src/verifier/core/grounded_certification.py": { + "CertificationPolicy.digest": "Return the canonical digest of this policy's serialized fields.", + "CertificationPolicy.from_dict": "Parse a versioned policy, rejecting unknown coordinates and out-of-range resource bounds.", + "CertificationPolicy.to_dict": "Serialize admitted obligations, resource ceilings, and catalogue and specification digests.", + "CertificationRequest.from_dict": "Parse a versioned request, rejecting unknown or out-of-target obligation coordinates.", + "CertificationRequest.to_dict": "Serialize the requested claim binding, target profile, and bound obligations.", + "MechanismAdmission.from_dict": "Parse a mechanism admission with exact required fields and normalized digest.", + "MechanismAdmission.to_dict": "Serialize the admitted mechanism identifier, normalized digest, and declared trust roots." + }, + "src/verifier/core/platform_comparison.py": { + "PlatformComparisonResult.exit_code": "Map PASS to zero, CONFLICTED or INVALID to one, and other statuses to two.", + "PlatformComparisonResult.to_dict": "Serialize the bounded diagnostic, compared platforms, differences, errors, and claim boundary." + }, + "src/verifier/core/profile_obligations.py": { + "ProfileObligation.id": "Return the numbered profile and index as a dotted obligation identifier.", + "ProfileObligation.predicate": "Return the predicate name, using the VSTD-4 rung form for profile four.", + "ProfileObligation.to_dict": "Serialize this obligation with its dependency list, identifier, and predicate." + }, + "src/verifier/core/receipt.py": { + "VstdReceipt.compute_and_set_digest": "Compute and store the digest of the receipt's stable payload; return that digest.", + "VstdReceipt.save_to_directory": "Write the receipt, claim, file manifest, optional log, and report under the output directory.", + "VstdReceipt.to_dict": "Serialize the receipt and compute its stable-payload digest first when absent.", + "VstdReceipt.verify_digest_integrity": "Compare the stored digest with the stable payload's recomputed digest, without verifying the claim." + }, + "src/verifier/core/witness.py": { + "WitnessBundle.from_dict": "Reconstruct a witness bundle from its witness, independence, and corroboration mappings.", + "WitnessBundle.to_dict": "Serialize the claim binding, witness identities, independence assertions, and corroborations." + }, + "src/verifier/data/assurance.py": { + "AssuranceLedger.current_status": "Return the most degraded recorded status for an artifact, or UNKNOWN when it is absent.", + "AssuranceLedger.events": "Return an immutable snapshot of recorded assurance events.", + "AssuranceLedger.graph_digest": "Return the digest captured for the historical Graph at ledger creation.", + "AssuranceLedger.record_rot": "Evaluate an exact current-status proposition and append a strictly degrading ROT event.", + "AssuranceLedger.record_rust": "Evaluate a descendant deviation and record diagnostic backward reachability, not causal attribution.", + "AssuranceLedger.record_trust": "Check exact transformation inputs, current admissibility, and prerequisites before evaluating and appending a TRUST event.", + "AssuranceLedger.resolutions": "Return an immutable snapshot of recorded conflict resolutions.", + "AssuranceLedger.rust_concentration": "Count distinct passing RUST origins reaching each ancestor; this is diagnostic, not causal strength.", + "AssuranceLedger.to_dict": "Serialize the historical Graph, events, resolutions, and digest of the current view.", + "AssuranceLedger.unresolved_conflicts": "Return conflict records that have no recorded resolution.", + "AssuranceLedger.verify_hash_chain": "Check event order and predecessor digests; this alone does not replay mechanisms or authenticate actors.", + "ObligationCoordinate.digest": "Return the canonical digest of this obligation coordinate's serialized fields.", + "ObligationCoordinate.from_dict": "Reconstruct an obligation coordinate, requiring its scope to be a mapping.", + "ObligationCoordinate.to_dict": "Serialize the obligation identifier, content digest, scope, assumptions, and exclusions." + }, + "src/verifier/data/models.py": { + "ProvenanceHypergraph.add_artifact": "Add an artifact by unique identifier, keeping artifact and transformation identifiers disjoint.", + "ProvenanceHypergraph.add_conflict": "Add a conflict record by unique identifier and return that identifier.", + "ProvenanceHypergraph.add_contributor": "Add a contributor by unique identifier and return that identifier.", + "ProvenanceHypergraph.add_rights": "Add a rights record by unique identifier and return that identifier.", + "ProvenanceHypergraph.add_transformation": "Add a transformation by unique identifier, keeping transformation and artifact identifiers disjoint.", + "ProvenanceHypergraph.compute_completeness": "Compute declared-field coverage and lineage depth; digest presence does not rehash artifact bytes.", + "ProvenanceHypergraph.has_conflict": "Report whether any recorded conflict names this subject; resolution state is not considered.", + "ProvenanceHypergraph.to_dict": "Serialize recorded artifacts, transformations, contributors, rights, and conflicts." + }, + "src/verifier/domains/certification.py": { + "NativeDomainAdapter.evaluate": "Replay one domain obligation against its bound bundle and policy, distinguishing unavailable from refuted evidence." + }, + "src/verifier/interoperability/control_surface.py": { + "ControlSurfaceContext.to_dict": "Serialize interaction mode, domain tags, operating regime, consequences, and authority requirements.", + "SurfaceAnalysis.canonical_json_bytes": "Return canonical JSON bytes for this surface analysis's serialized fields.", + "SurfaceAnalysis.to_dict": "Serialize the geometry assessment, validity errors, closure blockers, holes, and claim boundary.", + "SurfaceHole.to_dict": "Serialize a detected hole with its native state, blocking effects, and required relations." + } + } +} diff --git a/docs/PR_SOURCE_FEATURES.json b/docs/PR_SOURCE_FEATURES.json index 8e4f874..0642984 100644 --- a/docs/PR_SOURCE_FEATURES.json +++ b/docs/PR_SOURCE_FEATURES.json @@ -131,14 +131,16 @@ }, { "path": "scripts/build_reference.py", - "sha256": "a8dd6a8b1fa74c1e9d2cc5428e55725dcc73cad2525684ff1944a0cc850823ad", + "sha256": "7c5592ece3251525571190931f255b4b272c71abb94612225db6057544ecdd7c", "symbols": [ "_api_section", "_cli_section", + "_member_source", + "_member_summaries", "render" ], - "summary": "Generates command and argument inventory from the parser and supported Python exports from verifier.__all__; import-checks a selected pipeline map and marks missing method docstrings.", - "limits": "The selected map and source summaries are descriptions, not behavior proofs. Experimental direct submodules and methods lacking docstrings remain outside full descriptive coverage." + "summary": "Generates parser-based command inventory and the supported Python export reference, including public class members; binds undocumented members to reviewed summaries keyed by their source file and fails on missing or stale summaries.", + "limits": "The selected pipeline map, source docstrings, and reviewed summaries describe declared behavior rather than proving it. Experimental direct submodule imports remain outside the supported top-level reference." }, { "path": "scripts/build_silo_composition_fixture.py", diff --git a/docs/PYTHON_API_GUIDE.md b/docs/PYTHON_API_GUIDE.md index be20437..203cb4d 100644 --- a/docs/PYTHON_API_GUIDE.md +++ b/docs/PYTHON_API_GUIDE.md @@ -11,7 +11,10 @@ build time. For what is promised to stay stable, read At this unreleased 2.0.0 source coordinate, the Verifier Standard (VSTD) supported Python surface is exactly `verifier.__all__` — 69 names. The generated reference -also lists commands from the live CLI parser. Direct imports from experimental +also lists public instance methods, class methods, and properties of exported classes, +plus commands from the live CLI parser. Member descriptions come from source docstrings +or the reviewed [member summary map](API_MEMBER_SUMMARIES.json); the map does not alter +runtime source bytes or establish correctness. Direct imports from experimental submodules are outside this supported top-level boundary. The base package has no required third-party dependencies; seal creation and verification need the optional `seal` extra. diff --git a/docs/reference.html b/docs/reference.html index 9b8ddb0..3a3672b 100644 --- a/docs/reference.html +++ b/docs/reference.html @@ -44,11 +44,11 @@

Inspect the supported surface.

The command and argument inventory comes from the parser; the Python export inventory and signatures come from verifier.__all__ at build time. The pipeline map selects import-checked implementation targets. Summaries come from - source docstrings or the map's reviewed prose. Presentation tests detect generated + source docstrings or the reviewed public-member summary map. Presentation tests detect generated page drift from these sources; they do not prove the described behaviour correct.

This page states the declared public surface of one implementation. It - does not cover experimental direct submodule imports. A method marked "No method - docstring is declared" has a signature here but no descriptive contract. The page + does not cover experimental direct submodule imports. Public instance methods, + class methods, and properties of exported classes are listed here. The page does not establish that an individual claim checked by these commands is true, nor that an external implementation exists.

@@ -880,7 +880,8 @@

ArtifactVerification class

Result of independently recomputing a frozen artifact and its seals.

Defined in verifier.artifact_control

- + +
MethodSummary
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
sealed (property)Report whether this verification result's state is SEALED.
to_dict(self) -> 'dict[str, Any]'Serialize the observed freeze, guard, seal, anchor, errors, and warnings.
@@ -889,32 +890,33 @@

AssuranceLedger class

Append-only current-state overlay for an immutable provenance graph.

Defined in verifier.data.assurance

- - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodSummary
admissibility_blocking_conflicts(self) -> 'tuple[ConflictRecord, ...]'Return conflicts whose effect still blocks a clean TRUST route.
compose_guilt(self, ancestor_id: 'str', descendant_id: 'str', obligation: 'ObligationCoordinate', proposition: 'BoundProposition', *, localization_event_digest: 'str', responsibility_component_digest: 'str', applicability_component_digest: 'str', violation_component_digest: 'str', session: 'VerificationSession', recorded_at: 'str') -> 'DiagnosticAttribution'Compose technical GUILT from three exact, separately earned components.
current_status(self, artifact_id: 'str') -> 'ArtifactStatus'No method docstring is declared.
current_transformation_status(self, transformation_id: 'str') -> 'str'Return a transformation's additive current status projection.
current_trust_events(self) -> 'tuple[AssuranceEvent, ...]'Return recursively current edge-local TRUST records.
diagnose(self, kind: 'DiagnosticKind', ancestor_id: 'str', descendant_id: 'str', proposition: 'Optional[BoundProposition]', *, session: 'VerificationSession', recorded_at: 'str') -> 'DiagnosticAttribution'Compute BLAME, or fail closed for legacy opaque GUILT calls.
establish_guilt_components(self, ancestor_id: 'str', descendant_id: 'str', obligation: 'ObligationCoordinate', responsibility_proposition: 'BoundProposition', applicability_proposition: 'BoundProposition', violation_proposition: 'BoundProposition', *, localization_event_digest: 'str', session: 'VerificationSession', recorded_at: 'str') -> 'tuple[AssuranceEvent, AssuranceEvent, AssuranceEvent]'Run one compound mechanism and retain three separately bound results.
establish_obligation_applicability(self, artifact_id: 'str', obligation: 'ObligationCoordinate', proposition: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Evaluate whether one exact obligation applies to one exact artifact.
establish_obligation_violation(self, ancestor_id: 'str', descendant_id: 'str', obligation: 'ObligationCoordinate', proposition: 'BoundProposition', *, localization_event_digest: 'str', applicability_component_digest: 'str', session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Evaluate violation after exact applicability and deviation localization.
establish_responsibility(self, ancestor_id: 'str', descendant_id: 'str', proposition: 'BoundProposition', *, localization_event_digest: 'str', session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Evaluate one separately bound material-contribution component.
events(self) -> 'tuple[AssuranceEvent, ...]'No method docstring is declared.
impacted_descendants(self, artifact_id: 'str') -> 'tuple[str, ...]'Return the deduplicated recorded forward impact set, not a verdict.
localize_cause(self, ancestor_id: 'str', descendant_id: 'str', proposition: 'BoundProposition', *, rust_event_digest: 'str', session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Bind one ancestor to one exact passing descendant-deviation event.
materialize_current_graph(self) -> 'ProvenanceHypergraph'Create a derived current view; never mutate the historical graph.
project_challenges(self, challenges: 'ChallengeLedger', *, recorded_at: 'str') -> 'tuple[AssuranceEvent, ...]'Project challenge state into an additive current Graph overlay.
record_conflict(self, conflict: 'ConflictRecord', proposition: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Add mechanism-established current conflict evidence without rewriting Graph.
record_rot(self, artifact_id: 'str', resulting_status: 'ArtifactStatus', proposition: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'No method docstring is declared.
record_rust(self, descendant_id: 'str', deviation: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'No method docstring is declared.
record_status_projection(self, artifact_id: 'str', proposition: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Record a mechanism-checked current-status projection additively.
record_trust(self, target_id: 'str', source_ids: 'Iterable[str]', proposition: 'BoundProposition', *, transformation_id: 'str', prerequisite_trust_event_digests: 'Iterable[str]' = (), session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'No method docstring is declared.
resolutions(self) -> 'tuple[ConflictResolution, ...]'No method docstring is declared.
resolve_conflict(self, conflict_id: 'str', selected_value: 'str', proposition: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'ConflictResolution'Adjudicate one value without equating selection with admissibility.
rust_concentration(self) -> 'tuple[StructuralConcentration, ...]'No method docstring is declared.
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
unresolved_conflicts(self) -> 'tuple[ConflictRecord, ...]'No method docstring is declared.
verify_hash_chain(self) -> 'bool'No method docstring is declared.
admissibility_blocking_conflicts(self) -> 'tuple[ConflictRecord, ...]'Return conflicts whose effect still blocks a clean TRUST route.
compose_guilt(self, ancestor_id: 'str', descendant_id: 'str', obligation: 'ObligationCoordinate', proposition: 'BoundProposition', *, localization_event_digest: 'str', responsibility_component_digest: 'str', applicability_component_digest: 'str', violation_component_digest: 'str', session: 'VerificationSession', recorded_at: 'str') -> 'DiagnosticAttribution'Compose technical GUILT from three exact, separately earned components.
current_status(self, artifact_id: 'str') -> 'ArtifactStatus'Return the most degraded recorded status for an artifact, or UNKNOWN when it is absent.
current_transformation_status(self, transformation_id: 'str') -> 'str'Return a transformation's additive current status projection.
current_trust_events(self) -> 'tuple[AssuranceEvent, ...]'Return recursively current edge-local TRUST records.
diagnose(self, kind: 'DiagnosticKind', ancestor_id: 'str', descendant_id: 'str', proposition: 'Optional[BoundProposition]', *, session: 'VerificationSession', recorded_at: 'str') -> 'DiagnosticAttribution'Compute BLAME, or fail closed for legacy opaque GUILT calls.
establish_guilt_components(self, ancestor_id: 'str', descendant_id: 'str', obligation: 'ObligationCoordinate', responsibility_proposition: 'BoundProposition', applicability_proposition: 'BoundProposition', violation_proposition: 'BoundProposition', *, localization_event_digest: 'str', session: 'VerificationSession', recorded_at: 'str') -> 'tuple[AssuranceEvent, AssuranceEvent, AssuranceEvent]'Run one compound mechanism and retain three separately bound results.
establish_obligation_applicability(self, artifact_id: 'str', obligation: 'ObligationCoordinate', proposition: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Evaluate whether one exact obligation applies to one exact artifact.
establish_obligation_violation(self, ancestor_id: 'str', descendant_id: 'str', obligation: 'ObligationCoordinate', proposition: 'BoundProposition', *, localization_event_digest: 'str', applicability_component_digest: 'str', session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Evaluate violation after exact applicability and deviation localization.
establish_responsibility(self, ancestor_id: 'str', descendant_id: 'str', proposition: 'BoundProposition', *, localization_event_digest: 'str', session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Evaluate one separately bound material-contribution component.
events(self) -> 'tuple[AssuranceEvent, ...]'Return an immutable snapshot of recorded assurance events.
graph_digest (property)Return the digest captured for the historical Graph at ledger creation.
impacted_descendants(self, artifact_id: 'str') -> 'tuple[str, ...]'Return the deduplicated recorded forward impact set, not a verdict.
localize_cause(self, ancestor_id: 'str', descendant_id: 'str', proposition: 'BoundProposition', *, rust_event_digest: 'str', session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Bind one ancestor to one exact passing descendant-deviation event.
materialize_current_graph(self) -> 'ProvenanceHypergraph'Create a derived current view; never mutate the historical graph.
project_challenges(self, challenges: 'ChallengeLedger', *, recorded_at: 'str') -> 'tuple[AssuranceEvent, ...]'Project challenge state into an additive current Graph overlay.
record_conflict(self, conflict: 'ConflictRecord', proposition: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Add mechanism-established current conflict evidence without rewriting Graph.
record_rot(self, artifact_id: 'str', resulting_status: 'ArtifactStatus', proposition: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Evaluate an exact current-status proposition and append a strictly degrading ROT event.
record_rust(self, descendant_id: 'str', deviation: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Evaluate a descendant deviation and record diagnostic backward reachability, not causal attribution.
record_status_projection(self, artifact_id: 'str', proposition: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Record a mechanism-checked current-status projection additively.
record_trust(self, target_id: 'str', source_ids: 'Iterable[str]', proposition: 'BoundProposition', *, transformation_id: 'str', prerequisite_trust_event_digests: 'Iterable[str]' = (), session: 'VerificationSession', recorded_at: 'str') -> 'AssuranceEvent'Check exact transformation inputs, current admissibility, and prerequisites before evaluating and appending a TRUST event.
resolutions(self) -> 'tuple[ConflictResolution, ...]'Return an immutable snapshot of recorded conflict resolutions.
resolve_conflict(self, conflict_id: 'str', selected_value: 'str', proposition: 'BoundProposition', *, session: 'VerificationSession', recorded_at: 'str') -> 'ConflictResolution'Adjudicate one value without equating selection with admissibility.
rust_concentration(self) -> 'tuple[StructuralConcentration, ...]'Count distinct passing RUST origins reaching each ancestor; this is diagnostic, not causal strength.
to_dict(self) -> 'dict[str, Any]'Serialize the historical Graph, events, resolutions, and digest of the current view.
unresolved_conflicts(self) -> 'tuple[ConflictRecord, ...]'Return conflict records that have no recorded resolution.
verify_hash_chain(self) -> 'bool'Check event order and predecessor digests; this alone does not replay mechanisms or authenticate actors.
@@ -923,8 +925,9 @@

BoundProposition class

Exact proposition, evidence, mechanism, trust-root, and bound binding.

Defined in verifier.core.evidence

- - + + +
MethodSummary
digest(self) -> 'str'No method docstring is declared.
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
digest(self) -> 'str'Return the canonical digest of this proposition's serialized binding.
from_dict(data: 'Mapping[str, Any]') -> "'BoundProposition'"Reconstruct a bound proposition and its evidence bounds from a mapping.
to_dict(self) -> 'dict[str, Any]'Serialize the exact subject, mechanism, evidence, trust roots, bounds, and parameters of this proposition.
@@ -940,8 +943,9 @@

CertificationPolicy class

External mechanism admission and resource policy, not certificate authority.

Defined in verifier.core.grounded_certification

- - + + +
MethodSummary
digest(self) -> 'str'No method docstring is declared.
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
digest(self) -> 'str'Return the canonical digest of this policy's serialized fields.
from_dict(value: 'Any') -> 'CertificationPolicy'Parse a versioned policy, rejecting unknown coordinates and out-of-range resource bounds.
to_dict(self) -> 'dict[str, Any]'Serialize admitted obligations, resource ceilings, and catalogue and specification digests.
@@ -950,7 +954,8 @@

CertificationRequest class

Exact claim and individual evidence propositions; no supplied outcomes.

Defined in verifier.core.grounded_certification

- + +
MethodSummary
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
from_dict(value: 'Any') -> 'CertificationRequest'Parse a versioned request, rejecting unknown or out-of-target obligation coordinates.
to_dict(self) -> 'dict[str, Any]'Serialize the requested claim binding, target profile, and bound obligations.
@@ -959,7 +964,7 @@

ControlSurfaceContext class

External planning context; only schema and interaction mode affect matches.

Defined in verifier.interoperability.control_surface

- +
MethodSummary
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
to_dict(self) -> 'dict[str, Any]'Serialize interaction mode, domain tags, operating regime, consequences, and authority requirements.
@@ -968,9 +973,9 @@

DecisionCertificate class

Canonical grounded decision certificate (GDC) blocks for the bounded checker.

Defined in verifier.core.certificate

- - - + + +
MethodSummary
digest(self) -> 'str'No method docstring is declared.
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
without_hints(self) -> "'DecisionCertificate'"Hint-stripped form.
digest(self) -> 'str'Return the canonical digest of this certificate's serialized fields, including hints.
to_dict(self) -> 'dict[str, Any]'Serialize the certificate header, formula, grounding, decision block, and hints.
without_hints(self) -> "'DecisionCertificate'"Hint-stripped form.
@@ -986,7 +991,7 @@

EvidenceBounds class

Resource ceilings enforced before invoking a domain mechanism.

Defined in verifier.core.evidence

- +
MethodSummary
to_dict(self) -> 'dict[str, int]'No method docstring is declared.
to_dict(self) -> 'dict[str, int]'Serialize the item-count and byte-count ceilings for bound evidence.
@@ -995,10 +1000,10 @@

EvidenceStore class

In-memory content-addressed evidence store with collision/fork refusal.

Defined in verifier.core.evidence

- - - - + + + +
MethodSummary
add(self, payload: 'bytes') -> 'str'No method docstring is declared.
export_base64(self, references: 'Sequence[str]') -> 'dict[str, str]'Export exact evidence bytes for portable, offline mechanism replay.
import_base64(self, payloads: 'Mapping[str, str]') -> 'None'Import a portable bundle and refuse every reference/byte mismatch.
resolve(self, reference: 'str') -> 'bytes'No method docstring is declared.
add(self, payload: 'bytes') -> 'str'Retain exact payload bytes and return their content reference, rejecting other types or a digest collision.
export_base64(self, references: 'Sequence[str]') -> 'dict[str, str]'Export exact evidence bytes for portable, offline mechanism replay.
import_base64(self, payloads: 'Mapping[str, str]') -> 'None'Import a portable bundle and refuse every reference/byte mismatch.
resolve(self, reference: 'str') -> 'bytes'Return retained bytes only when the reference exists and the bytes still match its digest.
@@ -1020,7 +1025,8 @@

MechanismAdmission class

Checker-selected executable and trust roots for one exact obligation.

Defined in verifier.core.grounded_certification

- + +
MethodSummary
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
from_dict(value: 'Any') -> 'MechanismAdmission'Parse a mechanism admission with exact required fields and normalized digest.
to_dict(self) -> 'dict[str, Any]'Serialize the admitted mechanism identifier, normalized digest, and declared trust roots.
@@ -1042,7 +1048,8 @@

NativeCertificationMechanism class

Execute bounded claim-record, geometry and decision-certificate checks.

Defined in verifier.core.certification_mechanisms

- + +
MethodSummary
evaluate(self, binding: 'BoundProposition', evidence: 'Sequence[bytes]') -> 'MechanismDecision'No method docstring is declared.
evaluate(self, binding: 'BoundProposition', evidence: 'Sequence[bytes]') -> 'MechanismDecision'Check one supported native obligation against retained evidence; unsupported inputs stay UNKNOWN.
mechanism_digest (property)Return a digest binding the listed native source modules to their current file bytes.

@@ -1051,7 +1058,7 @@

NativeDomainAdapter class

Executable mechanism for one domain; registration supplies no implicit authority.

Defined in verifier.domains.certification

- +
MethodSummary
evaluate(self, binding: 'BoundProposition', evidence: 'Sequence[bytes]') -> 'MechanismDecision'No method docstring is declared.
evaluate(self, binding: 'BoundProposition', evidence: 'Sequence[bytes]') -> 'MechanismDecision'Replay one domain obligation against its bound bundle and policy, distinguishing unavailable from refuted evidence.
@@ -1060,8 +1067,9 @@

ObligationCoordinate class

Exact technical obligation and the declared scope in which it applies.

Defined in verifier.data.assurance

- - + + +
MethodSummary
digest(self) -> 'str'No method docstring is declared.
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
digest(self) -> 'str'Return the canonical digest of this obligation coordinate's serialized fields.
from_dict(data: 'Mapping[str, Any]') -> "'ObligationCoordinate'"Reconstruct an obligation coordinate, requiring its scope to be a mapping.
to_dict(self) -> 'dict[str, Any]'Serialize the obligation identifier, content digest, scope, assumptions, and exclusions.
@@ -1070,7 +1078,8 @@

PlatformComparisonResult class

Machine-readable diagnostic result; this object is not a VSTD receipt.

Defined in verifier.core.platform_comparison

- + +
MethodSummary
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
exit_code (property)Map PASS to zero, CONFLICTED or INVALID to one, and other statuses to two.
to_dict(self) -> 'dict[str, Any]'Serialize the bounded diagnostic, compared platforms, differences, errors, and claim boundary.
@@ -1085,7 +1094,9 @@

ProfileObligation class

A separately checked proposition with explicit prerequisite obligations.

Defined in verifier.core.profile_obligations

- + + +
MethodSummary
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
id (property)Return the numbered profile and index as a dotted obligation identifier.
predicate (property)Return the predicate name, using the VSTD-4 rung form for profile four.
to_dict(self) -> 'dict[str, Any]'Serialize this obligation with its dependency list, identifier, and predicate.
@@ -1094,22 +1105,23 @@

ProvenanceHypergraph class

N-ary Hypergraph structure for dataset, training, and artifact lineage.

Defined in verifier.data.models

- - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + +
MethodSummary
add_artifact(self, artifact: 'ArtifactNode') -> 'str'No method docstring is declared.
add_conflict(self, conflict: 'ConflictRecord') -> 'str'No method docstring is declared.
add_contributor(self, contributor: 'ContributorSpec') -> 'str'No method docstring is declared.
add_rights(self, rights: 'RightsSpec') -> 'str'No method docstring is declared.
add_transformation(self, transform: 'TransformationHyperedge') -> 'str'No method docstring is declared.
ancestors(self, artifact_ids: 'Iterable[str]') -> 'set[str]'Backward reachability closure across transformation hyperedges.
blast_radius(self, revoked_artifact_id: 'str') -> 'list[str]'Compute the forward blast radius of affected downstream artifacts when one node is revoked.
compute_completeness(self) -> 'CompletenessMetrics'No method docstring is declared.
descendants(self, artifact_ids: 'Iterable[str]') -> 'set[str]'Forward reachability closure across transformation hyperedges.
has_conflict(self, subject_id: 'str') -> 'bool'No method docstring is declared.
incoming_hyperedges(self, artifact_id: 'str') -> 'list[TransformationHyperedge]'Hyperedges that produce artifact_id as an output.
outgoing_hyperedges(self, artifact_id: 'str') -> 'list[TransformationHyperedge]'Hyperedges that consume artifact_id as an input.
root_sources(self) -> 'set[str]'Artifacts with zero incoming hyperedges (genesis roots).
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
validate_structure(self, *, allow_legacy_identifier_overlap: 'bool' = False) -> 'list[str]'Return deterministic errors for the implemented graph surface.
verify_acyclicity(self, artifact_ids: 'Optional[Iterable[str]]' = None) -> 'bool'Check whether all or a selected artifact-induced subgraph contains cycles.
add_artifact(self, artifact: 'ArtifactNode') -> 'str'Add an artifact by unique identifier, keeping artifact and transformation identifiers disjoint.
add_conflict(self, conflict: 'ConflictRecord') -> 'str'Add a conflict record by unique identifier and return that identifier.
add_contributor(self, contributor: 'ContributorSpec') -> 'str'Add a contributor by unique identifier and return that identifier.
add_rights(self, rights: 'RightsSpec') -> 'str'Add a rights record by unique identifier and return that identifier.
add_transformation(self, transform: 'TransformationHyperedge') -> 'str'Add a transformation by unique identifier, keeping transformation and artifact identifiers disjoint.
ancestors(self, artifact_ids: 'Iterable[str]') -> 'set[str]'Backward reachability closure across transformation hyperedges.
blast_radius(self, revoked_artifact_id: 'str') -> 'list[str]'Compute the forward blast radius of affected downstream artifacts when one node is revoked.
compute_completeness(self) -> 'CompletenessMetrics'Compute declared-field coverage and lineage depth; digest presence does not rehash artifact bytes.
descendants(self, artifact_ids: 'Iterable[str]') -> 'set[str]'Forward reachability closure across transformation hyperedges.
from_dict(data: 'Mapping[str, Any]', *, allow_legacy_identifier_overlap: 'bool' = True) -> "'ProvenanceHypergraph'"Decode stored Graph bytes without rewriting their identifier semantics.
has_conflict(self, subject_id: 'str') -> 'bool'Report whether any recorded conflict names this subject; resolution state is not considered.
incoming_hyperedges(self, artifact_id: 'str') -> 'list[TransformationHyperedge]'Hyperedges that produce artifact_id as an output.
outgoing_hyperedges(self, artifact_id: 'str') -> 'list[TransformationHyperedge]'Hyperedges that consume artifact_id as an input.
root_sources(self) -> 'set[str]'Artifacts with zero incoming hyperedges (genesis roots).
to_dict(self) -> 'dict[str, Any]'Serialize recorded artifacts, transformations, contributors, rights, and conflicts.
validate_structure(self, *, allow_legacy_identifier_overlap: 'bool' = False) -> 'list[str]'Return deterministic errors for the implemented graph surface.
verify_acyclicity(self, artifact_ids: 'Optional[Iterable[str]]' = None) -> 'bool'Check whether all or a selected artifact-induced subgraph contains cycles.
@@ -1124,8 +1136,8 @@

SurfaceAnalysis class

Deterministic report over only the supplied, declared geometry.

Defined in verifier.interoperability.control_surface

- - + +
MethodSummary
canonical_json_bytes(self) -> 'bytes'No method docstring is declared.
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
canonical_json_bytes(self) -> 'bytes'Return canonical JSON bytes for this surface analysis's serialized fields.
to_dict(self) -> 'dict[str, Any]'Serialize the geometry assessment, validity errors, closure blockers, holes, and claim boundary.
@@ -1141,7 +1153,8 @@

SurfaceHole class

One structured diagnostic derived from an existing geometry blocker.

Defined in verifier.interoperability.control_surface

- + +
MethodSummary
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
native_state (property)Compatibility spelling for callers that describe statuses as states.
to_dict(self) -> 'dict[str, Any]'Serialize a detected hole with its native state, blocking effects, and required relations.
@@ -1156,10 +1169,10 @@

VerificationGeometry class

A finite verification geometry and its higher-order audit surface.

Defined in verifier.core.geometry

- - - - + + + +
MethodSummary
assess_closure(self) -> 'ClosureAssessment'Assess declared closure and higher-order self-closure separately.
canonical_digest(self) -> 'str'No method docstring is declared.
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
validate(self) -> 'list[str]'Return structural and epistemic errors; an empty list means valid.
assess_closure(self) -> 'ClosureAssessment'Assess declared closure and higher-order self-closure separately.
canonical_digest(self) -> 'str'Return the SHA-256 hex digest of the geometry's sorted compact JSON bytes.
to_dict(self) -> 'dict[str, Any]'Serialize the geometry's declared coordinates and relations as JSON-compatible values.
validate(self) -> 'list[str]'Return structural and epistemic errors; an empty list means valid.
@@ -1168,10 +1181,10 @@

VerificationSession class

Resolve evidence and rerun only explicitly registered mechanisms.

Defined in verifier.core.evidence

- - - - + + + +
MethodSummary
evaluate(self, binding: 'BoundProposition') -> 'EvaluatedProposition'No method docstring is declared.
evaluate_compound(self, bindings: 'Sequence[BoundProposition]') -> 'tuple[EvaluatedProposition, ...]'Run one compound mechanism invocation over separately bound propositions.
register(self, mechanism: 'VerificationMechanism') -> 'None'No method docstring is declared.
registered_mechanisms(self) -> 'tuple[VerificationMechanism, ...]'Snapshot caller-registered capabilities for an isolated evidence replay.
evaluate(self, binding: 'BoundProposition') -> 'EvaluatedProposition'Evaluate a bound proposition against registered mechanism and retained evidence; unmet prerequisites yield UNKNOWN.
evaluate_compound(self, bindings: 'Sequence[BoundProposition]') -> 'tuple[EvaluatedProposition, ...]'Run one compound mechanism invocation over separately bound propositions.
register(self, mechanism: 'VerificationMechanism') -> 'None'Register a mechanism by identifier and digest, refusing substitution under an existing identifier.
registered_mechanisms(self) -> 'tuple[VerificationMechanism, ...]'Snapshot caller-registered capabilities for an isolated evidence replay.
@@ -1186,11 +1199,11 @@

VstdReceipt class

Mutable in-memory model of a canonically digested VSTD-1 claim receipt.

Defined in verifier.core.receipt

- - - - - + + + + +
MethodSummary
compute_and_set_digest(self) -> 'str'No method docstring is declared.
get_stable_payload(self) -> 'dict[str, Any]'Extract only deterministic, location-independent fields for canonical hashing.
save_to_directory(self, out_dir: 'Path') -> 'Path'No method docstring is declared.
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
verify_digest_integrity(self) -> 'bool'No method docstring is declared.
compute_and_set_digest(self) -> 'str'Compute and store the digest of the receipt's stable payload; return that digest.
get_stable_payload(self) -> 'dict[str, Any]'Extract only deterministic, location-independent fields for canonical hashing.
save_to_directory(self, out_dir: 'Path') -> 'Path'Write the receipt, claim, file manifest, optional log, and report under the output directory.
to_dict(self) -> 'dict[str, Any]'Serialize the receipt and compute its stable-payload digest first when absent.
verify_digest_integrity(self) -> 'bool'Compare the stored digest with the stable payload's recomputed digest, without verifying the claim.
@@ -1199,7 +1212,8 @@

WitnessBundle class

Claim-bound identities, ordered separation assertions, and corroborations.

Defined in verifier.core.witness

- + +
MethodSummary
to_dict(self) -> 'dict[str, Any]'No method docstring is declared.
from_dict(data: 'Mapping[str, Any]') -> "'WitnessBundle'"Reconstruct a witness bundle from its witness, independence, and corroboration mappings.
to_dict(self) -> 'dict[str, Any]'Serialize the claim binding, witness identities, independence assertions, and corroborations.
diff --git a/scripts/build_reference.py b/scripts/build_reference.py index c1229a6..f0c167a 100644 --- a/scripts/build_reference.py +++ b/scripts/build_reference.py @@ -9,7 +9,8 @@ CLI names and options come from the argument parser; top-level Python names and signatures come from the importable package. The pipeline map is a selected, manually described set of import-checked dispatch targets, and summaries come -from source docstrings. `scripts/check_presentation.py` and +from source docstrings or a reviewed map of undocumented public members. +`scripts/check_presentation.py` and `tests/test_presentation_surface.py` regenerate this file and fail closed when the committed page drifts from the code.""" @@ -20,6 +21,7 @@ import html import importlib import inspect +import json import os from pathlib import Path import re @@ -32,6 +34,7 @@ if str(SOURCE_ROOT) not in sys.path: sys.path.insert(0, str(SOURCE_ROOT)) OUTPUT = ROOT / "docs/reference.html" +MEMBER_SUMMARIES = ROOT / "docs/API_MEMBER_SUMMARIES.json" SOURCE_BASE = "https://github.com/TimeLordRaps/verifier/blob/main/" # command -> the declared implementation stages it dispatches into. Every target is @@ -229,6 +232,38 @@ def _summary(obj: object) -> str: return doc.split("\n\n", 1)[0].strip().replace("\n", " ") +def _member_summaries() -> dict[tuple[str, str], str]: + try: + payload = json.loads(MEMBER_SUMMARIES.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError) as exc: + raise ReferenceBuildError(f"cannot load reviewed member summaries: {exc}") from exc + if not isinstance(payload, dict) or set(payload) != {"schema_version", "source_files"}: + raise ReferenceBuildError("member summary map has unexpected top-level fields") + if payload["schema_version"] != 1 or not isinstance(payload["source_files"], dict): + raise ReferenceBuildError("member summary map has an unsupported schema") + summaries: dict[tuple[str, str], str] = {} + for source, members in payload["source_files"].items(): + if (not isinstance(source, str) or not source.startswith("src/verifier/") + or not (ROOT / source).is_file() or not isinstance(members, dict)): + raise ReferenceBuildError(f"invalid member summary source: {source!r}") + for name, summary in members.items(): + if not isinstance(name, str) or not isinstance(summary, str) or not summary.strip(): + raise ReferenceBuildError(f"invalid member summary: {source}:{name}") + summaries[(source, name)] = summary.strip() + return summaries + + +def _member_source(member: object) -> str: + target = member.fget if isinstance(member, property) else member + source = inspect.getsourcefile(target) + if source is None: + raise ReferenceBuildError(f"cannot locate source for public member {member!r}") + try: + return Path(source).resolve().relative_to(ROOT).as_posix() + except ValueError as exc: + raise ReferenceBuildError(f"public member source is outside repository: {source}") from exc + + def _esc(text: str) -> str: return html.escape(text, quote=False) @@ -329,6 +364,8 @@ def _cli_section() -> str: def _api_section() -> str: package = importlib.import_module("verifier") blocks: list[str] = [] + member_summaries = _member_summaries() + used_summaries: set[tuple[str, str]] = set() for name in sorted(package.__all__): value = getattr(package, name) module_name = value.__module__ @@ -350,17 +387,31 @@ def _api_section() -> str: members = f'

Members: {_esc(values)}

' elif kind == "class": rows = "" - for member_name, member in sorted(inspect.getmembers(value, inspect.isfunction)): + for member_name, member in inspect.getmembers(value): if member_name.startswith("_"): continue - try: - member_signature = f"{member_name}{inspect.signature(member)}" - except (TypeError, ValueError): - member_signature = member_name - method_summary = _summary(member) or "No method docstring is declared." + if isinstance(member, property): + member_signature = f"{member_name} (property)" + elif inspect.isfunction(member) or inspect.ismethod(member): + try: + member_signature = f"{member_name}{inspect.signature(member)}" + except (TypeError, ValueError): + member_signature = member_name + else: + continue + member_summary = _summary(member) + if not member_summary: + key = (_member_source(member), f"{name}.{member_name}") + member_summary = member_summaries.get(key, "") + if not member_summary: + raise ReferenceBuildError( + f"public member has no reviewed summary: {key[0]}:{key[1]}" + ) + used_summaries.add(key) rows += ( - f"{_esc(member_signature)}" - f"{_esc(method_summary)}\n" + f'' + f"{_esc(member_signature)}" + f"{_esc(member_summary)}\n" ) if rows: members = ( @@ -395,6 +446,9 @@ def _api_section() -> str: f"{_esc(module_name)}

\n" f"{members}\n
" ) + stale = set(member_summaries) - used_summaries + if stale: + raise ReferenceBuildError(f"unused member summaries: {sorted(stale)}") return "\n".join(blocks) @@ -488,11 +542,11 @@ def render() -> str:

The command and argument inventory comes from the parser; the Python export inventory and signatures come from verifier.__all__ at build time. The pipeline map selects import-checked implementation targets. Summaries come from - source docstrings or the map's reviewed prose. Presentation tests detect generated + source docstrings or the reviewed public-member summary map. Presentation tests detect generated page drift from these sources; they do not prove the described behaviour correct.

This page states the declared public surface of one implementation. It - does not cover experimental direct submodule imports. A method marked "No method - docstring is declared" has a signature here but no descriptive contract. The page + does not cover experimental direct submodule imports. Public instance methods, + class methods, and properties of exported classes are listed here. The page does not establish that an individual claim checked by these commands is true, nor that an external implementation exists.

diff --git a/tests/test_presentation_surface.py b/tests/test_presentation_surface.py index 04dc320..0c430d5 100644 --- a/tests/test_presentation_surface.py +++ b/tests/test_presentation_surface.py @@ -8,7 +8,9 @@ from __future__ import annotations +import enum from html.parser import HTMLParser +import inspect import importlib.util import json from pathlib import Path @@ -996,6 +998,51 @@ def test_generated_reference_covers_commands_and_top_level_exports() -> None: assert "Monotone reproduction-fidelity states" in page +def test_generated_reference_explains_every_public_class_member() -> None: + """A public class member needs a reachable entry and a source-grounded summary.""" + import verifier + + page = (ROOT / "docs/reference.html").read_text(encoding="utf-8") + missing = [] + for export_name in verifier.__all__: + value = getattr(verifier, export_name) + if not inspect.isclass(value) or issubclass(value, enum.Enum): + continue + for member_name, member in inspect.getmembers(value): + if member_name.startswith("_"): + continue + if not (inspect.isfunction(member) or inspect.ismethod(member) + or isinstance(member, property)): + continue + anchor = f'id="api-{export_name}.{member_name}"' + if anchor not in page: + missing.append(f"{export_name}.{member_name}") + assert not missing, f"reference omits public class members: {missing}" + assert "No method docstring is declared." not in page + assert "No public member docstring is declared." not in page + + +def test_generated_reference_rejects_stale_member_summary( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, +) -> None: + """A summary detached from the public source surface must fail the build.""" + path = ROOT / "scripts/build_reference.py" + spec = importlib.util.spec_from_file_location("build_reference_stale_map", path) + assert spec is not None and spec.loader is not None + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + + summaries = json.loads((ROOT / "docs/API_MEMBER_SUMMARIES.json").read_text(encoding="utf-8")) + source = "src/verifier/core/evidence.py" + summaries["source_files"][source]["EvidenceStore.not_a_public_method"] = "Stale description." + candidate = tmp_path / "member_summaries.json" + candidate.write_text(json.dumps(summaries), encoding="utf-8") + monkeypatch.setattr(module, "MEMBER_SUMMARIES", candidate) + + with pytest.raises(module.ReferenceBuildError, match="unused member summaries"): + module._api_section() + + @pytest.mark.parametrize( ("docstring", "expected"), ( From 386f55cf11c3d9f7ed9143611c1b955a8dd94a4a Mon Sep 17 00:00:00 2001 From: TimeLordRaps Date: Mon, 28 Sep 2026 11:02:23 -0700 Subject: [PATCH 6/6] fix: ground stacked pull requests against both review bases --- docs/PR_SOURCE_FEATURES.json | 6 +- docs/RELEASE_FEATURE_GROUNDING.md | 10 ++- scripts/check_pr_description.py | 128 +++++++++++++++++------------- tests/test_pr_source_grounding.py | 24 ++++++ 4 files changed, 105 insertions(+), 63 deletions(-) diff --git a/docs/PR_SOURCE_FEATURES.json b/docs/PR_SOURCE_FEATURES.json index 0642984..076cf4a 100644 --- a/docs/PR_SOURCE_FEATURES.json +++ b/docs/PR_SOURCE_FEATURES.json @@ -186,7 +186,7 @@ }, { "path": "scripts/check_pr_description.py", - "sha256": "8b600df838fe8ac220f6df2ee2795f0834afcf0c482639112a424651a274c57c", + "sha256": "6d6c803b7adcabfda035e6abb664a23c320e4e6bff7e7621bd8554af010a8b6b", "symbols": [ "_fail", "accountable_domain_inventory", @@ -206,8 +206,8 @@ "tracked_file_count", "use_commit" ], - "summary": "Binds pull-request prose to selected source/commit bytes, reviewed source rows, declared adapters and exact inventory/head fields; recognizes current namespace coordinates through tier8 and keeps the standalone fallback inventory in tested parity. Unknown governance-tier object names now fail.", - "limits": "Prose/tree consistency does not establish correctness, review acceptance, full object certification or release readiness. Historical adapter ranges retain their own meanings; the fallback remains a tested specification copy for standalone fixtures." + "summary": "Binds pull-request prose to selected source/commit bytes, reviewed source rows, declared adapters and exact inventory/head fields. It now checks up to two distinct ancestor-base source blocks against the same head for stacked pull requests, while retaining current namespace and fallback inventory checks.", + "limits": "Every supplied source block is checked for completeness, but prose/tree consistency does not establish correctness, review acceptance, full object certification or release readiness. Historical adapter ranges retain their meanings; the fallback remains a tested specification copy." }, { "path": "scripts/check_pr_description_changed.py", diff --git a/docs/RELEASE_FEATURE_GROUNDING.md b/docs/RELEASE_FEATURE_GROUNDING.md index 9a081d7..d3d08d1 100644 --- a/docs/RELEASE_FEATURE_GROUNDING.md +++ b/docs/RELEASE_FEATURE_GROUNDING.md @@ -21,8 +21,12 @@ to obtain the binding fields. Add `--commit ` for commit eviden The base is the trusted review target, not a base chosen to conceal changes; hosted callers must supply the actual target branch or base. Missing objects fail closed. -The description must contain exactly one fenced `vstd-source-features` block with -a JavaScript Object Notation (JSON) object. Small changes may place `base`, `target` +The description must contain one fenced `vstd-source-features` block for the +review base, or two blocks with distinct ancestor bases for a stacked pull +request whose hosted checks use both its immediate parent and the default +branch. Every block is checked against the same reviewed head; a second block +cannot conceal a missing or stale row in the first. Each block contains a +JavaScript Object Notation (JSON) object. Small changes may place `base`, `target` and `files` in that block. Large changes may put the complete `files` array in the committed `docs/PR_SOURCE_FEATURES.json` file and place `base`, `target`, and `manifest: {"path":"docs/PR_SOURCE_FEATURES.json","sha256":"..."}` in the block. @@ -40,7 +44,7 @@ working-tree edits cannot change the verdict. Both forms require each file row t The generated inventory deliberately does not invent summaries or limits. A list of hashes without those fields fails. Omitted or extra paths, missing definitions, -duplicate keys/paths/blocks, stale digests and incorrect base/target bindings fail. +duplicate keys/paths/bases, stale digests and incorrect base/target bindings fail. Non-Python files and module-level changes remain bound through whole-file digests. The manifest is a review aid, not a way to omit a source path, altered definition, behavioral summary or limit from the description's referenced evidence. diff --git a/scripts/check_pr_description.py b/scripts/check_pr_description.py index 512e922..14e2a2d 100644 --- a/scripts/check_pr_description.py +++ b/scripts/check_pr_description.py @@ -156,14 +156,14 @@ def visit(nodes: list, prefix: str = "") -> None: def check_source_grounding(body: str, findings: list[str], *, root: Path = ROOT, base: str = "origin/main", target: str | None = None) -> None: - """Require one reviewable record per changed source path, with no stale exclusions.""" + """Require complete source records for each declared stacked review base.""" try: expected = source_feature_inventory(root, base, target) if not expected["files"]: return blocks = re.findall(r"^```vstd-source-features\s*\n(.*?)^```[ \t]*$", body, re.MULTILINE | re.DOTALL) - if len(blocks) != 1: - raise ValueError("exactly one vstd-source-features block is required") + if not 1 <= len(blocks) <= 2: + raise ValueError("one or two vstd-source-features blocks are required") def unique(pairs: list) -> dict: result = {} for key, value in pairs: @@ -171,62 +171,76 @@ def unique(pairs: list) -> dict: raise ValueError("duplicate source coverage field") result[key] = value return result - record = json.loads(blocks[0], object_pairs_hook=unique) - if type(record) is not dict or set(record) not in ( - {"base", "target", "files"}, {"base", "target", "manifest"} - ): - raise ValueError("invalid source coverage record fields") - if any(record[key] != expected[key] for key in ("base", "target")): + records = [json.loads(block, object_pairs_hook=unique) for block in blocks] + bases: set[str] = set() + for record in records: + if type(record) is not dict or set(record) not in ( + {"base", "target", "files"}, {"base", "target", "manifest"} + ): + raise ValueError("invalid source coverage record fields") + declared_base = record["base"] + if (type(declared_base) is not str + or not re.fullmatch(r"[0-9a-f]{40}", declared_base) + or declared_base in bases): + raise ValueError("source coverage bases must be distinct commit identifiers") + bases.add(declared_base) + if expected["base"] not in bases: raise ValueError("source coverage base or target is stale") - if "manifest" in record: - locator = record["manifest"] - if (type(locator) is not dict or set(locator) != {"path", "sha256"} - or locator["path"] != SOURCE_FEATURE_MANIFEST - or type(locator["sha256"]) is not str - or not re.fullmatch(r"[0-9a-f]{64}", locator["sha256"])): - raise ValueError("source coverage manifest locator is invalid") - if target is None: - manifest_path = root / SOURCE_FEATURE_MANIFEST - if (manifest_path.is_symlink() or not manifest_path.is_file() - or not manifest_path.resolve().is_relative_to(root.resolve()) - or manifest_path.stat().st_size > MAX_SOURCE_FEATURE_MANIFEST_BYTES): - raise ValueError("source coverage manifest must be a bounded regular file") - raw = manifest_path.read_bytes() - else: - object_name = expected["target"] + ":" + SOURCE_FEATURE_MANIFEST - size = subprocess.run(["git", "-C", str(root), "cat-file", "-s", object_name], - capture_output=True, timeout=30) - size.check_returncode() - if int(size.stdout) > MAX_SOURCE_FEATURE_MANIFEST_BYTES: - raise ValueError("source coverage manifest byte bound exceeded") - archived = subprocess.run(["git", "-C", str(root), "show", object_name], + + for record in records: + checked = (expected if record["base"] == expected["base"] else + source_feature_inventory(root, record["base"], target)) + if record["target"] != checked["target"]: + raise ValueError("source coverage base or target is stale") + if "manifest" in record: + locator = record["manifest"] + if (type(locator) is not dict or set(locator) != {"path", "sha256"} + or locator["path"] != SOURCE_FEATURE_MANIFEST + or type(locator["sha256"]) is not str + or not re.fullmatch(r"[0-9a-f]{64}", locator["sha256"])): + raise ValueError("source coverage manifest locator is invalid") + if target is None: + manifest_path = root / SOURCE_FEATURE_MANIFEST + if (manifest_path.is_symlink() or not manifest_path.is_file() + or not manifest_path.resolve().is_relative_to(root.resolve()) + or manifest_path.stat().st_size > MAX_SOURCE_FEATURE_MANIFEST_BYTES): + raise ValueError("source coverage manifest must be a bounded regular file") + raw = manifest_path.read_bytes() + else: + object_name = checked["target"] + ":" + SOURCE_FEATURE_MANIFEST + size = subprocess.run(["git", "-C", str(root), "cat-file", "-s", object_name], capture_output=True, timeout=30) - archived.check_returncode() - raw = archived.stdout - if hashlib.sha256(raw).hexdigest() != locator["sha256"]: - raise ValueError("source coverage manifest digest differs") - document = json.loads(raw.decode("utf-8"), object_pairs_hook=unique) - if type(document) is not dict or set(document) != {"base", "files"}: - raise ValueError("source coverage manifest fields are invalid") - record = {"base": document["base"], "target": record["target"], - "files": document["files"]} - if record["base"] != expected["base"]: - raise ValueError("source coverage manifest base differs") - if type(record["files"]) is not list: - raise ValueError("source coverage files must be a list") - observed = {} - for row in record["files"]: - if type(row) is not dict or set(row) != {"path", "sha256", "symbols", "summary", "limits"}: - raise ValueError("each source row needs path, sha256, symbols, summary and limits") - if type(row["path"]) is not str or row["path"] in observed: - raise ValueError("invalid or duplicate source path") - if any(type(row[key]) is not str or not row[key].strip() for key in ("summary", "limits")): - raise ValueError("source coverage requires a behavioral summary and explicit limits") - observed[row["path"]] = {key: row[key] for key in ("path", "sha256", "symbols")} - wanted = {row["path"]: row for row in expected["files"]} - for path in sorted(set(wanted) | set(observed)): - if wanted.get(path) != observed.get(path): - _fail(findings, f"source feature coverage missing, stale or extraneous: {path}") + size.check_returncode() + if int(size.stdout) > MAX_SOURCE_FEATURE_MANIFEST_BYTES: + raise ValueError("source coverage manifest byte bound exceeded") + archived = subprocess.run(["git", "-C", str(root), "show", object_name], + capture_output=True, timeout=30) + archived.check_returncode() + raw = archived.stdout + if hashlib.sha256(raw).hexdigest() != locator["sha256"]: + raise ValueError("source coverage manifest digest differs") + document = json.loads(raw.decode("utf-8"), object_pairs_hook=unique) + if type(document) is not dict or set(document) != {"base", "files"}: + raise ValueError("source coverage manifest fields are invalid") + record = {"base": document["base"], "target": record["target"], + "files": document["files"]} + if record["base"] != checked["base"]: + raise ValueError("source coverage manifest base differs") + if type(record["files"]) is not list: + raise ValueError("source coverage files must be a list") + observed = {} + for row in record["files"]: + if type(row) is not dict or set(row) != {"path", "sha256", "symbols", "summary", "limits"}: + raise ValueError("each source row needs path, sha256, symbols, summary and limits") + if type(row["path"]) is not str or row["path"] in observed: + raise ValueError("invalid or duplicate source path") + if any(type(row[key]) is not str or not row[key].strip() for key in ("summary", "limits")): + raise ValueError("source coverage requires a behavioral summary and explicit limits") + observed[row["path"]] = {key: row[key] for key in ("path", "sha256", "symbols")} + wanted = {row["path"]: row for row in checked["files"]} + for path in sorted(set(wanted) | set(observed)): + if wanted.get(path) != observed.get(path): + _fail(findings, f"source feature coverage missing, stale or extraneous: {path}") except (OSError, ValueError, SyntaxError, UnicodeError, subprocess.SubprocessError, tarfile.TarError) as error: _fail(findings, f"source feature grounding failed: {error}") diff --git a/tests/test_pr_source_grounding.py b/tests/test_pr_source_grounding.py index 9950dbe..4a08999 100644 --- a/tests/test_pr_source_grounding.py +++ b/tests/test_pr_source_grounding.py @@ -168,6 +168,30 @@ def test_duplicate_json_keys_and_multiple_blocks_fail(repo): assert check(repo, body.replace('"base":', '"base":"forged", "base":', 1)) +def test_stacked_pull_request_covers_both_review_bases(repo): + root, main_base = repo + git(root, "add", ".") + git(root, "commit", "-m", "release parent") + release_base = git(root, "rev-parse", "HEAD") + (root / "src/verifier/feature.py").write_text( + "def existing():\n return 3\n\ndef admission():\n return False\n", + encoding="utf-8", + ) + main_block = body_for(gate.source_feature_inventory(root, main_base)) + release_block = body_for(gate.source_feature_inventory(root, release_base)) + body = main_block + "\n" + release_block + + for base in (main_base, release_base): + findings = [] + gate.check_source_grounding(body, findings, root=root, base=base) + assert findings == [] + + stale = release_block.replace('"sha256": "', '"sha256": "0', 1) + findings = [] + gate.check_source_grounding(main_block + "\n" + stale, findings, root=root, base=main_base) + assert findings + + def test_unimplemented_accountability_domain_cannot_be_omitted(tmp_path, monkeypatch): source = tmp_path / "verifier/core" source.mkdir(parents=True)