Skip to content

[inscriptive] Inconsistent lifecycle contract (delta flush) and endianness across managers #19

Description

@GideonBature

Summary

Two cross-cutting consistency issues across the storage managers that are easy to fix and would prevent future bugs:

  1. Lifecycle contract drift: Graveyard::apply_changes flushes its own delta internally (flush_deltas()), while every other manager leaves flushing to the caller (flush_delta()). The method name is also plural in graveyard and singular everywhere else.
  2. Endianness split: sync_manager and archival_manager serialize their keys/values big-endian (to_be_bytes), while coin_manager, state_manager, registry, and privileges_manager use little-endian (to_le_bytes). Internally consistent, but a landmine for any cross-manager key/value format.

Affected file(s)

  • Lifecycle: src/inscriptive/graveyard/graveyard.rs vs. all other managers
  • Endianness: src/inscriptive/sync_manager/sync_manager.rs, src/inscriptive/archival_manager/archival_manager.rs vs. the rest

Location

1. Lifecycle / flush

src/inscriptive/graveyard/graveyard.rs:236-272apply_changes ends with:

// 3 Flush the delta.
self.flush_deltas();

// 4 Return success.
Ok(())

and the method is flush_deltas (plural) at graveyard.rs:275-278. Compare every other manager, e.g. coin_manager.rs:2012-2018:

pub fn flush_delta(&mut self) {
    self.delta.flush();
    self.backup_of_delta.flush();
}

…and coin_manager's apply_changes does not call flush_delta — the engine (src/executive/exec_ctx/) calls flush_delta() separately after a successful apply_changes. So the engine code path presumably already calls graveyard.flush_deltas() again after graveyard.apply_changes(), making the internal flush either redundant or a sign that the graveyard's caller doesn't follow the same orchestration as the others.

2. Endianness

Manager Site Endianness
sync_manager.rs ~lines 43, 51 (bitcoin_sync_height_tip, cube_batch_sync_height_tip) and 123, 133 setters to_be_bytes / from_be_bytes
archival_manager.rs ~line 99 (load), ~line 159 (store) to_be_bytes / from_be_bytes
coin_manager.rs balance/allocs values to_le_bytes
state_manager.rs, registry.rs, privileges_manager.rs, params_manager.rs all serialized numerics to_le_bytes

Root cause / analysis

Lifecycle — copy-paste drift: graveyard's apply_changes was likely written with the flush inlined, then never normalized. The risk is double-handling (caller flushes an already-empty delta — harmless) or, worse, a caller that assumes the manager doesn't flush (like every other manager) and skips flushing graveyard — at which point the internal flush is load-bearing and easily removed by a refactor.

Endianness — not a runtime bug (each manager reads what it writes), but: if any two managers ever share a key namespace (e.g. a unified height index), or if tooling/dumping code assumes one endianness, values are silently misread. Mixed endianness in one storage layer is a known source of "off by 4 billion" bugs.

Impact

  • Lifecycle: low immediate risk, high refactor fragility.
  • Endianness: no current bug, latent cross-manager hazard.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions