🥮 mooncakes.io

moonbit-shard-note

Printable short-message shard cards with checksum validation, multi-parity recovery, diagnostics, and conformance scenarios.

moonbit
offline
recovery
parity
gf256
resilient
checksum
diagnostics
paper-backup
moon add JJ-ai-nb/moonbit-shard-note@0.2.1
Download zip
Author
Version
0.2.1
License
Apache-2.0
Repository
Last updated
4 hours ago
Downloads
19
README

#JJ-ai-nb/moonbit-shard-note

MoonBit package for printable short-message recovery cards.

///| test { let payload = @moonbit-shard-note.ascii_payload("MoonBit resilient shard notes") let cards = @moonbit-shard-note.weave_resilient("readme-demo", payload, 6, 3) let partial = @moonbit-shard-note.drop_resilient_indices(cards, [1, 4]) match @moonbit-shard-note.recover_resilient(partial) { @moonbit-shard-note.ResilientRestored(restored) => inspect(@moonbit-shard-note.payload_to_ascii(restored), content="MoonBit resilient shard notes") _ => inspect("not restored", content="not restored") } }

#
CardParse

source
pub(all) enum CardParse {
  ParsedCard(ResilientShardCard)
  InvalidCard(String)
} derive(Eq, 
Debug)

Parse result for one rendered RSN1|... card line.

#
CopyEstimate

source
pub(all) struct CopyEstimate {
  cards : Int
  symbols : Int
  groups : Int
  estimated_minutes : Int
  risk_level : String
} derive(Eq, 
Debug)

A short estimate for manual copy work.

#
Recovery

source
pub(all) enum Recovery {
  Restored(Array[Int])
  NeedCards(Array[Int])
  Damaged(String)
} derive(Eq, 
Debug)

Recovery result for a deck of shard cards.

#
ResilientDeckAudit

source
pub(all) struct ResilientDeckAudit {
  deck : String
  expected_cards : Int
  present_cards : Int
  valid_cards : Int
  data_cards : Int
  parity_cards : Int
  missing_data : Array[Int]
  missing_parity : Array[Int]
  duplicate_indices : Array[Int]
  checksum_failures : Array[Int]
  profile_mismatches : Array[Int]
  width_failures : Array[Int]
  recoverable_now : Bool
  summary : String
} derive(Eq, 
Debug)

Audit information for a group of resilient cards.

#
ResilientPlan

source
pub(all) struct ResilientPlan {
  deck : String
  payload_len : Int
  data_count : Int
  parity_count : Int
  width : Int
  total_cards : Int
  recoverable_missing_data_cards : Int
  estimated_symbols : Int
} derive(Eq, 
Debug)

A deterministic plan used by the planner and documentation examples.

#
ResilientRecovery

source
pub(all) enum ResilientRecovery {
  ResilientRestored(Array[Int])
  ResilientNeedCards(Array[Int])
  ResilientDamaged(String)
} derive(Eq, 
Debug)

Recovery result for the multi-parity card format.

#
ResilientScenario

source
pub(all) struct ResilientScenario {
  name : String
  deck : String
  seed : Int
  payload_len : Int
  data_count : Int
  parity_count : Int
  missing_indices : Array[Int]
  expected_recovery : Bool
} derive(Eq, 
Debug)

A built-in recovery scenario used by the conformance suite.

#
ResilientShardCard

source
pub(all) struct ResilientShardCard {
  deck : String
  index : Int
  data_count : Int
  parity_count : Int
  width : Int
  original_len : Int
  checksum : Int
  cells : Array[Int]
} derive(Eq, 
Debug)

A stronger shard card that can carry multiple parity rows.

index < data_count is a data card. index >= data_count is a parity card, and index - data_count is the parity row number.

#
ScenarioRun

source
pub(all) struct ScenarioRun {
  name : String
  expected_recovery : Bool
  actual_recovery : Bool
  recovered_matches : Bool
  reported_missing : Array[Int]
  payload_len : Int
  fingerprint : String
  message : String
} derive(Eq, 
Debug)

Result produced after running one recovery scenario.

#
ShardCard

source
pub(all) struct ShardCard {
  deck : String
  index : Int
  data_count : Int
  width : Int
  original_len : Int
  checksum : Int
  cells : Array[Int]
} derive(Eq, 
Debug)

A printable shard card. index == data_count is the parity card.

#
SheetLayout

source
pub(all) struct SheetLayout {
  columns : Int
  group_size : Int
  include_header : Bool
  include_audit : Bool
  include_checklist : Bool
} derive(Eq, 
Debug)

