docs: methodology paper + adoption guide; em-dash pass across prose docs - #1
Conversation
Two companion docs to the Bundle v1 standard: docs/methodology.md (how the Validator Integrity Index is built + honest limits) and docs/adoption-guide.md (classify a finding into the eleven-family vocabulary, worked example from the public NR-2026-001 advisory). Linked from the README under a new 'Adopting the standard' section. Built from public-only sources; no finding counts, no corpus internals, no replication-coverage list. Branched off clean main (v0.1.2), NOT off the stale loop-01 branch whose history carries the withdrawn proof.
…ee, colons for headings/labels, plain punctuation in prose)
…G, rust README, dataset card) Style-only: em-dashes replaced with plain punctuation (hyphens in file trees and changelog date headers, colons for labels, commas/periods in prose). No content, count, or claim changes; the held-out-chain figures and all wording are unchanged. Code files (docstrings + spec-definition strings that feed the generated schema and contract tests) intentionally untouched.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces two new documentation files, docs/adoption-guide.md and docs/methodology.md, which detail the methodology and classification rules for the Validator Integrity Index. It also cleans up punctuation across all markdown files by replacing em-dashes with hyphens, colons, and periods. The review feedback is highly constructive, pointing out a missing CITATION.cff file reference, correcting a discrepancy regarding file hashes in the dataset card's description of the manifest, and suggesting clearer phrasing for resource-amplification classification rules.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
|
|
||
| ## Citing and contributing | ||
|
|
||
| Cite the format using the `CITATION.cff` file in this repository. The format is MIT-licensed, so you can |
There was a problem hiding this comment.
The repository does not currently contain a CITATION.cff file. To prevent broken references, please update this text to refer to the Citation section in the README.md, or add a CITATION.cff file to the repository root.
| Cite the format using the `CITATION.cff` file in this repository. The format is MIT-licensed, so you can | |
| Cite the format using the citation details provided in the `README.md` of this repository. The format is MIT-licensed, so you can |
| | `vectors.parquet` | Computed feature vectors derived from the above | **Not populated in this release.** Reserved schema slot; consumers should derive feature vectors at inference time using the bundle-spec reference parser plus their own feature pipeline | | ||
|
|
||
| The manifest pins `primitive_id`, `family_id`, `traffic_source`, `fidelity_class`, `target_authorisation`, and provenance hashes for every file in the bundle. The schema is chain-agnostic — no field assumes a specific blockchain. The `BundleFiles` block (`packets_pcap`, `host_parquet`, `app_parquet`, `protocol_parquet`, `responses_parquet`, `vectors_parquet`) is the authoritative present/absent contract; readers should check the manifest before reading each modality file. | ||
| The manifest pins `primitive_id`, `family_id`, `traffic_source`, `fidelity_class`, `target_authorisation`, and provenance hashes for every file in the bundle. The schema is chain-agnostic: no field assumes a specific blockchain. The `BundleFiles` block (`packets_pcap`, `host_parquet`, `app_parquet`, `protocol_parquet`, `responses_parquet`, `vectors_parquet`) is the authoritative present/absent contract; readers should check the manifest before reading each modality file. |
There was a problem hiding this comment.
The dataset card states that the manifest pins "provenance hashes for every file in the bundle." However, the canonical BundleManifest and Provenance schemas (defined in python/bundle_spec/bundle_v1.py) do not include fields for file hashes, and the example manifest in README.md does not contain them either. To avoid confusing users looking for file hashes in the manifest, please update this description to accurately reflect the schema fields.
| The manifest pins `primitive_id`, `family_id`, `traffic_source`, `fidelity_class`, `target_authorisation`, and provenance hashes for every file in the bundle. The schema is chain-agnostic: no field assumes a specific blockchain. The `BundleFiles` block (`packets_pcap`, `host_parquet`, `app_parquet`, `protocol_parquet`, `responses_parquet`, `vectors_parquet`) is the authoritative present/absent contract; readers should check the manifest before reading each modality file. | |
| The manifest pins `primitive_id`, `family_id`, `traffic_source`, `fidelity_class`, and `target_authorisation` for the bundle. The schema is chain-agnostic: no field assumes a specific blockchain. The `BundleFiles` block (`packets_pcap`, `host_parquet`, `app_parquet`, `protocol_parquet`, `responses_parquet`, `vectors_parquet`) is the authoritative present/absent contract; readers should check the manifest before reading each modality file. |
| 7. Otherwise it is a resource-amplification shape. Pick by the resource that dominates: large response | ||
| bytes from a small request is `response_amp`; large CPU from a small request is `compute_amp`; | ||
| unbounded retained memory over time is `memory_amp`; a per-connection or per-subscription leak is | ||
| `connection_exhaustion`. |
There was a problem hiding this comment.
The phrasing "large response bytes" and "large CPU" is slightly awkward. Rephrasing these to refer to "large response size" and "high CPU consumption" would improve the grammatical flow and clarity of the classification rules.
| 7. Otherwise it is a resource-amplification shape. Pick by the resource that dominates: large response | |
| bytes from a small request is `response_amp`; large CPU from a small request is `compute_amp`; | |
| unbounded retained memory over time is `memory_amp`; a per-connection or per-subscription leak is | |
| `connection_exhaustion`. | |
| 7. Otherwise it is a resource-amplification shape. Pick by the resource that dominates: a large response | |
| size (in bytes) from a small request is `response_amp`; high CPU consumption from a small request is `compute_amp`; | |
| unbounded retained memory over time is `memory_amp`; a per-connection or per-subscription leak is | |
| `connection_exhaustion`. |
1 participant
Adds two companion docs to the Bundle v1 standard and cleans em-dashes across the prose docs.
What's here
docs/methodology.md: how the Validator Integrity Index is built, and what it does and does not yet claim.docs/adoption-guide.md: how to classify a validator-integrity finding into the eleven-family vocabulary, with a worked example from the public NR-2026-001 advisory.Built from public sources. No changes to code, schema, or example data.