cli/docs/adr/0002-keyed-load-once-manifests-are-validated.md

Keyed load-once manifests are validated before packing

The plugin SDK and CMS host support keyed LoadOnce callbacks whose durable identity is the (plugin name, key) pair. A malformed or duplicate key would make execution ambiguous and should not survive until production installation.

Decision: both ninja plugin build and ninja plugin verify validate every load_once_keys manifest entry with the SDK's canonical rules. Keys are 1–128 bytes, start alphanumeric, and contain only lower-case letters, digits, ., _, or -; duplicates are rejected. Codeless artifacts reject load-once keys because they have no guest callback to execute.

Consequences:

• Build and verification fail before an invalid artifact can be published.
• CLI and host use the same SDK validator instead of drifting grammars.
• Changing a valid key remains the deliberate way to define a new one-time operation.

Keywords: plugin CLI, LoadOnce, load_once_keys, BNP, validation, codeless