feat(glossary): add 5 community-proposed terms (cNFT unified pool batch)#47
Open
zupy-fmartinelli wants to merge 3 commits intosolanabr:mainfrom
Open
feat(glossary): add 5 community-proposed terms (cNFT unified pool batch)#47zupy-fmartinelli wants to merge 3 commits intosolanabr:mainfrom
zupy-fmartinelli wants to merge 3 commits intosolanabr:mainfrom
Conversation
Terms proposed by Kuka agent during teaching conversations with @WebMaster (Zupy) while wrapping up the cNFT unified pool epic: - bubblegum-asset-pda (zk-compression): Bubblegum Asset PDA - cnft-tree-pool (zk-compression): cNFT Tree Pool - mint-kill-switch (security): Mint Kill-Switch - non-retryable-error (infrastructure): Non-Retryable Error - retry-storm (infrastructure): Retry Storm All 5 passed schema validation and cross-reference existing terms (bubblegum, merkle-tree, pda, circuit-breaker, defense-in-depth, transaction-retry, idempotency, ...). i18n pt/es included.
zupy-fmartinelli
added a commit
to zupy-fmartinelli/solana-glossary
that referenced
this pull request
Apr 19, 2026
Bug surfaced in production on 2026-04-19 while opening a proposal batch
PR via `submit-proposals.ts --pr`. Two symptoms:
1. commit message came out with empty slots where term IDs should be:
- (zk-compression): Bubblegum Asset PDA
- (zk-compression): cNFT Tree Pool
instead of the expected `bubblegum-asset-pda (zk-compression): ...`.
2. `gh pr create` failed outright with errors like
/bin/sh: 1: bubblegum-asset-pda: not found
/bin/sh: 1: validate-term-proposal.ts: not found
(one per backtick in the body) and returned exit code 1, so
`pr_url` came back null even though the branch + commit had been
made successfully.
Root cause: both `commitProposals` and `submitPr` embedded the message/
body into the shell command string via template literal, only escaping
double quotes. Any backtick in the text (plentiful: term IDs are
formatted as `` `id` ``, and the PR body had an inline code block
mentioning `validate-term-proposal.ts`) was interpreted as command
substitution by /bin/sh, which then tried to execute each ID as a
shell command.
Fix: pipe the message via stdin using the native "read from stdin"
options — `git commit -F -` and `gh pr create --body-file -`. execSync
accepts an `input` option that pipes a string to stdin of the spawned
process, so there is no shell quoting step at all.
Validation: full submit-proposals --pr flow run end-to-end, produced a
real PR (solanabr#47 against solanabr/solana-glossary) with correct commit
message and correctly-rendered body. typecheck clean.
Terms added in this batch were missing the required depth field, breaking CI validation. Assigned depths based on category patterns: - non-retryable-error (infrastructure): 4 - retry-storm (infrastructure): 3 - mint-kill-switch (security): 4 - bubblegum-asset-pda (zk-compression): 4 - cnft-tree-pool (zk-compression): 4
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.
Glossary Expansion — Kuka Agent Proposals
New Terms (5)
Proposed by the Kuka teaching agent during a session with @zupy-fmartinelli (Zupy) while closing the cNFT unified-pool epic. All 5 come from concrete production experience — concepts the team had to invent words for during an incident and recovery.
bubblegum-asset-pdaasset_id— it identifies the tx, not the asset.cnft-tree-poolmint-kill-switchretry-stormnon-retryable-errorHow they connect
The three infra/security terms form a closed triangle:
The two zk-compression terms anchor onto
bubblegum,compressed-nft,merkle-tree,concurrent-merkle-tree,canopy-depth.Validation
All 5 pass
validate-term-proposal.ts:relatedrefs resolve against currentmainProvenance
Generated by Kuka 🎓 during real teaching work, not synthesized artificially. The cNFT unified pool epic that sourced these terms shipped to production on 2026-04-19 — the pattern-naming became part of post-incident knowledge transfer.