Update a library deliberately

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

An exact identity tells you which content changed. It does not decide whether the new version is compatible with its callers or saved state.

1. Establish the current expectation

Read library.toml to identify the reusable library and consumers. Record the behaviour you intend to change and the consumers expected to observe it.

Run the current checks before editing:

effectful verify ./pricing
effectful test ./pricing

An existing failure needs a clear disposition. Otherwise a later test result cannot tell you whether your change introduced it.

2. Edit the owning source

Change the library under pricing/packages/pricing/. Review exported types, function signatures and effect requirements as well as function bodies.

For a rule change, keep the intended result independent of the implementation. If your agent changes the tests, ask it to explain why each expectation changed.

3. Check every declared consumer

effectful verify ./pricing
effectful test ./pricing

Verification captures and checks the declared consumer graphs. Testing checks their cases. A consumer omitted from the project descriptor is not covered simply because it exists elsewhere in your repository.

You can use a selected test for fast diagnosis:

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

That result covers the selected case. Run the broader suite before drawing a broader conclusion.

4. Inspect evidence after the change

If you retained graph-test evidence for a consumer, compare it with the current graph using code evidence. Changed relevant components make an observation stale; missing execution context can make applicability unknown.

Use a new receipt path for fresh evidence. Keep old observations as historical evidence instead of rewriting them to describe the new source.

5. Assess activation and state compatibility

A green test suite does not automatically make a schema change safe for existing actors. Review saved-state compatibility, in-flight operations and any required conversion.

In the library watch workflow, compatible green edits can become the active consumer selection while the last accepted selection keeps serving through refused edits. That activation rule has a defined scope; it is not a general live-migration promise for arbitrary state changes.

Use the consumer watch guide to observe a refused edit followed by an accepted one on the local listener.

6. Review dependency and native boundaries

An installed package update selects an explicit new identity. Do not edit immutable package bytes in place. If the library’s native oracle or adapter changed, run the separate native checks as well.

Keep the selected identity, changed contract and applicable evidence together so a reviewer can see what the update means for the system that consumes it.