Browse documentation

How-to guides

Update a library

Check consumers and compatibility when changing reusable code.

Use this procedure for a library project with declared consumers. Commands use pricing from the library tutorial.

1. Check the baseline

Read library.toml for the library and consumer list. State the intended behaviour change, then run:

effectful verify ./pricing
effectful test ./pricing

Resolve or record existing failures before editing.

2. Edit the library

Change source under pricing/packages/pricing/. Review exported types, signatures and effects as well as function bodies. Update test expectations only when the requirement justifies the new result.

3. Check the consumers

effectful verify ./pricing
effectful test ./pricing

These commands cover declared consumers. They do not cover an application omitted from the descriptor.

For diagnosis, select one case:

effectful test ./pricing --consumer example --case scaled

Run the broader suite before making a broader claim.

4. Check evidence and compatibility

Use code evidence to compare recorded consumer test results with current inputs. Relevant changes make results stale; missing provenance can make applicability unknown. Use new receipt paths for fresh execution.

A passing suite does not establish saved-state compatibility. Review in-flight operations, state conversions and activation rules. The watch guide demonstrates compatible activation and a refused edit.

5. Update the selected identity

An installed package update selects a new content identity. Do not change immutable package bytes in place. Run separate native checks if the oracle or adapter changed.

Retain the selected identity, contract change and evidence with the review. Content addressing identifies the update; it does not decide compatibility.

Search concepts, guides and reference.