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

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions