@mcptoolshop/accessibility-suite 0.1.0

package/docs/prov-spec/WHY.md

@@ -0,0 +1,86 @@
+# Why prov-spec exists
+
+## The problem
+
+Provenance is everywhere. Every pipeline, every tool, every system generates some form of "where did this come from?" metadata. Build systems track inputs. ML pipelines record hyperparameters. Data workflows log transformations.
+
+But it's informal, implicit, unverifiable. Strings without contracts. Field names that vary by vendor. Hashes computed over undefined bytes. Claims you can't check without running the original system. This doesn't scale. When provenance is tied to a specific tool, it dies with that tool.
+
+## What went wrong historically
+
+Provenance has been tied to:
+
+- **Frameworks** — you need the framework to verify the provenance
+- **SDKs** — you need the SDK to parse the records
+- **Vendors** — you need the vendor's system to trust the claims
+
+This creates a problem: verification becomes impossible without "the original system." If your audit happens five years later, or in a different language, or after the vendor pivots — you're stuck.
+
+The result is that most provenance is write-only. Systems generate it, but nothing consumes it reliably. It exists for compliance theater, not actual verification.
+
+## The core idea
+
+**Provenance should be verifiable without trusting the producer.**
+
+That's the thesis. Everything in prov-spec hangs off this single requirement.
+
+If I can't verify your provenance claim using only:
+- the record you gave me
+- a specification I can read
+- inputs I can obtain
+
+...then your provenance is not provenance. It's a story.
+
+## What prov-spec standardizes
+
+- **Method identity** — stable, namespaced IDs that mean the same thing everywhere
+- **Semantics** — what a method ID *commits to* when claimed
+- **Canonical bytes** — exactly what gets hashed, no ambiguity
+- **Validation behavior** — test vectors that define correct output
+
+## What prov-spec refuses to standardize
+
+- **Storage** — where you keep records is your problem
+- **Transport** — how you send records is your problem
+- **UI** — how you display records is your problem
+- **Policy** — who trusts what is your problem
+
+This restraint is a feature. Every additional thing a spec standardizes is another thing that can break, another thing that creates lock-in, another thing that prevents adoption.
+
+prov-spec is deliberately minimal. It standardizes the verification surface and nothing else.
+
+## Why method IDs are the unit of interoperability
+
+A method ID like `integrity.digest.sha256` is not a function call. It's a *contract*.
+
+When a provenance record claims `integrity.digest.sha256`, it's saying:
+
+> "I computed a SHA-256 hash. The hash is over canonical JSON bytes. The bytes were computed using the canonicalization rules in the spec. The hex is lowercase. You can verify this yourself."
+
+That contract survives:
+- Rewrites of the producing system
+- Ports to different languages
+- Years of bit-rot
+- Changes in organizational ownership
+
+Method IDs are portable truth. Combined with test vectors, they become *executable* portable truth.
+
+## What success looks like
+
+Multiple engines, different languages, same vectors, same answers.
+
+A Python tool produces a provenance record. A Rust verifier checks it. A Node.js dashboard displays it. A Go auditor validates the chain. None of them share code. All of them agree on what the record means.
+
+That's the goal. Not "everyone uses our SDK." Not "everyone adopts our framework." Just: everyone agrees on what the words mean, and can prove it.
+
+## Non-goals
+
+prov-spec is **not a framework**. There's no runtime, no library you must import, no service you must call.
+
+prov-spec is **not a governance body**. We don't certify implementations, don't issue compliance badges, don't arbitrate disputes.
+
+prov-spec is **not an endorsement mechanism**. A valid provenance record doesn't mean the content is good, true, or trustworthy. It means the record is well-formed and the claims are verifiable.
+
+## Closing
+
+prov-spec exists so provenance can outlive the systems that generate it.

package/docs/prov-spec/examples/artifact.example.json

