@mcptoolshop/accessibility-suite 0.1.0

package/docs/prov-spec/CONTRIBUTING.md

@@ -0,0 +1,145 @@
+# Contributing to prov-spec
+
+Thank you for your interest in contributing to prov-spec! This is a formal specification for provenance method IDs, records, and validation.
+
+## How to Contribute
+
+### Reporting Issues
+
+If you find a bug or have a suggestion:
+
+1. Check if the issue already exists in [GitHub Issues](https://github.com/mcp-tool-shop-org/prov-spec/issues)
+2. If not, create a new issue with:
+   - A clear, descriptive title
+   - Steps to reproduce (for bugs)
+   - Expected vs. actual behavior
+   - Your environment (Python version, OS)
+
+### Contributing to the Specification
+
+**Before proposing a new method ID:**
+
+1. Open an issue describing:
+   - The real-world use case
+   - Why existing method IDs don't suffice
+   - Expected behavior and semantics
+2. Wait for maintainer feedback
+3. Method IDs require real-world justification — we don't speculatively add IDs
+
+**Spec changes:**
+
+1. Fork the repository and create a branch from `main`
+2. Make your changes to files in `spec/`
+3. Update `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+4. Submit a pull request with:
+   - Clear description of changes
+   - Rationale for the change
+   - Backward compatibility analysis
+
+### Contributing Reference Tools
+
+Reference tools in `tools/` are provided for convenience and are not normative.
+
+1. **Python validator** (`tools/python/prov_validator.py`):
+   - Follow existing code style
+   - Add test cases for new features
+   - Ensure all test vectors pass
+   - Keep dependencies minimal
+
+### Adding Test Vectors
+
+Test vectors live in `spec/vectors/[method-id]/`:
+
+1. Create a new directory for the method ID
+2. Add `input.json` and `expected.json` files
+3. Follow the format of existing vectors
+4. Ensure deterministic behavior
+5. Update the method's documentation
+
+### Development Workflow
+
+```bash
+# Clone the repository
+git clone https://github.com/mcp-tool-shop-org/prov-spec.git
+cd prov-spec
+
+# Verify installation
+python tools/python/prov_validator.py --help
+
+# List known methods
+python tools/python/prov_validator.py list-methods
+
+# Run a specific test vector
+python tools/python/prov_validator.py check-vector integrity.digest.sha256
+
+# Validate a provenance record
+python tools/python/prov_validator.py validate-methods record.json --strict
+```
+
+### Specification Style Guide
+
+- Use RFC 2119 keywords (MUST, SHOULD, MAY) consistently
+- Include examples for every requirement
+- Keep language precise and unambiguous
+- Reference existing standards where applicable
+- Use ABNF notation for grammar rules
+
+### Versioning Policy
+
+- **Spec version:** Semantic Versioning 2.0.0
+- **Method catalog:** Append-only within major version
+- **Schemas:** `additionalProperties: false` for forward compatibility
+- **Method IDs marked `stable`:** Append-only, semantics never change
+
+### Conformance Levels
+
+When adding features, consider the conformance level:
+
+| Level | Name | Requirements |
+|-------|------|--------------|
+| **1** | Integrity | `integrity.digest.*` methods |
+| **2** | Engine | Level 1 + `engine.*` methods |
+| **3** | Lineage | Level 2 + `lineage.*` methods |
+
+See [CONFORMANCE_LEVELS.md](CONFORMANCE_LEVELS.md) for details.
+
+### Reserved Namespaces
+
+These namespaces are reserved for future use:
+- `policy.*` - Access control, permissions
+- `attestation.*` - Signed claims, witnesses
+- `execution.*` - Runtime context, environments
+- `audit.*` - Compliance, logging
+
+### Code Review Process
+
+1. Maintainers review for:
+   - Specification clarity
+   - Backward compatibility
+   - Real-world justification
+   - Test coverage
+2. Address feedback promptly
+3. Maintainers merge when approved
+
+### Testing Requirements
+
+- All test vectors must pass
+- New method IDs require test vectors
+- Schema changes require validation examples
+- Reference tools must validate correctly
+
+## Code of Conduct
+
+Please note that this project is released with a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you agree to abide by its terms.
+
+## Questions?
+
+Open an issue or start a discussion. We're here to help!
+
+## References
+
+- [PROV_METHODS_SPEC.md](spec/PROV_METHODS_SPEC.md) — Normative specification
+- [CONFORMANCE_LEVELS.md](CONFORMANCE_LEVELS.md) — Conformance tiers
+- [Semantic Versioning](https://semver.org/)
+- [Keep a Changelog](https://keepachangelog.com/)
+- [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.html) — Key words for RFCs

package/docs/prov-spec/IMPLEMENTER_CHECKLIST.md

@@ -0,0 +1,137 @@
+# prov-spec — Implementer Checklist (v0.1.0)
+
+This checklist is for engineers implementing prov-spec–compliant provenance methods or validators.
+
+**If you can check every box below, your implementation is compliant.**
+
+---
+
+## 1. Scope Check (before you write code)
+
+- [ ] I am implementing **specific method IDs**, not "provenance in general"
+- [ ] I understand that prov-spec standardizes **contracts**, not storage, transport, or policy
+- [ ] I am **not adding behavior** that is not explicitly specified
+
+> If you want flexibility, stop here—prov-spec is intentionally strict.
+
+---
+
+## 2. Method Identification
+
+- [ ] Every provenance record includes a valid `method_id`
+- [ ] The `method_id` **exactly matches** an entry in `spec/methods.json`
+- [ ] I do not invent or rename method IDs
+- [ ] I treat method IDs as **stable contracts**, not strings of convenience
+
+> **Rule:** If the ID is marked `stable`, its semantics must never change.
+
+---
+
+## 3. Semantic Compliance (most important)
+
+For each implemented method:
+
+- [ ] I have read the method's normative requirements in `PROV_METHODS_SPEC.md`
+- [ ] All **MUST** requirements are implemented
+- [ ] All **MUST NOT** constraints are enforced
+- [ ] Optional behavior is clearly optional and documented
+
+> **Rule:** Passing tests without meeting semantics is non-compliant.
+
+---
+
+## 4. Canonicalization & Integrity (if applicable)
+
+If your method involves hashing, signing, or verification:
+
+- [ ] I use the **exact canonicalization algorithm** specified
+- [ ] I hash/sign the **canonical bytes**, not ad-hoc serialization
+- [ ] I reject non-canonical or ambiguous inputs
+- [ ] Digest values match expected length, encoding, and format exactly
+
+> **Common failure:** Correct algorithm, wrong bytes.
+
+---
+
+## 5. Record Shape & Fields
+
+- [ ] Output records include all required fields
+- [ ] Field names, types, and nesting match the spec
+- [ ] No required fields are omitted
+- [ ] No forbidden fields are added
+
+Validate against the JSON Schemas in `spec/schemas/`.
+
+---
+
+## 6. Test Vectors (mandatory)
+
+For each implemented method:
+
+- [ ] All **positive** test vectors pass
+- [ ] All **negative** (must-fail) vectors fail correctly
+- [ ] Failures are **explicit** (errors), not silent acceptance
+
+> **Rule:** If a must-fail vector passes, the implementation is wrong.
+
+---
+
+## 7. Capability Declaration (recommended)
+
+If publishing an engine or tool:
+
+- [ ] I provide a `prov-capabilities.json`
+- [ ] Declared methods **exactly match** what is implemented
+- [ ] The manifest validates against `prov-capabilities.schema.json`
+
+This enables automated interoperability without code imports.
+
+---
+
+## 8. Conformance Level
+
+- [ ] I know which conformance level I meet:
+  - **Level 1:** Integrity
+  - **Level 2:** Engine
+  - **Level 3:** Lineage
+- [ ] I do not claim a higher level than implemented
+- [ ] Unsupported levels are not implied
+
+> Partial compliance is acceptable—misrepresentation is not.
+
+---
+
+## 9. Language & Tooling Neutrality
+
+- [ ] My implementation does **not depend** on prov-spec reference tooling
+- [ ] I treat the Python validator as **optional**
+- [ ] I could replace the validator and still be compliant
+
+> Authority lives in the spec and vectors, not in code.
+
+---
+
+## 10. Versioning Discipline
+
+- [ ] I record which spec version I target (e.g. `v0.1.0`)
+- [ ] I do not assume future behavior
+- [ ] I understand that stable method semantics **never change**
+
+If the spec updates, re-run vectors before upgrading claims.
+
+---
+
+## Final Sanity Check
+
+Ask yourself:
+
+> *"Could someone else independently implement this method and produce the same result?"*
+
+- If the answer is **yes**, you're done.
+- If the answer is **maybe**, re-read the spec.
+
+---
+
+**prov-spec exists to make provenance verifiable without trusting the producer.**
+
+**This checklist exists to make that practical.**

package/docs/prov-spec/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 prov-spec contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/docs/prov-spec/PRESS_RELEASE.md

@@ -0,0 +1,74 @@
+# prov-spec v0.1.0 Released
+
+**A formal, language-neutral specification for verifiable provenance**
+
+*January 26, 2026*
+
+---
+
+Today marks the release of **prov-spec v0.1.0**, a formal, versioned specification and conformance suite for provenance method identifiers, records, and validation.
+
+prov-spec defines a minimal, stable interoperability surface for provenance systems—focusing on **what can be verified**, not how systems are built. It is designed to be implementation-agnostic, language-neutral, and durable over time.
+
+---
+
+## What prov-spec provides
+
+- Normative specification using RFC 2119 language
+- Stable, append-only method identifiers with frozen semantics
+- Machine-readable catalogs and JSON Schemas
+- Positive and negative test vectors for deterministic validation
+- Conformance levels for incremental adoption
+- Reference validator tooling (optional, non-privileged)
+
+---
+
+## What prov-spec does not do
+
+prov-spec intentionally does **not** define:
+
+- Storage formats
+- Transport protocols
+- User interfaces
+- Policy or governance models
+
+This restraint is deliberate. **prov-spec standardizes contracts, not implementations.**
+
+---
+
+## Proven interoperability
+
+To demonstrate language neutrality, a zero-dependency Node.js provenance engine was implemented independently and validated against prov-spec test vectors **without importing any prov-spec code**. The engine passes all applicable vectors, confirming that the specification is executable and portable.
+
+---
+
+## Stability guarantees
+
+- Method identifiers marked `stable` are **append-only**
+- Semantics for stable methods will **never change**
+- Compatibility is guaranteed within a major version
+
+**prov-spec v0.1.0 is considered stable.**
+
+---
+
+## Who this is for
+
+- Provenance engine authors
+- Tool and platform integrators
+- Infrastructure and security teams
+- Auditors and verification systems
+- Anyone who needs provenance to remain verifiable beyond the lifetime of a single system
+
+---
+
+## Availability
+
+prov-spec v0.1.0 is available now under the MIT license.
+
+- Specification: [github.com/mcp-tool-shop-org/prov-spec](https://github.com/mcp-tool-shop-org/prov-spec)
+- Node.js Reference Engine: [github.com/mcp-tool-shop-org/prov-engine-js](https://github.com/mcp-tool-shop-org/prov-engine-js)
+
+---
+
+> **prov-spec exists so provenance can outlive the systems that generate it.**

package/docs/prov-spec/README.md

@@ -0,0 +1,182 @@
+# prov-spec
+
+**A formal, versioned specification and conformance suite for provenance method IDs, records, and validation.**
+
+[![Spec Version](https://img.shields.io/badge/spec-v0.1.0-blue)](spec/PROV_METHODS_SPEC.md)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+---
+
+## What is this?
+
+A normative specification defining:
+- **Method IDs** — stable, namespaced identifiers for provenance operations
+- **Provenance Records** — structured JSON documenting tool invocations
+- **Conformance Levels** — testable compliance tiers
+- **Test Vectors** — canonical inputs/outputs for interoperability
+
+## What is this not?
+
+- Not a framework
+- Not an SDK
+- Not MCP-specific
+- Not Python-specific
+
+## Who is it for?
+
+- **Engine authors** — implement provenance in any language
+- **Tool integrators** — wrap existing tools with provenance
+- **Auditors** — verify provenance claims
+- **Infrastructure builders** — build provenance-aware systems
+
+---
+
+## Stability Guarantee
+
+> **Method IDs marked `stable` are append-only and will never change semantics.**
+> **Compatibility is guaranteed within a major version.**
+
+---
+
+## Quick Start
+
+### Verify in 10 seconds
+
+```bash
+# Clone and run a test vector
+git clone https://github.com/prov-spec/prov-spec
+cd prov-spec
+python tools/python/prov_validator.py check-vector integrity.digest.sha256
+```
+
+Expected output: `INFO: Test vector integrity.digest.sha256 passed`
+
+---
+
+### 1. Understand the spec
+
+Read [`spec/PROV_METHODS_SPEC.md`](spec/PROV_METHODS_SPEC.md) — the normative specification.
+
+### 2. Check the catalog
+
+Browse [`spec/methods.json`](spec/methods.json) — machine-readable method registry.
+
+### 3. Declare conformance
+
+Ship a `prov-capabilities.json` in your project:
+
+```json
+{
+  "schema": "prov-capabilities@v0.1",
+  "engine": {
+    "name": "your-engine",
+    "version": "1.0.0"
+  },
+  "implements": [
+    "adapter.wrap.envelope_v0_1",
+    "integrity.digest.sha256"
+  ],
+  "conformance_level": "fully-conformant"
+}
+```
+
+### 4. Validate (optional)
+
+Use the reference validator:
+
+```bash
+# List known methods
+python -m prov_validator list-methods
+
+# Validate a provenance record
+python -m prov_validator validate-methods record.json --strict
+
+# Run test vectors
+python -m prov_validator check-vector integrity.digest.sha256
+```
+
+---
+
+## Repository Structure
+
+```
+prov-spec/
+├── spec/                    # Normative specification
+│   ├── PROV_METHODS_SPEC.md # Main specification document
+│   ├── methods.json         # Machine-readable method catalog
+│   ├── schemas/             # JSON Schemas
+│   │   ├── prov.record.schema.v0.1.json
+│   │   ├── artifact.schema.v0.1.json
+│   │   ├── evidence.schema.v0.1.json
+│   │   ├── mcp.envelope.schema.v0.1.json
+│   │   └── prov-capabilities.schema.json
+│   └── vectors/             # Test vectors
+│       ├── integrity.digest.sha256/
+│       ├── adapter.wrap.envelope_v0_1/
+│       └── ...
+├── tools/                   # Reference implementations (optional)
+│   └── python/              # Python reference validator
+├── examples/                # Example files
+├── CONFORMANCE_LEVELS.md    # Conformance tiers
+└── CHANGELOG.md             # Version history
+```
+
+**Note:** Reference tools are provided for convenience and are not required for conformance.
+
+---
+
+## Conformance Levels
+
+| Level | Name | Requirements |
+|-------|------|--------------|
+| **1** | Integrity | `integrity.digest.*` methods |
+| **2** | Engine | Level 1 + `engine.*` methods |
+| **3** | Lineage | Level 2 + `lineage.*` methods |
+
+See [`CONFORMANCE_LEVELS.md`](CONFORMANCE_LEVELS.md) for details.
+
+---
+
+## Method Namespaces
+
+| Namespace | Purpose |
+|-----------|---------|
+| `adapter.*` | Envelope wrapping, transport |
+| `engine.*` | Evidence extraction, provenance construction |
+| `integrity.*` | Hashing, signatures, verification |
+| `lineage.*` | Parent linking, graph operations |
+
+Reserved for future use: `policy.*`, `attestation.*`, `execution.*`, `audit.*`
+
+---
+
+## Versioning
+
+- **Spec version:** `v0.1.0`
+- **Method catalog:** append-only within major version
+- **Schemas:** `additionalProperties: false` — forward-compatible within patch
+
+---
+
+## Contributing
+
+1. New method IDs: open an issue with use case
+2. Spec clarifications: submit PR to `spec/`
+3. Reference tools: submit PR to `tools/`
+
+Method IDs require real-world justification. We don't speculatively add IDs.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+---
+
+## References
+
+- [PROV_METHODS_SPEC.md](spec/PROV_METHODS_SPEC.md) — Normative specification
+- [PROV_METHODS_CATALOG.md](spec/PROV_METHODS_CATALOG.md) — Human-readable catalog
+- [CONFORMANCE_LEVELS.md](CONFORMANCE_LEVELS.md) — Conformance tiers
+- [MCP_COMPATIBILITY.md](spec/MCP_COMPATIBILITY.md) — MCP envelope compatibility

package/docs/prov-spec/SETUP.md

@@ -0,0 +1,135 @@
+# Getting Started with prov-spec
+
+This guide is for engineers who want to validate, implement, or integrate with prov-spec.
+
+**You do not need to use any specific language or framework to comply.**
+
+---
+
+## Repository Structure
+
+```
+prov-spec/
+├── spec/                # Normative specification, schemas, vectors
+├── tools/python/        # Reference validator (optional)
+├── interop/             # Interoperability proofs
+├── WHY.md               # Design intent and non-goals
+└── CONFORMANCE_LEVELS.md
+```
+
+**Only the `spec/` directory is normative.**
+
+---
+
+## Option A: Validate provenance records (recommended first step)
+
+### Requirements
+
+- Python 3.10+
+
+### Run the reference validator
+
+```bash
+cd prov-spec
+python tools/python/prov_validator.py --help
+```
+
+### Validate a provenance record
+
+```bash
+python tools/python/prov_validator.py \
+  validate-methods path/to/record.json --strict
+```
+
+This checks:
+- Method IDs
+- Required fields
+- Semantic constraints
+- Catalog compliance
+
+---
+
+## Option B: Validate against official test vectors
+
+### Run a built-in vector check
+
+```bash
+python tools/python/prov_validator.py \
+  check-vector integrity.digest.sha256
+```
+
+Vectors include **must-pass** and **must-fail** cases.
+
+**Passing vectors is sufficient to demonstrate method compliance.**
+
+---
+
+## Option C: Declare engine capabilities (no imports required)
+
+Third-party engines declare support using a capability manifest:
+
+```json
+{
+  "schema": "mcp-tool-shop/prov-capabilities@v0.1",
+  "engine": {
+    "name": "example-engine",
+    "version": "1.0.0"
+  },
+  "implements": [
+    "integrity.digest.sha256",
+    "adapter.wrap.envelope_v0_1"
+  ]
+}
+```
+
+### Validate the manifest
+
+```bash
+python tools/python/prov_validator.py \
+  validate-manifest prov-capabilities.json
+```
+
+---
+
+## Option D: Implement prov-spec in any language
+
+To implement a method:
+
+1. Read its normative requirements in `spec/PROV_METHODS_SPEC.md`
+2. Implement the method exactly as specified
+3. Run the corresponding test vectors
+4. (Optional) Publish a `prov-capabilities.json`
+
+**No SDK, framework, or library is required.**
+
+---
+
+## Reference tooling policy
+
+The Python validator is provided for **convenience only**.
+
+- It is **not required** for conformance
+- Alternative validators and engines are encouraged
+- All authority lives in the specification and vectors
+
+---
+
+## Versioning and upgrades
+
+- v0.1.0 is **stable**
+- Method IDs are **append-only**
+- New behavior will only appear in new versions
+- Existing records remain valid forever
+
+---
+
+## Where to start (TL;DR)
+
+If you are new:
+
+1. Run one vector check
+2. Read `WHY.md`
+3. Implement one method
+4. Stop there
+
+**prov-spec is intentionally small.**