Skip to content

AGENTS.md

Latest commit

 

History

History
88 lines (69 loc) · 3.81 KB

AGENTS.md

File metadata and controls

88 lines (69 loc) · 3.81 KB
Raw

AGENTS.md: capsule

Capsule Protocol Specification (CPS) plus reference implementations. Open source, Apache 2.0 with patent grant. The spec in spec/ is the source of truth, not any single implementation.

Stack

  • Spec: spec/ plus conformance/ (16 valid + 15 negative golden vectors). Language-agnostic.
  • Python reference: reference/python/ publishes qp-capsule on PyPI. Python 3.11+, pynacl, hatchling.
  • TypeScript reference: reference/typescript/ publishes @quantumpipes/capsule on npm. TypeScript 5.9+ strict, Node 20.19+, ESM-only.
  • Ecosystem libraries (not in this repo): capsule-go, capsule-litellm.

Commands

Python (always cd reference/python first):

make install      # pip install -e ".[storage,dev]"
make lint         # ruff check src/ tests/
make typecheck    # mypy src/qp_capsule/ (strict)
make test         # pytest, 100% coverage enforced (--cov-fail-under=100)
make test-golden  # golden conformance vectors only
make test-all     # lint + typecheck + test + golden

TypeScript (always cd reference/typescript first):

npm ci
npm run lint         # tsc --noEmit
npm test             # vitest run
npm run conformance  # golden fixtures only

Structure

spec/                  CPS v1.0 specification, URI scheme, VERSION
conformance/           golden vectors every implementation must pass
reference/python/      qp-capsule (src/, tests/, Makefile, pyproject.toml)
reference/typescript/  @quantumpipes/capsule (src/, tests/, package.json)
docs/                  architecture, security, 11 compliance mappings
examples/              language-agnostic example Capsules
nist-submission/       NIST materials

Style

  • No em dashes anywhere in code, commits, or docs. Use commas, periods, colons, parentheses.
  • Python: type hints on all public functions, async where I/O happens, mypy strict, filterwarnings = ["error"] (any new warning fails CI).
  • TypeScript: strict mode, ESM-only (.js extensions in imports).
  • Crypto allowlist: SHA3-256 (FIPS 202), Ed25519 (FIPS 186-5), ML-DSA-65 (FIPS 204), AES-256-GCM (FIPS 197). Never MD5, SHA1, SHA2, RSA, ECDSA-P256, 3DES, RC4.

Canonical seal (Python):

from qp_capsule import Capsule, Seal, CapsuleType, TriggerSection
c = Capsule(type=CapsuleType.AGENT, trigger=TriggerSection(source="bot", request="deploy"))
seal = Seal(); seal.seal(c); assert seal.verify(c)

Git workflow

  • Conventional commits with scope: feat(spec): ..., fix(python): ..., docs(compliance): ....
  • Never include Co-Authored-By, Generated by, or any AI attribution.
  • Protocol changes to spec/ go through the CPS change proposal process (rare, requires spec-change issue plus updated golden vectors in the same PR).
  • Implementation PRs must keep every golden vector green in every reference language.

Boundaries

Always:

  • Run make test-all (or npm test) in the affected reference before committing.
  • Keep canonicalize() byte-identical across languages for the same input.
  • Update conformance/ vectors together with any spec change, same commit.

Ask first:

  • Any change to spec/ (the protocol itself).
  • Adding a dependency to a reference implementation.
  • Adding a new reference language (open a new-implementation issue first).

Never:

  • Break the 16 golden vectors. Regenerate only via make golden-regenerate after an approved spec change.
  • Introduce deprecated cryptography (see Style).
  • Add runtime network dependencies. Air-gap compatibility is a protocol invariant.
  • Change to_dict() or canonicalize() output in one implementation without matching changes in the others.

Related