@@ -0,0 +1,14 @@
+{
+  "schema_version": "artifact.v0.1",
+  "artifact_id": "clierr-01",
+  "media_type": "application/json",
+  "locator": "file:/tmp/cli_error.json",
+  "digest": {
+    "alg": "sha256",
+    "value": "9f2c6a0e0f76c9d6d8b1c2f9a88d7b6c1e7f0f0b3f4a9b6c2d1a9e7c0b1f2a3c"
+  },
+  "labels": {
+    "role": "cli_error_json",
+    "schema": "cli.error.v0.1"
+  }
+}

package/docs/prov-spec/examples/artifact.ref.example.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": "artifact.ref.v0.1",
+  "locator": "file:/tmp/cli_error.json",
+  "media_type": "application/json",
+  "labels": {
+    "role": "cli_error_json",
+    "schema": "cli.error.v0.1"
+  }
+}

package/docs/prov-spec/examples/evidence.example.json

@@ -0,0 +1,6 @@
+{
+  "schema_version": "evidence.v0.1",
+  "field": "plan[0]",
+  "source": "artifact:clierr-01#json:/fix/0",
+  "method": "engine.extract.evidence.json_pointer"
+}

package/docs/prov-spec/examples/mcp.envelope.example.json

@@ -0,0 +1,97 @@
+{
+  "schema_version": "mcp.envelope.v0.1",
+  "result": {
+    "schema_version": "assist.response.v0.1",
+    "anchored_id": "PAYROLL.EXPORT.SFTP.AUTH",
+    "confidence": "High",
+    "safest_next_step": "Confirm the credential method used for SFTP.",
+    "plan": [
+      "Verify the username and password or the SSH key.",
+      "Re-run the export in dry run mode.",
+      "Retry the upload."
+    ],
+    "next_safe_commands": [
+      "payroll export --batch 2026-01-26 --dry-run"
+    ],
+    "notes": [
+      "This assistance is additive. Original output was not modified."
+    ],
+    "methods_applied": [
+      "engine.normalize.from_cli_error_v0_1",
+      "profile.screen_reader.apply",
+      "guard.validate_profile_transform"
+    ],
+    "evidence": [
+      {
+        "field": "anchored_id",
+        "source": "artifact:clierr-01#json:/id"
+      },
+      {
+        "field": "safest_next_step",
+        "source": "artifact:clierr-01#json:/why/0"
+      }
+    ]
+  },
+  "provenance": {
+    "schema_version": "prov.record.v0.1",
+    "run_id": "9a1c2e9f-5c3f-4a3a-9d5e-1d2b4b6f9c10",
+    "tool": {
+      "name": "a11y-assist",
+      "version": "v0.3.1",
+      "adapter": "cli"
+    },
+    "inputs": [
+      {
+        "schema_version": "artifact.v0.1",
+        "artifact_id": "clierr-01",
+        "media_type": "application/json",
+        "locator": "file:/tmp/cli_error.json",
+        "digest": {
+          "alg": "sha256",
+          "value": "9f2c6a0e0f76c9d6d8b1c2f9a88d7b6c1e7f0f0b3f4a9b6c2d1a9e7c0b1f2a3c"
+        },
+        "labels": {
+          "role": "cli_error_json",
+          "schema": "cli.error.v0.1"
+        }
+      }
+    ],
+    "outputs": [
+      {
+        "schema_version": "artifact.v0.1",
+        "artifact_id": "assist-01",
+        "media_type": "application/json",
+        "digest": {
+          "alg": "sha256",
+          "value": "3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b"
+        },
+        "labels": {
+          "role": "assist_response_json",
+          "schema": "assist.response.v0.1",
+          "profile": "screen-reader"
+        }
+      }
+    ],
+    "methods": [
+      "engine.normalize.from_cli_error_v0_1",
+      "profile.screen_reader.apply",
+      "guard.validate_profile_transform"
+    ],
+    "evidence": [
+      {
+        "schema_version": "evidence.v0.1",
+        "field": "safest_next_step",
+        "source": "artifact:clierr-01#json:/why/0"
+      }
+    ],
+    "parents": []
+  },
+  "meta": {
+    "adapter": "cli",
+    "request_id": "req-abc123",
+    "duration_ms": 42,
+    "schema_hints": {
+      "result": "assist.response.v0.1"
+    }
+  }
+}

