# Contributing to Agent Passport System

Thanks for your interest in contributing to the Agent Passport System! This project implements an open protocol for AI agent identity, trust, governance, and commerce.

## Getting Started

1. Fork the repository
2. Clone your fork: `git clone https://github.com/<your-username>/agent-passport-system.git`
3. Install dependencies: `npm install`
4. Run the test suite: `npm test`

## Development

The SDK is organized into 8 protocol layers plus 23 v2 constitutional modules. See `ARCHITECTURE.md` for the full layer-to-file-to-test mapping.

### Running Tests

```bash
npm test
```

All 4,026 tests across 913 suites (3 skipped) must pass before submitting a PR. TypeScript strict mode must compile clean.

To see line/branch/function coverage, run:

```bash
npm run test:coverage
```

This uses Node's built-in `--experimental-test-coverage` flag, no separate
coverage tool or third-party account needed.

### Reproducible builds

The TypeScript build is reproducible: given the committed lockfile, `npm ci` followed by `npm run build` produces a bit-for-bit identical `dist/` tree on repeated runs. The toolchain is pinned by `package-lock.json`. To verify, build twice and compare:

```
npm ci && npm run build
find dist -type f | sort | xargs sha256sum | sha256sum
rm -rf dist && npm run build
find dist -type f | sort | xargs sha256sum | sha256sum

```

The two hashes must match (macOS ships `shasum -a 256` instead of `sha256sum`). Rust components build from the committed `Cargo.lock`.

### Code Style

- TypeScript throughout
- Ed25519 signing and SHA-256 hashing via the Node standard library (`node:crypto`)
- Runtime dependencies are held to two: `libsodium-wrappers` (encrypted messaging) and `uuid`. Do not add more.

## Submitting Changes

1. Create a feature branch from `main`
2. Make your changes with clear, descriptive commits
3. Ensure all tests pass (`npm test`) and `tsc --noEmit` is clean
4. Open a pull request with a description of what you changed and why

## Code review

Every external pull request is reviewed by the maintainer before merge. What review checks, in order:

1. The failing test exists and fails without the change (for fixes), or tests cover the new behavior (for features).
2. The change is minimal: no scope expansion, no drive-by refactors.
3. `npm test` and `npx tsc --noEmit` pass.
4. Security-sensitive paths get line-by-line review: anything touching cryptography, canonical byte forms, signature verification, or delegation narrowing. Changes here may also require new conformance or adversarial fixtures before they are acceptable.
5. Public API changes require documentation updates in the same PR.

Acceptance means all five hold. A change that is useful but out of scope is redirected, not expanded in place.

Beyond the checklist, every PR is evaluated against five questions, applied to every contributor equally:

1. **Identity.** Is the contributor identifiable, with a real GitHub presence?
2. **Format.** Does the change match existing patterns (module layout, naming, error handling, test density)?
3. **Substance.** Do tests actually exercise the claimed behavior?
4. **Scope.** Does the PR stay scoped to its stated purpose?
5. **Reversibility.** Can the change be reverted cleanly if a downstream issue surfaces?

Substantive declines include the reason. Review comments aim to be concrete and actionable.

## Reporting Issues

Open an issue on GitHub with:

- A clear title and description
- Steps to reproduce (if applicable)
- Expected vs actual behavior
- Your environment (Node.js version, OS)

## Protocol Contributions

If you're proposing changes to the protocol itself (new layers, modified signature schemes, governance changes), please open a discussion issue first so we can align on the design before implementation.

---

## Quick start checklist

**For a bug fix:**
1. A failing test that reproduces the bug (added in the existing test suite where it logically belongs)
2. The minimal fix that makes the test pass without breaking other tests
3. No scope expansion — fix the bug, don't refactor adjacent code in the same PR

**For a feature addition:**
1. Issue first — get a thumbs-up on direction before sinking work into a PR
2. Tests cover the new behavior at the same density as adjacent code
3. No breaking changes to published API without a major version bump and migration note
4. TypeScript strict mode compiles clean
5. Format consistent with adjacent modules (naming, error handling, test density)

**For documentation:** straight PR is fine. No issue needed first.

## What makes a PR mergeable

1. **Tests pass** — `npm test` green, count stays at or above current level
2. **TypeScript clean** — strict mode, no new `any` in public surface
3. **API stability** — no breaking changes to published exports without a major version bump
4. **Format consistency** — matches existing module layout, naming, error handling
5. **Scope discipline** — PR stays focused on its stated purpose; refactors ride alongside in separate PRs

## Stability expectations

The SDK follows semantic versioning. Changes to public API surface require a major version bump with migration notes. Internal refactors can land in patch releases. Three new primitives shipping per month is normal velocity; each arrives with tests and documentation together.

## Out of scope

- **Breaking changes to published API surface** without major version bump and migration documentation
- **New signature algorithms in core identity primitives** (Ed25519 is load-bearing). Alternative algorithms can ride alongside via extension, not replace
- **Vendored dependencies or large binary artifacts** without specific justification
- **Named integrations woven into core module exports** — integration code belongs in `INTEGRATION.md`, `examples/`, or a sibling adapter repo
- **Disabling tests** without a documented reason

---

## Practical details

- **Maintainer:** [@aeoess](https://github.com/aeoess) (Tymofii Pidlisnyi)
- **Review timing:** maintainer-bandwidth dependent. If a PR has had no response after 5 business days, ping it — the notification may have been missed.
- **CLA / DCO:** no CLA. The project uses the Developer Certificate of Origin (developercertificate.org): every commit must carry a Signed-off-by line asserting you have the right to contribute it under Apache-2.0 (use `git commit -s`). CI enforces this on pull requests.
- **Publishing:** maintainers handle npm release publishing. Please do not bump version numbers in PRs. If your change requires a version bump, call that out in the PR description so we can sequence the release.
- **Security issues:** open a private security advisory via GitHub rather than a public issue.
- **Code of Conduct:** Contributor Covenant 2.1 — see [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md).

---

## Licensing

Apache License 2.0 (see [`LICENSE`](./LICENSE)). By contributing, you agree that your contributions will be licensed under the project's existing license.
