Conventions
The cross-package contracts contributors must preserve.
Repository-wide engineering contracts live in the small
cross-package invariant set.
Package-specific rules belong in the nearest CONTEXT.md.
Product language
Consumer APIs speak in Accounts, Organizations, Money, Payments, recipients, destinations, and documents. Custody and provider substrate does not replace those product concepts. Check the domain glossary before adding a public term.
Public and wire boundaries
- Packed exports, not workspace-only exports, define the installable surface.
- Public SDK calls resolve to
CapxulResult<T>rather than leaking Effect programs or internal failures. - Untrusted input is parsed at the boundary; a cast is not validation.
- Wire shapes explicitly remove secret material, provider payloads, raw custody objects, and internal evidence.
- Public money uses
Money; raw chain units stay at settlement and evidence boundaries.
Authorization and scope
Authentication, application consent, and Organization Permission authority are different checks. Passing one does not imply the others. Organization scope is explicit; the SDK does not maintain a mutable global active Organization.
Tests and evidence
Use the proof ladder in development and verification: static, hermetic, package, integration, live, then visual. A lower rung must not be described as a higher one.
Start work with a behaviorally meaningful failing test, keep mocks at system
boundaries, and preserve the observable contract when consolidating tests.
Run all gate-shaped commands through vp.
Documentation impact
When a PR changes responsibility, interface, behavior, evidence, or operator meaning, update its local context and every affected canon, ADR, operation, or public projection in the same PR. Moving or deleting prose requires a reviewed disposition and a surviving owner.