package/docs/prov-spec/examples/mcp.request.example.json

@@ -0,0 +1,28 @@
+{
+  "schema_version": "mcp.request.v0.1",
+  "request_id": "req-001",
+  "tool": {
+    "name": "a11y-assist.explain",
+    "version": "v0.3.1"
+  },
+  "params": {
+    "profile": "screen-reader",
+    "_meta": {
+      "capture_provenance": true,
+      "capture_artifacts": true
+    }
+  },
+  "artifacts": [
+    {
+      "schema_version": "artifact.ref.v0.1",
+      "locator": "file:/tmp/cli_error.json",
+      "media_type": "application/json",
+      "labels": {
+        "role": "cli_error_json"
+      }
+    }
+  ],
+  "preferences": {
+    "deterministic": true
+  }
+}

package/docs/prov-spec/examples/prov.record.example.json

@@ -0,0 +1,35 @@
+{
+  "schema_version": "prov.record.v0.1",
+  "run_id": "9a1c2e9f-5c3f-4a3a-9d5e-1d2b4b6f9c10",
+  "tool": {
+    "name": "a11y-assist",
+    "version": "v0.3.1",
+    "adapter": "cli"
+  },
+  "inputs": [
+    {
+      "schema_version": "artifact.v0.1",
+      "artifact_id": "clierr-01",
+      "media_type": "application/json"
+    }
+  ],
+  "outputs": [
+    {
+      "schema_version": "artifact.v0.1",
+      "artifact_id": "assist-01",
+      "media_type": "application/json"
+    }
+  ],
+  "methods": [
+    "engine.normalize.from_cli_error_v0_1",
+    "guard.validate_profile_transform"
+  ],
+  "evidence": [
+    {
+      "schema_version": "evidence.v0.1",
+      "field": "safest_next_step",
+      "source": "artifact:clierr-01#json:/why/0"
+    }
+  ],
+  "parents": []
+}

package/docs/prov-spec/interop/PROOF_NODE_ENGINE.md

