40 lines
1.7 KiB
Markdown
40 lines
1.7 KiB
Markdown
# 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.
|