Skip to content

feat(prism-code): local image store, prism.images list/tag/remove/prune and prism-code images (Closes #349, Part of #442) - #622

Merged
afflom merged 24 commits into
mainfrom
claude/project-thread-cry1z3
Nov 12, 2026
Merged

afflom merged 24 commits into
mainfrom
claude/project-thread-cry1z3

Conversation

@afflom

@afflom afflom commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Requested by Alex · project thread

v0.5 workstream WS2: #349 (the local image store), the store half of #442 (prism.images) and the image half of #446 (system df, info and prune).

What changes

  • src/image-store.mjs is a content-addressed store. Each image is kept once, under the BLAKE3 digest its own footer names. Tags are [registry/]repository:tag names that point at a digest.
    • On disk it holds index.json (prism/image-store/1) and blobs/blake3/<hex>. Both are private to the user and written atomically.
    • Every read hashes the bytes again, so a file changed on disk raises image.corrupt and is never served.
  • The removal rules are a LexLean model. bindings/src/Foundation/Images/V1/Store.lex.tex (root writeImageStoreRules) generates the decision table src/image-store-rules.json, which remove and prune look each case up in.
    • Two theorems are proved by decide: removeNeverDeletesAHeldImage and pruneNeverDeletesAHeldOrTaggedImage.
    • The certified export is vendored as xtask/src/image_store_rules/model.rs. cargo xtask check-image-store-rules, which validate also runs, checks that the committed table matches it byte for byte.
  • prism.images gains list, get, tag, remove, prune and usage.
    • build and pull write into the store. pull writes only after the image has verified.
    • push without source sends the stored image that its name names, as docker push does.
    • images may not import containers, so the client passes in which images containers hold.
  • The CLI:
    • prism-code images ls|tag|rm|prune and Docker's top-level images, tag and rmi, in src/cli/images.mjs.
    • prism-code push with one operand pushes the stored image of that name.
    • prism-code pull also keeps what it pulled in the store.
    • The developer glossary flips images, tag and rmi to "now".
    • Flat prism-code build does not store anything; the SDK's images.build does.
  • prism.system and prism-code system:
    • df reports image usage, where an active image is one a container references. -v lists each image.
    • info counts the stored images.
    • prune collects images after exited containers and keeps any image a container references. -a/--all also removes tagged images that nothing references.
  • Prism.fromEnv() keeps the store in $PRISM_IMAGES, else $PRISM_HOME/images. fileImageStore, memoryImageStore and imagesDirectory are exported from prism-code/node.
  • Registry and conformance:
  • Docs: the guide "Keep images locally" covers the store and its garbage collection. Also the cli.json rows, the regenerated skill, STABILITY rows and both changelogs.
  • Package: scripts/package-allowances/local-image-store.json adds 32 KiB.

Tests

  • npm test in sdk/npm/prism-code: 907 pass. reference-archives fails locally on main too.
  • validate-model, check-modules, check-developer-view, check-image-store-rules, the sdk/docs tests and the OC-11/OC-12 conformance cases all pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_013Asa3NmrRTpngJ3TFNocur

…iew's glossary (#347)

The developer view of #346 is declared once, as the LexLean model
bindings/src/Foundation/Views/V1/Developer.lex.tex: the Docker-aligned
terms over the canonical terms they name, the other words of the surface
and the deprecated aliases. Its certified export is vendored into xtask,
and `cargo xtask check-developer-view` (part of `cargo xtask validate`)
runs it over sdk/npm/prism-code/developer-surface.json, refusing a name
outside the glossary, a canonical term the view renames, a Docker verb
taken before Prism has its behaviour, and an undeclared alias. The model
renders docs/developer-glossary.md.

A prism-code test keeps developer-surface.json equal to the CLI help, the
delegated verbs and the client. The check found two canonical terms on the
surface, now renamed with deprecated aliases through 0.8 that each print
one warning: `history` is `record`, and `--holo` (replay, dev) is
`--image`. Verbs handed to prismpm keep prismpm's flags.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3N4k8eo7mrfwURU1WM
…#347)

check-developer-view compares docs/developer-glossary.md byte for byte with
the page the model renders, so a CRLF checkout would report drift. Pin it
to LF, as COMPLIANCE.md is.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3N4k8eo7mrfwURU1WM
…nt (#347)

The glossary maps the developer view's words onto the canonical terms and
names the issues that build the waiting verbs, as docs/vocabulary.md maps
the docs' terms onto the repository's names, so it is excluded with it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3N4k8eo7mrfwURU1WM
, #349)

build and pull keep each image once under its BLAKE3 digest, with tags as
[registry/]repository:tag names (src/image-store.mjs). push without a source
sends the stored image its name names. list, get, tag, remove and prune are
new verbs of prism.images.

What may be removed comes from one decision table, src/image-store-rules.json:
remove untags one of several tags, refuses with image.in-use while a container
references the image unless forced and always while one runs, and refuses by
digest an image with several tags unless forced; prune deletes only images no
container references, untagged ones unless all. The client tells images what
containers hold, since images may not import containers.

system.df reports image usage, and system.prune collects images after
containers, keeping any a container references. Prism.fromEnv() keeps the store
in $PRISM_IMAGES, else $PRISM_HOME/images; bytes are hashed again on every read.

Seven image.* codes are registered under the new conformance id OC-12, which
runs test/image-store.test.mjs. The guide "Keep images locally" documents the
store and its garbage collection.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3NmrRTpngJ3TFNocur
# Conflicts:
#	sdk/npm/prism-code/scripts/check-package.mjs
#	sdk/npm/prism-code/test/package.test.mjs
…(Part of #442)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3NmrRTpngJ3TFNocur
…image store (Part of #442)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3NmrRTpngJ3TFNocur
…Part of #442)

bindings/src/Foundation/Images/V1/Store.lex.tex decides every case of
prism.images.remove and prune and writes the table prism-code reads,
src/image-store-rules.json. Lean proves by decide that no remove case deletes
an image a running container references or a referenced one without force,
and that prune never deletes a referenced image or, without all, a tagged one.

The certified export adds the package prism_image_store_rules, vendored as
xtask/src/image_store_rules/model.rs. `cargo xtask check-image-store-rules`
(also run by `cargo xtask validate`) compares the writer's output with the
committed table byte for byte. The other packages' provenance changes only in
the project's source id. The package allowance rises to 28 KiB, the whole
growth rounded up.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3NmrRTpngJ3TFNocur
`prism-code <module> <verb>` dispatches through src/cli/index.mjs to one
file per module, so each workstream adds verbs to its own file and never
to bin/prism-code.mjs. `images build|inspect|pull|push|verify` and
`containers run|rm|inspect` name the flat verbs, which stay. A group file
may also give its verbs as functions with a verbatim `help` block, and
`aliases` for top-level spellings (`login` for `auth login`).

The developer surface reads a group line's verb as the word after the
module, so `images push` is checked against the glossary as `push`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3QVSkS6PGopegNeztG
…and own src/cli/

cli.json is compared with the verbs --help prints, so the two group words
join it, and the generated skill table follows. src/cli/ is owned by the
client, which composes the modules, with the same entry as #621.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3QVSkS6PGopegNeztG
…its module

When a module's file aliases the module's own name (images for images ls),
prism-code images inspect x is still the group verb; the alias applies only
when no group verb follows and no --help is asked for.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3QVSkS6PGopegNeztG
…es, tag and rmi (Part of #442)

Merges the CLI group dispatcher (#625, on #614) and adds the image store verbs
to src/cli/images.mjs: `images ls` (also `prism-code images`), `tag`, `rm`
(also `rmi`) and `prune`. `prism-code pull` keeps what it verified in the
local image store under the name it was pulled by, and `prism-code push
<reference>` with no holo sends the stored image of that name.

The developer view's glossary marks images, tag and rmi as now (#349 is
here), adds ls and usage to its words, and the bindings are re-exported.
OC-12 now counts the CLI test. Suites that pull through the CLI keep their
store in a scratch folder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3NmrRTpngJ3TFNocur
…to claude/project-thread-cry1z3

# Conflicts:
#	sdk/docs/cli.json
#	sdk/npm/prism-code/bin/prism-code.mjs
#	sdk/npm/prism-code/skill/SKILL.md
#	skills/prism/SKILL.md
…-cry1z3

# Conflicts:
#	ERRORS.md
#	STABILITY.md
#	model/sdk-diagnostics.toml
#	sdk/npm/prism-code/CHANGELOG.md
…-cry1z3

# Conflicts:
#	CHANGELOG.md
#	sdk/npm/prism-code/CHANGELOG.md
…-cry1z3

# Conflicts:
#	bindings/generated/prism_bindings_js/package.json
#	bindings/generated/prism_bindings_js/provenance.json
#	bindings/generated/prism_bindings_python/package.json
#	bindings/generated/prism_bindings_python/provenance.json
#	bindings/generated/prism_bindings_rust/package.json
#	bindings/generated/prism_bindings_rust/provenance.json
#	bindings/generated/prism_developer_view/package.json
#	bindings/generated/prism_developer_view/provenance.json
#	bindings/generated/prism_developer_view/src/lib.rs
#	bindings/generated/prism_proof_statement/package.json
#	bindings/generated/prism_proof_statement/provenance.json
#	bindings/lexlean.lock
#	bindings/lexlean.toml
#	bindings/production.json
#	bindings/src/Foundation/Views/V1/Developer.lex.tex
#	docs/developer-glossary.md
#	sdk/docs/cli.json
#	sdk/npm/prism-code/CHANGELOG.md
#	sdk/npm/prism-code/bin/prism-code.mjs
#	sdk/npm/prism-code/developer-surface.json
#	sdk/npm/prism-code/skill/SKILL.md
#	sdk/npm/prism-code/src/developer-view.mjs
#	sdk/npm/prism-code/test/developer-view.test.mjs
#	skills/prism/SKILL.md
#	xtask/src/bindings.rs
#	xtask/src/developer_view/model.rs
#	xtask/src/main.rs
…-cry1z3

# Conflicts:
#	sdk/docs/cli.json
#	sdk/npm/prism-code/developer-surface.json
#	sdk/npm/prism-code/skill/SKILL.md
#	sdk/npm/prism-code/src/cli/images.mjs
#	sdk/npm/prism-code/test/cli-groups.test.mjs
#	skills/prism/SKILL.md
…ore (Part of #349)

#621's system verbs were written before the store existed. df now counts
images (and lists them with -v), info gives the stored count, and prune
takes -a|--all and prints the images it deleted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3NmrRTpngJ3TFNocur
…-cry1z3

# Conflicts:
#	bindings/generated/prism_bindings_js/package.json
#	bindings/generated/prism_bindings_js/provenance.json
#	bindings/generated/prism_bindings_python/package.json
#	bindings/generated/prism_bindings_python/provenance.json
#	bindings/generated/prism_bindings_rust/package.json
#	bindings/generated/prism_bindings_rust/provenance.json
#	bindings/generated/prism_developer_view/package.json
#	bindings/generated/prism_developer_view/provenance.json
#	bindings/generated/prism_developer_view/src/lib.rs
#	bindings/generated/prism_proof_statement/package.json
#	bindings/generated/prism_proof_statement/provenance.json
#	bindings/src/Foundation/Views/V1/Developer.lex.tex
#	docs/developer-glossary.md
#	sdk/docs/cli.json
#	sdk/npm/prism-code/skill/SKILL.md
#	skills/prism/SKILL.md
#	xtask/src/developer_view/model.rs
@afflom afflom changed the title feat(prism-code): local image store and prism.images list/tag/remove/prune (Part of #442) feat(prism-code): local image store, prism.images list/tag/remove/prune and prism-code images (Closes #349, Part of #442) Nov 12, 2026
@afflom
afflom marked this pull request as ready for review November 12, 2026 10:21
@afflom
afflom merged commit a6c17d0 into main Nov 12, 2026
33 of 34 checks passed
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