Skip to content

Commit 2a43d7b

Browse files
bradleygauthierbradleygauthier
committed
Initial: Capsule Protocol Specification v1.0.0
0 parents  commit 2a43d7b

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+13186
-0
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
name: Bug Report
3+
about: Report a bug in Capsule or the CPS reference implementation
4+
title: "[Bug] "
5+
labels: bug
6+
assignees: ''
7+
---
8+
9+
## Describe the Bug
10+
11+
A clear description of what the bug is.
12+
13+
## To Reproduce
14+
15+
Steps to reproduce the behavior:
16+
17+
1. Install with `pip install qp-capsule...`
18+
2. Run this code:
19+
20+
```python
21+
# Minimal reproducer
22+
```
23+
24+
3. See error
25+
26+
## Expected Behavior
27+
28+
What you expected to happen.
29+
30+
## Actual Behavior
31+
32+
What actually happened. Include the full traceback if applicable.
33+
34+
## Environment
35+
36+
- **OS**: (e.g., macOS 15, Ubuntu 24.04)
37+
- **Python**: (e.g., 3.12.1)
38+
- **Capsule version**: (e.g., 1.0.0)
39+
- **Install extras**: (e.g., `[storage]`, `[pq]`)
40+
41+
## Additional Context
42+
43+
Any other context about the problem.

‎.github/ISSUE_TEMPLATE/cps_change.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
name: CPS Protocol Change
3+
about: Propose a change to the Capsule Protocol Specification itself
4+
title: "[CPS] "
5+
labels: protocol
6+
assignees: ''
7+
---
8+
9+
## Summary
10+
11+
One-sentence description of the proposed protocol change.
12+
13+
## Motivation
14+
15+
Why is this change needed? What problem does it solve at the protocol level?
16+
17+
## Specification Change
18+
19+
Describe the exact change to CPS. Which section(s) of the spec are affected?
20+
21+
## Backward Compatibility
22+
23+
- Does this break existing Capsules? (sealed records must remain verifiable)
24+
- Does this break existing implementations? (SDK authors must update)
25+
- Does this change canonical JSON output? (golden fixtures must be updated)
26+
27+
## Golden Fixture Impact
28+
29+
- [ ] Existing golden fixtures still pass
30+
- [ ] New golden fixtures are needed
31+
- [ ] Existing golden fixtures produce different output (BREAKING)
32+
33+
## References
34+
35+
Links to related issues, discussions, or external standards.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
name: Feature Request
3+
about: Suggest an enhancement to Capsule
4+
title: "[Feature] "
5+
labels: enhancement
6+
assignees: ''
7+
---
8+
9+
## Problem
10+
11+
What problem does this solve? What use case is not currently supported?
12+
13+
## Proposed Solution
14+
15+
Describe your preferred approach.
16+
17+
## Alternatives Considered
18+
19+
What other approaches did you consider? Why were they rejected?
20+
21+
## Additional Context
22+
23+
Any other context, screenshots, or references.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
## Summary
2+
3+
What does this PR do? Link to any related issues.
4+
5+
## Type of Change
6+
7+
- [ ] Bug fix (non-breaking change that fixes an issue)
8+
- [ ] New feature (non-breaking change that adds functionality)
9+
- [ ] Breaking change (fix or feature that changes existing behavior)
10+
- [ ] Protocol change (modifies the CPS specification)
11+
- [ ] Documentation update
12+
- [ ] Test improvement
13+
14+
## Checklist
15+
16+
- [ ] Tests pass (`pytest tests/`)
17+
- [ ] Linter passes (`ruff check src/ tests/`)
18+
- [ ] Type checker passes (`mypy src/qp_capsule/`)
19+
- [ ] Golden fixtures still pass (`pytest tests/test_golden_fixtures.py`)
20+
- [ ] Documentation updated (if applicable)
21+
- [ ] CHANGELOG.md updated (if user-facing change)
22+
23+
## Protocol Impact
24+
25+
Does this PR change the Capsule Protocol Specification?
26+
27+
- [ ] No protocol impact (implementation only)
28+
- [ ] Protocol change (requires CPS version bump and golden fixture update)

‎.github/dependabot.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: "pip"
4+
directory: "/"
5+
schedule:
6+
interval: "weekly"
7+
labels:
8+
- "dependencies"
9+
commit-message:
10+
prefix: "deps"
11+
12+
- package-ecosystem: "github-actions"
13+
directory: "/"
14+
schedule:
15+
interval: "weekly"
16+
labels:
17+
- "dependencies"
18+
commit-message:
19+
prefix: "ci"

‎.github/workflows/ci.yaml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
lint:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
17+
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
18+
with:
19+
python-version: "3.12"
20+
- run: pip install ruff
21+
- run: ruff check src/ tests/ specs/
22+
23+
typecheck:
24+
runs-on: ubuntu-latest
25+
steps:
26+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
27+
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
28+
with:
29+
python-version: "3.12"
30+
- run: pip install -e ".[storage,dev]"
31+
- run: mypy src/qp_capsule/
32+
33+
test:
34+
runs-on: ubuntu-latest
35+
strategy:
36+
matrix:
37+
python-version: ["3.11", "3.12", "3.13", "3.14"]
38+
steps:
39+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
40+
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
41+
with:
42+
python-version: ${{ matrix.python-version }}
43+
allow-prereleases: true
44+
- run: pip install -e ".[storage,dev]" pytest-cov
45+
- run: pytest tests/ -v --tb=short --cov=qp_capsule --cov-fail-under=100
46+
47+
test-golden:
48+
runs-on: ubuntu-latest
49+
steps:
50+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
51+
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
52+
with:
53+
python-version: "3.12"
54+
- run: pip install -e ".[storage,dev]"
55+
- run: pytest tests/test_golden_fixtures.py -v