Options for human-readable resilient sheet rendering.

#
SheetParseReport

source
pub(all) struct SheetParseReport {
  cards : Array[ResilientShardCard]
  ignored_lines : Int
  errors : Array[String]
} derive(Eq, 
Debug)

Parse result for a sheet that may contain comments, blank lines, and cards.

#
ascii_payload

source
fn ascii_payload(text : String) -> Array[Int]

Convert an ASCII string into byte cells. Non-ASCII characters are replaced with the byte value for ?, so the helper stays deterministic everywhere.

#
audit_resilient_deck

source
fn audit_resilient_deck(cards : Array[ResilientShardCard]) -> ResilientDeckAudit

Audit a resilient card set without attempting to repair it.

#
builtin_resilient_scenarios

source
fn builtin_resilient_scenarios() -> Array[ResilientScenario]

Return the full built-in conformance catalog.

#
corrupt_resilient_cell

source
fn corrupt_resilient_cell(card : ResilientShardCard, offset : Int, value : Int) -> ResilientShardCard

Create a copy of a card with one cell changed.

#
count_expected_blocked_scenarios

source
fn count_expected_blocked_scenarios() -> Int

Count scenarios that are expected to ask for more evidence.

#
count_expected_recoverable_scenarios

source
fn count_expected_recoverable_scenarios() -> Int

Count scenarios that are expected to recover.

#
count_passing_builtin_scenarios

source
fn count_passing_builtin_scenarios() -> Int

Count passing scenarios in the built-in catalog.

#
count_present_resilient_parity

source
fn count_present_resilient_parity(cards : Array[ResilientShardCard]) -> Int

Count present parity cards in a resilient card set.

#
count_resilient_roles

source
fn count_resilient_roles(cards : Array[ResilientShardCard]) -> Array[Int]

Count visible cards by role as [data, parity, other].

#
default_sheet_layout

source
fn default_sheet_layout() -> SheetLayout

Return a practical default layout for printed notes.

#
demo_payload

source
fn demo_payload() -> Array[Int]

A small built-in demo payload. It spells "MOONBIT" as byte values.

#
deterministic_payload

source
fn deterministic_payload(seed : Int, len : Int) -> Array[Int]

Build a deterministic payload for demos and scenario tests.

#
drop_resilient_indices

source
fn drop_resilient_indices(cards : Array[ResilientShardCard], indices : Array[Int]) -> Array[ResilientShardCard]

Drop cards with selected indices. This is used by examples and tests.

#
estimate_copy_work

source
fn estimate_copy_work(cards : Array[ResilientShardCard]) -> CopyEstimate

Estimate manual copy effort for a group of cards.

#
gf256_add

source
fn gf256_add(left : Int, right : Int) -> Int

GF(256) addition. In characteristic two this is XOR.

#
gf256_div

source
fn gf256_div(left : Int, right : Int) -> Int?

GF(256) division.

#
gf256_inv

source
fn gf256_inv(value : Int) -> Int?

GF(256) multiplicative inverse. Zero has no inverse, so None is returned.

#
gf256_mul

source
fn gf256_mul(left : Int, right : Int) -> Int

GF(256) multiplication using polynomial 0x11D.

#
gf256_pow

source
fn gf256_pow(base : Int, exponent : Int) -> Int

GF(256) exponentiation.

#
gf256_sub

source
fn gf256_sub(left : Int, right : Int) -> Int

GF(256) subtraction. It is identical to addition in characteristic two.

#
keep_resilient_indices

source
fn keep_resilient_indices(cards : Array[ResilientShardCard], indices : Array[Int]) -> Array[ResilientShardCard]

Keep only selected card indices, preserving original card order.

#
missing_resilient_data_indices

source
fn missing_resilient_data_indices(cards : Array[ResilientShardCard]) -> Array[Int]

Return missing data indices after validating only visible indices.

#
parse_resilient_card

source
fn parse_resilient_card(line : String) -> CardParse

Parse one RSN1|... line emitted by render_resilient_card.

#
parse_resilient_sheet

source
fn parse_resilient_sheet(text : String) -> SheetParseReport

Parse a multi-line sheet. Blank lines and Markdown heading lines are ignored.

#
payload_diff_offsets

source
fn payload_diff_offsets(left : Array[Int], right : Array[Int]) -> Array[Int]

Compare two payloads and return mismatch offsets.

#
payload_fingerprint

source
fn payload_fingerprint(payload : Array[Int]) -> String

Compute a lightweight payload fingerprint for logs and examples.

#
payload_to_ascii

source
fn payload_to_ascii(payload : Array[Int]) -> String

