Document npm package, bundled plugin, and runtime version mapping

[chainTe]

Summary

The following identifiers refer to the same Codex Security plugin release/content, but they use different version numbers:

• npm release tag: npm-v0.1.5
• bundled plugin manifest: 0.1.14
• Codex runtime distribution: 0.1.15

The vendor snapshot is therefore correct when copied byte-for-byte from npm-v0.1.5; the confusing part is the undocumented mapping between these three identifiers.

Observed source identity

• Tag npm-v0.1.5 resolves to commit 66778d0d85f478d7832854b81d0a6ddb93a3ce4c.
• The bundled plugin tree is 09b14c17694b5f568dd61860f2bc63771e5e4280.
• sdk/typescript/_bundled_plugin/.codex-plugin/plugin.json reports 0.1.14.
• The corresponding Codex runtime plugin reports 0.1.15.

Request

Could the release documentation or metadata explicitly describe the relationship between:

1. the npm release tag/version,
2. the bundled .codex-plugin/plugin.json version, and
3. the Codex runtime/catalog version?

An immutable mapping such as npm tag → commit SHA → bundled tree hash → runtime version would make byte-for-byte vendoring and provenance checks unambiguous.

Alternatively, aligning these version fields for future releases would avoid downstream tools interpreting the same release as a version mismatch.

Reproduction

git clone https://github.com/openai/codex-security.git
cd codex-security
git checkout npm-v0.1.5

git rev-parse HEAD
git rev-parse HEAD:sdk/typescript/_bundled_plugin
jq -r .version sdk/typescript/_bundled_plugin/.codex-plugin/plugin.json

Observed:

66778d0d85f478d7832854b81d0a6ddb93a3ce4c
09b14c17694b5f568dd61860f2bc63771e5e4280
0.1.14

[Souptik96]

Your three observed values check out, and building the table across every published tag turns up something sharper than a documentation gap: bundledPluginVersion cannot identify bundled content, because it has never changed while the content has changed every release.

The mapping, derived from all six published tags

npm tag	commit	_bundled_plugin tree	plugin.json version	package.json version
npm-v0.1.0	a45e3ee2f9cc	2076731023a2	0.1.14	0.1.0
npm-v0.1.1	e94d6bef9797	2076731023a2	0.1.14	0.1.1
npm-v0.1.2	1e03c89ad22d	464e53b25a58	0.1.14	0.1.2
npm-v0.1.3	f89633aeee1e	7f2e7c0a8879	0.1.14	0.1.3
npm-v0.1.4	ab3b91c8b1fc	faf3bfb780d1	0.1.14	0.1.4
npm-v0.1.5	66778d0d85f4	09b14c17694b	0.1.14	0.1.5

(Tree hashes are the _bundled_plugin entry SHA from the contents API at each tag, which is the git tree object — the same value your git rev-parse HEAD:sdk/typescript/_bundled_plugin produces. npm-v0.1.5 reproduces your 09b14c17694b… exactly.)

What that shows

1. package.json version tracks the npm tag 1:1 — that pair is a reliable anchor.
2. plugin.json version is frozen at 0.1.14 across all six releases, while the bundled tree hash changes at 0.1.2, 0.1.3, 0.1.4 and 0.1.5. So it is not a stale-by-one-release mismatch — the field simply does not track the bundled content at all.
3. That value is user-visible: cli.ts reports it as bundledPluginVersion from BUNDLED_PLUGIN_VERSION via codex-security info, which is where people (understandably) read it as a content identifier. It appears in bug reports for that reason — e.g. Windows: codex-security scan fails with "scan-manifest.json: expected a regular file inside the scan directory" #27's diagnostics show bundledPluginVersion: 0.1.14 on 0.1.1.
4. 0.1.0 and 0.1.1 share tree 2076731023a2, so the bundled plugin was genuinely byte-identical across those two npm releases.

For byte-for-byte vendoring today

The only self-consistent anchor available in this repo is the tag → commit → tree triple:

git rev-parse "npm-v${VERSION}"                                   # commit
git rev-parse "npm-v${VERSION}:sdk/typescript/_bundled_plugin"    # bundled tree

Pin on the tree hash, not on bundledPluginVersion.

What I could not determine

The runtime/catalog 0.1.15 is not derivable from this repository — nothing here emits it, so I can't verify or map it. That part genuinely needs maintainer input, as does whether the frozen plugin.json version is intentional (a manifest-schema version, say) or an oversight in the release process.

Happy to open a focused docs PR adding the verifiable half of this — the tag/commit/tree recipe plus a note that bundledPluginVersion does not identify bundled content — and leave the runtime mapping for you to fill in. Say the word and I'll put it up.