Skip to content

feat(prism-code): check the developer surface against the developer view's glossary (#347) - #614

Merged
afflom merged 6 commits into
mainfrom
claude/roadmap-347
Nov 12, 2026
Merged

afflom merged 6 commits into
mainfrom
claude/roadmap-347

Conversation

@afflom

@afflom afflom commented Nov 11, 2026

Copy link
Copy Markdown
Member

Requested by Alex · project thread

Part of #347. It does not close the issue.

What

  • The developer view as a LexLean model. bindings/src/Foundation/Views/V1/Developer.lex.tex declares Design proposal: stakeholder views, with a Docker-aligned developer view #346's developer glossary once:

    • the Docker-aligned terms over the canonical terms they name, and when each one becomes available;
    • the other words of the surface (Docker's verbs, plus terms new with Prism such as verify, replay and dispatch);
    • the deprecated aliases.

    It is exported by LexLean's certified production export as prism_developer_view and vendored into xtask. No check logic is written by hand.

  • cargo xtask check-developer-view [--write] runs as part of cargo xtask validate. It reads sdk/npm/prism-code/developer-surface.json and refuses:

    The model also renders docs/developer-glossary.md, and the check fails when that page drifts.

  • developer-surface.json matches the package. It lists every verb and flag of prism-code --help (with the delegated verbs), every namespace and method of createPrism(), and the aliases. test/developer-view.test.mjs keeps it equal to the package. The members of errors and verify keep the model's names, so only those two namespaces are listed.

  • Two renames the check found, each with a deprecated alias:

    Was Now Removed in
    prism-code history prism-code record 0.9.0
    --holo (replay, dev) --image 0.9.0
    • Each alias prints one warning that names the new term. Tests cover each alias with its warning and the new spelling without one.
    • Verbs that prism-code hands to prismpm (lock, build, verify and the others) keep prismpm's own flags.
    • Docs, the skill, cli.json, STABILITY.md and both changelogs are updated.
    • The package cap rises by 8 KiB to 1592 KiB.

Not in this PR (#347 stays open)

  • CLI JSON and SDK return objects: the versioned view schemas for these.
  • The familiarity test: it needs ps, logs, images and tag (Local image store: prism images, tag and rmi #349, Long-running holos as containers: run -d, ps, stop, rm, logs and exec #350).
  • The 0.2.0 examples run through the aliases.
  • Prose renames in the developer docs, where holo becomes image.
  • Open questions for review:
    • init --sdk-image would become --builder-image, but delegated prismpm lock --sdk-image would keep the old name on the same CLI. So both are left as they are for now.
    • prism-code manifest lints prism.toml, while the glossary uses manifest for a product release.

Checked locally

  • cargo xtask bindings-package (certified export, current)
  • check-developer-view
  • check-modules
  • validate-model
  • validate-spec-links
  • xtask tests and clippy
  • prism-code npm test: 858 pass. reference-archives fails, and it fails the same way locally on main.
  • sdk/docs tests: 98 pass.

Generated by Claude Code

…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
@afflom afflom self-assigned this Nov 11, 2026
…#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
# Conflicts:
#	sdk/npm/prism-code/scripts/check-package.mjs
#	sdk/npm/prism-code/test/package.test.mjs
afflom pushed a commit that referenced this pull request Nov 12, 2026
The deadline test reads /proc/<pid>/stat to see that the timed-out
descendant stopped. When the kernel reaps it between open and read, the
read fails with ESRCH (seen in Model & Audits on #614, run for 2813675),
which means the same as ENOENT: the process is gone.

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

afflom commented Nov 12, 2026

Copy link
Copy Markdown
Member Author

The Model & Audits failure on 2813675 is not from this PR. The failing test is scripts/product-sdk-check.test.mjs test 309 ("actual deadline kills descendant process group"), and its after hook failed with ESRCH: no such process, read at line 146.

This is a race. The hook reads /proc/<pid>/stat for a descendant that is reaped during the read, and the helper treats only ENOENT as gone, not ESRCH. This PR does not touch that file. The one-line fix is in #625.

I've re-run the failed job once.


Generated by Claude Code

afflom pushed a commit that referenced this pull request Nov 12, 2026
…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
# Conflicts:
#	sdk/npm/prism-code/CHANGELOG.md
# Conflicts:
#	CHANGELOG.md
#	sdk/npm/prism-code/CHANGELOG.md
@afflom
afflom merged commit 43127f8 into main Nov 12, 2026
33 checks passed
afflom pushed a commit that referenced this pull request Nov 12, 2026
afflom added a commit that referenced this pull request Nov 12, 2026
…625)

`prism-code <module> <verb>` dispatches through src/cli/index.mjs to one file per module. images build|inspect|pull|push|verify and containers run|rm|inspect name the flat verbs, which stay. Group files may give verbs as functions with a verbatim help block, and aliases for top-level spellings. The developer surface reads a group line's verb as the word after the module.

Also: the product-sdk-check deadline test treats ESRCH from /proc/<pid>/stat as an exited process.

Every check passed on ad4824b; daaf30f only records main's squash of #614 and has the identical tree (87fa6d0).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Asa3QVSkS6PGopegNeztG
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