Status

Stability

Puffball declares source version 0.2.0. Until 1.0, a minor release can change the public API, so pin the version you test against.

Package qualification does not publish a release. Check the npm registry before choosing a released version.

Limits and errors

• The default artifact policy accepts artifacts up to 65,536 bytes. Pass artifactPolicy: { maxBytes, maxManifestBytes } to createAppReleaseCatalog to change it.
• Every failure is a named error class exported from the root, such as AppReleaseInputError, AppReleaseImmutableConflictError, AppReleaseArtifactDigestMismatchError, AppReleaseTransitionReleaseUnverifiedError, AppReleaseTransitionIdempotencyConflictError, AppReleasePublicWebsiteNotFoundError and AppReleasePublicWebsiteUnavailableError.
• A store that returns a malformed result causes AppReleaseInvalidStoreResultError. An unreachable store causes AppReleaseStoreUnavailableError.
• The catalog does not deploy, configure domains, build from source or publish. Those stay with your host.

Contribute and license

MIT. See LICENSE.

@fungi.computer/puffball/app-event-facts owns the canonical App EventSink input and saved host-fact decoders. git-representation owns repository-name, SHA-1, ref-update and push-event-id schemas shared with Agar. These decode representations; they do not admit callers or grant Git access.

Background work uses @fungi.computer/puffball/background-replay. A host calls backgroundContext with the verified method name/effect, actual invocation ancestry and a host-sealed backgroundOrigin. An App checks mayEnqueueBackground on that host-supplied context and retains the origin with the accepted job; a replay never gets enqueue eligibility. Agents, keys, Workflow nodes and nested calls keep their work in the foreground. A wake retains only the member identity and observed revisions. readmitBackground resolves the member and re-admits the declared backend.sync.method on every delivery. That ordinary write method must cover every write method’s capability requirements. An unavailable installation is a host dead letter; a still-available refused lane may receive syncRefused with no binding grants.

The host derives its non-extractable signing key with backgroundOriginKey and seals the Instance, member lane and verified foreground method with sealBackgroundOrigin. In a replay, BACKGROUND.admit checks the claimed job’s retained origin against freshly admitted methods. Each frame permits one check: other capability effects wait for its admitted decision, while APP_STORAGE remains available for claiming and settling. A refused claim returns {kind: "refused", code: "access_changed"} before those effects; the App cannot declare the host-only BACKGROUND binding.