@@ -0,0 +1,114 @@
+# Interop Proof: Node.js Engine
+
+**Date:** 2025-01-26
+**Spec Version:** 0.1.0
+**Engine:** prov-engine-js v0.1.0
+
+This document provides evidence that prov-spec vectors can be validated by an independent, non-Python implementation.
+
+---
+
+## Engine Details
+
+| Property | Value |
+|----------|-------|
+| Name | prov-engine-js |
+| Version | 0.1.0 |
+| Language | JavaScript (Node.js 18+) |
+| Dependencies | None (built-ins only) |
+| Repository | https://github.com/prov-spec/prov-engine-js |
+
+## Implemented Methods
+
+- `integrity.digest.sha256`
+- `adapter.wrap.envelope_v0_1`
+
+## Vector Results
+
+### integrity.digest.sha256
+
+```
+$ node prov-engine.js check-vector spec/vectors/integrity.digest.sha256
+PASS: integrity.digest.sha256 vector
+```
+
+**Input:**
+```json
+{"key": "value", "number": 42, "nested": {"a": 1, "b": 2}}
+```
+
+**Output:**
+```json
+{
+  "canonical_form": "{\"key\":\"value\",\"nested\":{\"a\":1,\"b\":2},\"number\":42}",
+  "digest": {
+    "alg": "sha256",
+    "value": "54fb66ce0aa908012dc9c432d77d16df95a3d5033a557d1c14cfc6d82a63ae34"
+  }
+}
+```
+
+**Verification:** Output matches `spec/vectors/integrity.digest.sha256/expected.json` exactly.
+
+---
+
+### adapter.wrap.envelope_v0_1
+
+```
+$ node prov-engine.js check-vector spec/vectors/adapter.wrap.envelope_v0_1
+PASS: adapter.wrap.envelope_v0_1 vector
+```
+
+**Input:**
+```json
+{"ok": true, "count": 3, "message": "Operation completed"}
+```
+
+**Output:**
+```json
+{
+  "schema_version": "mcp.envelope.v0.1",
+  "result": {"ok": true, "count": 3, "message": "Operation completed"}
+}
+```
+
+**Verification:** Output matches `spec/vectors/adapter.wrap.envelope_v0_1/expected.json` exactly.
+
+---
+
+## Capability Manifest
+
+```json
+{
+  "schema": "prov-capabilities@v0.1",
+  "engine": {
+    "name": "prov-engine-js",
+    "version": "0.1.0",
+    "vendor": "prov-spec",
+    "license": "MIT"
+  },
+  "implements": [
+    "adapter.wrap.envelope_v0_1",
+    "integrity.digest.sha256"
+  ],
+  "conformance_level": "fully-conformant",
+  "constraints": {
+    "canonicalization": "jcs-subset",
+    "supported_digest_algorithms": ["sha256"]
+  }
+}
+```
+
+---
+
+## Conclusion
+
+The Node.js engine:
+
+1. Passes all applicable prov-spec vectors
+2. Produces byte-identical output to the Python reference
+3. Implements canonicalization per PROV_METHODS_SPEC.md Section 6
+4. Has zero dependencies beyond Node.js built-ins
+5. Shares no code with the Python reference implementation
+
+This constitutes proof of language-neutral interoperability.

package/docs/prov-spec/spec/MCP_COMPATIBILITY.md

