[magnus-madsen]

Adds src/locking-effects.md under Projects and Packages, between Trusting Dependencies and Publishing a Package. The book did not mention the eff-lock and eff-check commands or the effects.lock file.

The chapter

• Opens with a note that effect locking is an experimental feature, in the style of the Polymorphic Effects and Type-Level Programming chapters.
• Why we lock: a new version of a package may add an effect to a function we call, and only rereading every signature after every upgrade would catch it.
• eff-lock: the command, the effects.lock file it writes, and what it covers (every installed package, not the bundled library or our own code; nothing is locked if the project does not type check).
• eff-check: the clean report, the changed-signature warning and what to do about it, and that the command exits with status 1 on a change.
• Locking one package at a time, and how a named package replaces only its own section.
• How packages.lock and effects.lock differ, and why only the latter survives an upgrade.
• Why the lock rests on the security context, and why it is most informative for libraries that declare their own effects.

Other changes

• SUMMARY.md lists the chapter.
• trusting-dependencies.md points to the chapter after the paragraph on reading signatures.
• versions-and-upgrades.md notes the second lock file after the section on packages.lock.

Verification

• Every transcript is from a build of Flix master at f80f624, which includes fix: lock a declaration by its name inside its package flix#13500, in a scratch project depending on flix/museum-giftshop 2.0.2. Flix 0.78.0 prints the same output for every command, but writes the package id into each effects.lock key, so the excerpt matches master rather than 0.78.0.
• No museum release has ever changed a public signature (every function is Unit -> Unit \ IO, and museum 3.0.1 → 3.0.2 → 4.0.0 all check clean), so the warning transcript was produced by altering one hash in the lock file. The prose frames it as a hypothetical (locked pure, now IO) so that the printed def buyGift(): Unit \ IO is what the tool prints.
• eff-check exits 1 on a change and 0 otherwise; both commands refuse to run without flix.toml.
• mdbook build succeeds and all links on the new page resolve.

The effects.lock excerpt uses the key spelling introduced by flix/flix#13500, which is not in 0.78.0.

🤖 Generated with Claude Code