‎.github/workflows/release.yaml‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- "v*"
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
test:
13+
name: Test
14+
runs-on: ubuntu-latest
15+
strategy:
16+
matrix:
17+
python-version: ["3.11", "3.12", "3.13"]
18+
steps:
19+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
20+
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
21+
with:
22+
python-version: ${{ matrix.python-version }}
23+
- run: pip install -e ".[storage,dev]"
24+
- run: pytest tests/ -v --tb=short
25+
- run: pytest tests/test_golden_fixtures.py -v
26+
27+
build:
28+
name: Build Package
29+
runs-on: ubuntu-latest
30+
needs: test
31+
steps:
32+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
33+
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
34+
with:
35+
python-version: "3.12"
36+
- run: pip install build
37+
- run: python -m build
38+
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
39+
with:
40+
name: dist
41+
path: dist/
42+
43+
publish:
44+
name: Publish to PyPI
45+
runs-on: ubuntu-latest
46+
needs: build
47+
permissions:
48+
id-token: write
49+
environment:
50+
name: pypi
51+
url: https://pypi.org/p/qp-capsule
52+
steps:
53+
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
54+
with:
55+
name: dist
56+
path: dist/
57+
- uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # release/v1
58+
59+
github-release:
60+
name: GitHub Release
61+
runs-on: ubuntu-latest
62+
needs: publish
63+
permissions:
64+
contents: write
65+
steps:
66+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
67+
- name: Extract version from tag
68+
id: version
69+
run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
70+
- name: Create GitHub Release
71+
uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2
72+
with:
73+
generate_release_notes: true
74+
body: |
75+
## Capsule ${{ steps.version.outputs.VERSION }}
76+
77+
See [CHANGELOG.md](https://github.com/quantumpipes/capsule/blob/main/CHANGELOG.md) for details.
78+
79+
### Install
80+
81+
```bash
82+
pip install qp-capsule==${{ steps.version.outputs.VERSION }}
83+
```

‎.gitignore‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Python
2+
__pycache__/
3+
*.py[cod]
4+
*.egg-info/
5+
dist/
6+
build/
7+
*.egg
8+
9+
# Virtual environments
10+
.venv/
11+
venv/
12+
13+
# Testing
14+
.pytest_cache/
15+
.coverage
16+
htmlcov/
17+
18+
# Linting
19+
.ruff_cache/
20+
21+
# mypy
22+
.mypy_cache/
23+
24+
# IDE
25+
.idea/
26+
.vscode/
27+
*.swp
28+
*.swo
29+
30+
# OS
31+
.DS_Store
32+
Thumbs.db
33+
34+
# Database (generated at runtime)
35+
*.db

‎CHANGELOG.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Changelog
2+
3+
All notable changes to Capsule are documented in this file.
4+
5+
Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
6+
Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
---
9+
10+
## [1.0.0] - 2026-03-07
11+
12+
Initial public release of the Capsule Protocol Specification (CPS) v1.0 reference implementation.
13+
14+
### Added
15+
16+
- **Capsule model** with 6 mandatory sections: Trigger, Context, Reasoning, Authority, Execution, Outcome
17+
- **8 Capsule types**: agent, tool, system, kill, workflow, chat, vault, auth
18+
- **Cryptographic sealing**: SHA3-256 (FIPS 202) + Ed25519 (FIPS 186-5)
19+
- **Post-quantum dual signatures**: optional ML-DSA-65 (FIPS 204) via `pip install qp-capsule[pq]`
20+
- **Hash chain**: tamper-evident linking with sequence numbers and `previous_hash`
21+
- **CapsuleStorageProtocol**: runtime-checkable `typing.Protocol` for custom storage backends
22+
- **SQLite storage**: zero-config persistence via `pip install qp-capsule[storage]`
23+
- **PostgreSQL storage**: multi-tenant isolation via `pip install qp-capsule[postgres]`
24+
- **Pre-execution reasoning capture**: Section 3 (Reasoning) written before Section 5 (Execution)
25+
- **ReasoningOption.rejection_reason**: mandatory explanation for non-selected options
26+
- **Key management**: auto-generated keys with `0600` permissions, umask-based creation
27+
- **Cross-language interoperability**: canonical JSON serialization rules and 15 golden test vectors covering Unicode, fractional timestamps, all CapsuleTypes, chain sequences, deep nesting, failure paths
28+
- **Documentation**: getting-started, architecture, API reference, security evaluation, compliance mapping, CPS specification summary
29+
- **350 automated tests** across 14 test files with **100% code coverage** enforced in CI
30+
- **CPS v1.0 specification** shipped with the repo at `specs/cps/`
31+
- **Apache 2.0 license** with additional patent grant
32+
33+
### Security
34+
35+
- Ed25519 signatures required on every Capsule
36+
- SHA3-256 chosen over SHA-256 for length-extension resistance
37+
- Key files created with restrictive umask (no TOCTOU race)
38+
- ML-DSA-65 uses FIPS 204 standardized name
39+
- Zero runtime network dependencies (air-gapped operation)
40+
- `filterwarnings = ["error"]` with zero exemptions — any warning is a test failure
41+
- 100% test coverage enforced (`fail_under = 100`)
42+
43+
---
44+
45+
[1.0.0]: https://github.com/quantumpipes/capsule/releases/tag/v1.0.0

0 commit comments

Comments
 (0)