@@ -0,0 +1,241 @@
+# MCP Envelope Compatibility Policy v0.1
+
+**Status:** Normative (v0.3.1+)
+
+This document defines how adapters wrap legacy tool outputs into `mcp.envelope.v0.1` safely.
+
+---
+
+## How to adopt (minimal)
+
+You can adopt the MCP envelope and provenance system incrementally.
+
+### If you already return JSON
+Wrap your tool output in `mcp.envelope.v0.1`:
+
+```json
+{
+  "schema_version": "mcp.envelope.v0.1",
+  "result": { "your": "existing json payload" },
+  "provenance": null
+}
+```
+
+Your existing payload remains unchanged and unconstrained.
+
+### If you return text output
+Wrap it as a string result:
+
+```json
+{
+  "schema_version": "mcp.envelope.v0.1",
+  "result": "your existing text output",
+  "provenance": null
+}
+```
+
+### If you want provenance (recommended for audits)
+Attach a `prov.record.v0.1` record with:
+- input artifacts (`inputs[]`)
+- output artifacts (`outputs[]`)
+- applied method IDs (`methods[]`)
+- optional evidence anchors (`evidence[]`)
+- optional lineage (`parents[]`)
+
+```json
+{
+  "schema_version": "mcp.envelope.v0.1",
+  "result": { "..." : "..." },
+  "provenance": {
+    "schema_version": "prov.record.v0.1",
+    "run_id": "uuid",
+    "tool": { "name": "your-tool", "version": "vX.Y.Z", "adapter": "mcp" },
+    "inputs": [],
+    "outputs": [],
+    "methods": [],
+    "evidence": [],
+    "parents": []
+  }
+}
+```
+
+---
+
+## 1. What Counts as "Legacy"
+
+Anything that returns a payload that is **not** already an `mcp.envelope.v0.1` object:
+
+- Plain string output
+- Raw JSON object result
+- Arrays, numbers, booleans
+- Tool-specific response objects (e.g., `assist.response.v0.1`)
+
+---
+
+## 2. Wrapping Rule
+
+Adapters **MAY** wrap legacy results into:
+
+```json
+{
+  "schema_version": "mcp.envelope.v0.1",
+  "result": <original_payload>,
+  "provenance": null
+}
+```
+
+This is always safe and preserves meaning.
+
+---
+
+## 3. Results with Existing schema_version
+
+If the legacy payload is an object with its own `schema_version` (e.g., `assist.response.v0.1`), keep it intact as `result`:
+
+```json
+{
+  "schema_version": "mcp.envelope.v0.1",
+  "result": { "schema_version": "assist.response.v0.1", ... },
+  "provenance": null
+}
+```
+
+**Do not** rename fields. **Do not** reformat. **Do not** "upgrade" schemas.
+
+---
+
+## 4. Error Handling
+
+If a tool fails and the adapter can only observe:
+- An exception
+- A non-zero exit code
+- stderr text
+
+Then wrap:
+- `result`: `null` (or original partial output if available)
+- `errors[]`: At least one entry describing the failure
+
+### Example
+
+```json
+{
+  "schema_version": "mcp.envelope.v0.1",
+  "result": null,
+  "errors": [
+    {
+      "code": "ADAPTER.EXECUTION.FAILED",
+      "message": "Tool execution failed with exit code 2.",
+      "details": { "exit_code": 2 }
+    }
+  ],
+  "provenance": null
+}
+```
+
+If the tool itself provides structured errors, prefer those codes.
+
+---
+
+## 5. Provenance Attachment (Opt-in)
+
+Adapters **SHOULD** only attach provenance when:
+
+1. They can compute reliable artifact digests and sources, **AND**
+2. It won't require network calls unless the caller opted in
+
+Otherwise, set `provenance: null`.
+
+### Opt-in Convention
+
+Use `params._meta` for provenance control:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `capture_provenance` | boolean | `false` | Attach `prov.record.v0.1` to envelope |
+| `capture_artifacts` | boolean | `false` | Compute digests for input/output artifacts |
+| `provenance_mode` | string | `"minimal"` | `"minimal"` or `"full"` |
+
+---
+
+## 6. Determinism Preference
+
+If `mcp.request.preferences.deterministic` is `true` (default):
+
+- Adapters **SHOULD** omit timestamps
+- Adapters **SHOULD** avoid network calls
+- Tools **MAY** downgrade behavior (e.g., skip enrichment)
+
+---
+
+## 7. Pass-through Rule (No Double-wrap)
+
+If a tool already returns `mcp.envelope.v0.1`, adapters **MUST** return it unchanged.
+
+**No nesting.**
+
+---
+
+## 8. Forward Compatibility Rule
+
+Consumers must treat unknown top-level envelope fields as invalid (since `additionalProperties: false`), so:
+
+- Add new envelope fields only with a **major version bump**, OR
+- Create `mcp.envelope.v0.2` when adding top-level fields
+
+Within `result`, anything goes.
+
+---
+
+## 9. Examples
+
+### 9.1 Legacy JSON Result
+
+**Input:**
+```json
+{ "ok": true, "count": 3 }
+```
+
+**Wrapped:**
+```json
+{
+  "schema_version": "mcp.envelope.v0.1",
+  "result": { "ok": true, "count": 3 }
+}
+```
+
+### 9.2 Legacy String
+
+**Input:**
+```
+"done"
+```
+
+**Wrapped:**
+```json
+{
+  "schema_version": "mcp.envelope.v0.1",
+  "result": "done"
+}
+```
+
+### 9.3 Tool Already Returns Envelope
+
+**Input:**
+```json
+{
+  "schema_version": "mcp.envelope.v0.1",
+  "result": { ... },
+  "provenance": { ... }
+}
+```
+
+**Output:** Return unchanged.
+
+---
+
+## 10. References
+
+- `mcp.envelope.schema.v0.1.json`: Envelope schema
+- `mcp.request.schema.v0.1.json`: Request schema
+- `prov.record.schema.v0.1.json`: Provenance record schema
+- `artifact.ref.schema.v0.1.json`: Artifact reference schema