Contributing to Pulse

Source e69e4b6f1381 · Published v1.0.0-beta.10

These pages cover Pulse repository maintenance and the supported contracts for trusted package lowerers and explicitly selected provider toolchains. Application authors should start with the package guides.

Before changing a shared boundary, consult the Architecture contracts for ownership rules and invariants.

Contributor workflow

Choose the owning contract and read the root and nearest AGENTS.md. Use the architecture overview when ownership is unclear.
Classify the change with the scope policy. That page owns the PR declaration and protected-boundary rules. Obtain human direction before widening a contract; record existing direction in the PR.
Make the smallest coherent change in canonical sources. For documentation, use the documentation update loop to regenerate installed copies and references.
Run npm run maintainer:check and the focused checks selected for the diff. Testing Pulse owns task selection, dependency requirements and evidence rules. Ordinary changes do not require a local aggregate release seal.
Open a PR with the scope declaration, what changed, checks completed, and any dependency-bound checks still outstanding. Include the tested revision and working-tree state; an interrupted check is incomplete evidence.

Use the repository-pinned Node and pnpm versions and restore the frozen lockfile with lifecycle scripts disabled before dependency-bound checks. The release manifest owns the supported package and target set. Human maintainers retain merge, settings and release authority.

Choose the extension boundary

Pulse-aware package authoring — ordinary JavaScript packages, bounded package-root Native lowering, trusted builders, and the separate scoped-provider boundary.

Package-owned lowering

Package lowerer contract reference — manifest fields, builder protocol, effect shape, trust rules, and release invariants.
Add a first-party package-owned lowerer — end-to-end implementation tutorial using the GRIP/assets pattern.
Entities lowering maintainer reference — static extraction, schema authority, Native realization, catalog, and seal invariants for the Entities package.

Providers

Add a provider toolchain — descriptor, bindings, runtime, target, namespace bootstrap, diagnostics, docs, and tests.

Repository context

Declared lowerer builders execute as trusted build dependencies, including external packages admitted through the versioned contract. This is not a sandbox. Built-in provider shorthand is release-owned, while an exact scoped project provider may export the versioned ./toolchain contract without self-registration or dependency scanning. Changes that widen either executable trust boundary require an explicit security and compatibility design, not only another manifest or package export.