bee/bible-local/decisions/2026-04-29-read-only-embedded-submodules.md

Decision: Treat embedded submodules as read-only

Context

bee embeds external git submodules such as:

• internal/chart/ — reanimator/chart, a generic read-only viewer for Reanimator JSON snapshots
• bible/ — shared engineering rules and contracts

These repositories are reused by other projects. A local feature request in bee must not be solved by silently changing shared submodule behavior.

The concrete failure mode here was attempting to add project-specific storage telemetry presentation by editing internal/chart/. That couples a shared viewer to one host application's needs and creates hidden cross-project regressions.

Decision

Embedded submodules are read-only from the point of view of bee.

• Do not implement bee-specific behavior by editing internal/chart/.
• Do not implement bee-specific behavior by editing bible/.
• If bee needs new data in the report, produce it in the standard audit JSON emitted by bee itself.
• chart must continue to consume the canonical snapshot as an external viewer, without host-specific forks.
• Updating a submodule pointer to an upstream commit is allowed.
• Carrying local unmerged submodule commits as part of a bee feature is forbidden.

Consequences

• Audit/report features must be expressed through the contract in bible-local/docs/hardware-ingest-contract.md.
• bee owns collection, normalization, and serialization of storage telemetry in hardware.storage[].
• chart remains a pure visualization module that reads the snapshot it is given.
• If a capability is genuinely missing in a shared submodule, it must be proposed and landed upstream as a generic change first, then pulled into bee via a normal submodule update.