Convert byte cells back to a printable ASCII string.

#
plan_resilient_deck

source
fn plan_resilient_deck(deck : String, payload_len : Int, target_width : Int, max_data_cards : Int, parity_count : Int) -> ResilientPlan

Build a practical plan from a payload length and target card width.

#
recover

source
fn recover(cards : Array[ShardCard]) -> Recovery

Recover the original payload when all data cards exist, or when exactly one data card is missing but the parity card is present.

#
recover_resilient

source
fn recover_resilient(cards : Array[ResilientShardCard]) -> ResilientRecovery

Recover a payload with up to parity_count missing data cards, provided enough independent parity rows are present.

#
recover_resilient_sheet

source
fn recover_resilient_sheet(text : String) -> ResilientRecovery

Parse a sheet and immediately try to recover it.

#
render_card

source
fn render_card(card : ShardCard) -> String

Return a compact, copy-friendly line for one card.

#
render_copy_estimate

source
fn render_copy_estimate(estimate : CopyEstimate) -> String

Render copy effort as one line for CLI output.

#
render_payload_profile

source
fn render_payload_profile(payload : Array[Int]) -> String

Render a compact data profile for logs.

#
render_recovery_checklist

source
fn render_recovery_checklist(cards : Array[ResilientShardCard]) -> String

Render a manual recovery checklist.

#
render_resilient_audit

source
fn render_resilient_audit(audit : ResilientDeckAudit) -> String

Render an audit as compact Markdown for issue comments or release evidence.

#
render_resilient_card

source
fn render_resilient_card(card : ResilientShardCard) -> String

Return one compact, copy-friendly line for a resilient card.

#
render_resilient_markdown_table

source
fn render_resilient_markdown_table(cards : Array[ResilientShardCard]) -> String

Render cards as a Markdown table for README examples and issue comments.

#
render_resilient_sheet

source
fn render_resilient_sheet(cards : Array[ResilientShardCard]) -> String

Render a printable resilient note sheet.

#
render_resilient_sheet_with_layout

source
fn render_resilient_sheet_with_layout(cards : Array[ResilientShardCard], layout : SheetLayout) -> String

Render resilient cards with optional audit and checklist sections.

#
render_scenario_report

source
fn render_scenario_report(max_rows : Int) -> String

Render a short scenario report for CLI output and review notes.

#
render_sheet

source
fn render_sheet(cards : Array[ShardCard]) -> String

Render several cards as one printable note sheet.

#
resilient_capacity_summary

source
fn resilient_capacity_summary(cards : Array[ResilientShardCard]) -> String

Explain how many data cards can be missing for the current evidence.

#
resilient_profiles_match

source
fn resilient_profiles_match(cards : Array[ResilientShardCard]) -> Bool

Return true when all visible cards share the same profile.

#
rewrite_resilient_cell

source
fn rewrite_resilient_cell(card : ResilientShardCard, offset : Int, value : Int) -> ResilientShardCard

Return a corrected copy of a card after a deliberate cell edit.

#
run_builtin_resilient_scenarios

source
fn run_builtin_resilient_scenarios() -> Array[ScenarioRun]

Run the built-in conformance catalog.

#
run_resilient_scenario

source
fn run_resilient_scenario(scenario : ResilientScenario) -> ScenarioRun

Run one scenario through the full resilient encoder and decoder.

#
scenario_passes

source
fn scenario_passes(run : ScenarioRun) -> Bool

Return true if one scenario run matches its expected outcome.

#
scenario_payload

source
fn scenario_payload(scenario : ResilientScenario) -> Array[Int]

Build the deterministic payload for one scenario.

#
validate_card

source
fn validate_card(card : ShardCard) -> Bool

Check the checksum carried by one card.

#
validate_resilient_card

source
fn validate_resilient_card(card : ResilientShardCard) -> Bool

Check the checksum carried by one resilient card.

#
validation_commands

source
fn validation_commands() -> Array[String]

Return the expected validation commands for this package.

#
weave

source
fn weave(deck : String, payload : Array[Int], data_count : Int) -> Array[ShardCard]

Build data cards plus one parity card. The parity card can recover one missing data card, and every card carries a checksum for copy mistakes.

#
weave_resilient

source
fn weave_resilient(deck : String, payload : Array[Int], data_count : Int, parity_count : Int) -> Array[ResilientShardCard]

Build data cards plus parity_count parity cards.

Parity rows use a small systematic Reed-Solomon-style construction over GF(256). The first parity row is compatible with XOR parity, while later rows provide independent equations for multi-card recovery.

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io