Not released yet. PeltyCMS is under development and not released yet; these docs describe the upcoming release and may change.
PeltyCMS Developer docs
User docsDevelopers
/
v0.1.0

Developer docs/Guides

Addon SDK and ABI compatibility

Compatibility has several independent layers. Do not use an SDK version, addon version, signature, or passing fixture as a substitute for host compatibility.

Related guides: local testing, security review, and signed releases.

#Public SDK version identifiers

pelty-addon-sdk exposes these &str constants:

| Constant | Contract | | --- | --- | | SDK_VERSION | env!("CARGO_PKG_VERSION"): the SDK Rust crate's version inherited from the addon workspace; currently 0.1.0 | | WIT_PACKAGE_VERSION | 0.2.0: the generic bindings' pelty:addon WIT package identity | | ABI_VERSION | 0.5.0: latest manifest ABI feature level documented by this SDK, not an automatic minimum host or a negotiation result | | BASE_ABI_VERSION | 0.2.0: baseline generic addon manifest ABI | | CRON_ABI_VERSION | 0.5.0, available with SDK feature cron: minimum manifest feature level for the scheduled export |

These constants are informational Rust API. They do not update addon.json, embed capability approval, generate a compatibility range, or add runtime negotiation. There is no promise that every SDK feature works with a host merely because the manifest ABI was accepted. pelty-wasm::ABI_VERSION refers to the separate legacy captcha world (0.1.0); the generic runtime's identifier is pelty_wasm::runtime::ABI (0.5.0). Do not confuse them.

#Current generic host behavior

The generic runtime parses the manifest abi with strict semver::Version::parse and applies this compatibility policy:

Publish complete major.minor.patch strings, optionally with valid build metadata. ABI acceptance is followed by component linking, descriptor parsing and capability/limit checks, any of which can still fail.

| Manifest feature level | Additions | | --- | --- | | 0.2 | Generic describe, JSON call, on-event, host services and kind-specific wire adapters | | 0.3 | Lifecycle phases, custom events and mixins | | 0.4 | Call context, filters and core-function mixins | | 0.5 | Optional scheduled / on-cron export and cron jobs |

The additive generations retain WIT package identity pelty:[email protected]. The current host is intended to keep older components linking, rather than force recompilation of all old releases. The inverse is not guaranteed: rebuilding an old manifest with a new SDK can introduce imports unavailable on an older host. The cron feature selects the pelty-addon-cron world instead of the baseline pelty-addon world. Test the actual built component against the oldest host you intend to support and declare its required manifest feature level honestly.

Gateway/provisioning JSON is part of the wire contract as well as WIT. Use the shared pelty-payments::wire / pelty-provisioning::wire serializers, exact money strings, and structured error prefixes. Do not reinterpret unknown operations as success. Some optional provisioning operations (list_accounts, catalog) have explicit older-addon fallbacks; this is not a universal unknown-op policy.

#Semver policy and limits of the guarantee

The SDK is currently pre-1.0 and workspace-versioned, not a separately released stable platform. Use Cargo's pre-1.0 interpretation: compatible 0.1.x patch updates must preserve documented public Rust signatures, existing macro use, existing supported wire meanings and baseline exports; incompatible changes require the next minor (0.2.0), not a patch. After 1.0, those incompatible changes require a major. Additive optional APIs and bug fixes may be compatible, but new imports/exports must declare and test a suitable host feature level. Do not claim long-term support or a fixed support window that has not been published. Pin the SDK and shared dependency revisions/lockfile for reproducible builds; source compatibility does not guarantee identical WASM bytes.

This is the maintenance rule for the SDK's documented public surface, not a retroactive blanket stability claim for all internal code or generated wit-bindgen implementation details. Separate version changes are required for a breaking manifest/WIT/wire contract; changing the Rust crate version alone does not make an old host understand it. Conversely, retaining an ABI string does not justify changing the meaning of old fields or error codes incompatibly.

No SDK compatibility promise covers provider REST changes, addon business logic, credentials, operator approvals/limits, schema/data migrations, all CPU/OS/compiler combinations, or application API compatibility. Package signatures establish identity/integrity, not compatibility or an anti-rollback policy.

#Deprecation and removal rules

1. Identify the public symbol/operation/field, reason, replacement, affected SDK and ABI generations, and migration example in release notes and this contract. Use Rust #[deprecated(since = "...", note = "...")] where applicable. 2. Keep the old behavior available through the remainder of its compatible SDK line. Do not remove or silently repurpose it in a patch, and do not use a new default to bypass this rule. Retain regression coverage for old inputs. 3. Remove a Rust API only at the next allowed breaking SDK boundary (pre-1.0 minor, post-1.0 major), after publishing the replacement and removal release. No calendar grace period is implied. If no removal release is decided, say so. 4. Removing a WIT import/export or breaking JSON behavior also requires an explicit incompatible ABI strategy and host compatibility documentation. Old component support may be dropped only in a deliberately documented host breaking release, not as an incidental SDK cleanup. Re-test retained ABI lines. 5. Urgent security fixes may restrict unsafe behavior sooner. Publish the risk, affected versions and required operator action explicitly; do not describe security tightening as an unconditional backwards-compatibility guarantee.

For every release, record the SDK revision, manifest ABI, oldest/newest tested hosts and compiler target, retain package hashes, run the relevant offline fixtures, and test real upgrade/retry paths separately. Parent application owners define trust/activation and migration upgrade policy; this SDK document does not implement or assert those controls.