Explain static catalogs plainly; correct the term's scope#18
Merged
Conversation
Two related fixes, prompted by pinning down what a static catalog actually is. The README glossary called a static catalog 'one consistent snapshot,' which overstates it: static catalogs pin module file *content* to the catalog's version, not the whole catalog (resources and relationships are fixed at compile time in any catalog). Tightened the glossary line and added a beginner section that tells the story — an agent applies a catalog over time and fetches module files as it goes, so a deploy mid-run can leave it applying a mix of old and new; a static catalog stamps the catalog with a code_id so the agent fetches files at that version instead. It ends on where codavox fits: the server needs to answer 'which version?' and 'file X at version Y', PE answers with Code Manager and file sync, and a stock OpenVox Server has the socket but nothing plugged in — which is codavox. commands.md said static catalogs 'need enabling' with static_catalogs = true, which reads as if the setting were off by default. It defaults to true in both PE and OpenVox. Verified in openvox-server that the server sets include-code-id? on every /catalog/ request unconditionally, and that with no code-id-command configured the code_id is nil (versioned_code_service.clj logs 'Code-id will be nil'). So the real requirement is not the setting but configuring the two commands. Reworded to say the setting is usually already on and that wiring the commands is what makes static catalogs do their job. Signed-off-by: Michael Harp <mike@mikeharp.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Prompted by pinning down what a static catalog actually is (and isn't).
Beginner explainer + tighter glossary
The README glossary called a static catalog "one consistent snapshot," which overstates it — static catalogs pin module file content to the catalog's version, not the whole catalog. Tightened that line and added a Static catalogs in plain terms section that tells the story for a newcomer:
code_idso the agent fetches files at that version;commands.md correctness
It said static catalogs "need enabling" with
static_catalogs = true, reading as if the setting were off by default. It'strueby default in both PE and OpenVox. Verified in openvox-server:master_core.cljsets:include-code-id? trueon every/catalog/request unconditionally;code-id-commandconfigured,versioned_code_service.cljlogs "No code-id-command set … Code-id will be nil."So the real requirement isn't the setting — it's configuring the two commands. Reworded accordingly.
Docs-only. markdownlint clean, links resolve.
🤖 Generated with Claude Code