Skip to content

feat(build): keep each distinct built module once in the artifact store - #887

Draft
raymondk wants to merge 3 commits into
mainfrom
feat/dedup-artifact-store
Draft

raymondk wants to merge 3 commits into
mainfrom
feat/dedup-artifact-store

Conversation

@raymondk

@raymondk raymondk commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Intent

Stop .icp/cache/artifacts holding a full copy of the same WASM for every canister built from it. On a memory-backed disk each copy is RAM.

Supersedes #883, which reached the same goal by having the store record a link to a pre-built module's source file. This takes the other route: the store still owns its bytes, but owns each distinct module once.

What changed

The store's layout, inside ArtifactStore only:

.icp/cache/artifacts/
├── .modules/<sha256>.wasm    one per distinct module
└── .refs/<canister>          the SHA-256 of that canister's module
  • save hashes the bytes, writes the module only if it is not already there (to a .partial file, then renamed into place), and writes the canister's ref.
  • lookup reads the ref, then the module. A missing ref, a ref that is not a SHA-256 (non-text bytes included), or a ref whose module is gone all read as "not built", and a rebuild replaces it.
  • The two directories start with ., which a canister name cannot contain, so neither can collide with an artifact file an earlier version left for a canister.
  • When a save repoints a canister, the module it replaced is removed if no other ref names it.
  • The store_artifact::Access seam, the in-memory mock, and every caller (build, install, candid check, bundle, canister call) are unchanged.

Compared with #883

main this PR #883
N canisters on one module, copies in .icp N 1 0
Identical output from script builds shared no yes no
.icp self-contained yes yes no
Install refused when the source file changed after build n/a n/a yes
Seam changes — none Build returns Module, new Access::link

What this does not do, and #883 did: a pre-built step still copies its module to the scratch directory, and build still reads it into memory before saving. That copy is transient (it goes when the build ends). Removing it needs the build step to hand back a path instead of writing to the output, which can follow separately without the link or the install-time check.

Behaviour to know about

  • Artifacts written by an earlier version are not read. After upgrading, icp canister install reports a canister as not built until icp build (or icp deploy) has run. The old files are left in place and not read; nothing in the CLI clears .icp/cache/artifacts, so they stay until it is deleted by hand.
  • A canister removed from the manifest leaves its ref, and so its module, behind. That matches today, where its whole artifact file is left behind.

Testing

  • Six new unit tests on the host store: a canister never built, sharing (including a rebuild that changes nothing), naming by SHA-256, removal of a replaced module only once unreferenced, a missing module, and a malformed ref (text and non-UTF-8, and that neither its own rebuild nor another canister's is held up by it).
  • cargo test -p icp-project with and without default features, cargo clippy --workspace --all-targets, and the wasm32-unknown-unknown clippy all pass.
  • build_adapter_tests and build_tests pass against the built binary.
  • Driven by hand in a throwaway project and home: two pre-built canisters and one script canister producing the same bytes left one module and three 64-byte refs; changing the script canister's output added a second module and kept the shared one; icp project bundle read both back.
  • Not run locally: scripts/check-no-host-reach.sh (needs llvm-nm, not installed here). The change is entirely behind the host feature, and CI runs the check.

🤖 Generated with Claude Code

`.icp/cache/artifacts` held one whole copy of the module per canister, so
several canisters built to the same WASM (one pre-built module shared by
many canisters, say) each cost its full size on disk.

The store now keeps a module at `modules/<sha256>.wasm` and a small
`refs/<canister>` file naming it. Saving bytes already present writes only
the ref; a module is removed when the last canister naming it is rebuilt
to something else. The change is inside `ArtifactStore`: the
`store_artifact::Access` seam and its callers are untouched.

Artifacts written by an earlier version are not read, and each is removed
as its canister is rebuilt.

Co-Authored-By: Claude Fable 5.2 <[email protected]>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Non-UTF-8 artifact refs cause errors instead of being treated as invalid, preventing rebuilds from repairing malformed entries without manual deletion.

1 open issue
What changed in this PR

This PR reduces artifact-cache storage by keeping one owned copy of each distinct WASM module, while leaving the artifact-store interface and callers unchanged.

Changes:

  • Stores modules by SHA-256, with a small reference file per canister.
  • Removes replaced modules once unreferenced and clears legacy artifacts as canisters rebuild.
  • Adds host-store tests and documents the new layout and upgrade behavior.
File Description
docs/​concepts/​project-model.md Clarifies that distinct built WASM files are stored once.
crates/​icp-project/​src/​store_artifact.rs Implements shared module storage, reference lookup, cleanup, and tests.
CHANGELOG.md Documents deduplication and the rebuild requirement after upgrading.

Review effort: Balanced

…eanup

A ref holding bytes that are not UTF-8 failed to read, which failed both
that canister's rebuild and any other canister's save that scanned it. It
now reads as holding no module, like any other malformed ref.

The store's two directories are `.modules` and `.refs`: a canister name
cannot contain `.`, so neither can be where an earlier version left a
canister's artifact file. With that, the code that moved such files out of
the way is gone; they are left in place and not read.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Copilot AI balanced review requested due to automatic review settings November 20, 2026 22:17

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are reported for the WASM artifact deduplication change.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

@raymondk

Copy link
Copy Markdown
Collaborator Author

On the . in front of .modules and .refs:

Before this PR the store kept each canister's module in a file named for the canister, directly in .icp/cache/artifacts. A project that carries its cache across the upgrade can therefore still have such files there, and a canister called modules or refs would leave a file exactly where the new directory has to go, failing the next build.

Canister names may only contain ASCII letters, digits, _ and - (is_valid_name in project.rs). So a prefix like __ only makes the collision unlikely, since __modules is itself a legal canister name. A leading . can never appear in a name, which makes the collision impossible and lets the store drop the code that moved old files out of the way. It also matches the .lock file already in that directory.

The cost is that the two directories are hidden from a plain ls.

…or once

The round-trip and earlier-version tests repeated what the others already
cover, and the unchanged-rebuild case is now one save in the sharing test.
The store's own cause was being wrapped in a second StoreCause on its way
into SaveStore and LookupStore.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Copilot AI balanced review requested due to automatic review settings November 20, 2026 22:32

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are recorded for the change that deduplicates cached WASM artifacts.

No open issues 🎉

Review effort: Balanced

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants