Decoding (Recovery) Process Flow

The decoding process, also referred to as recovery, is the core function for retrieving the original 13-character generator code from a 55-character seed. This process is the inverse of the encoding operation and relies on the same deterministic EncodingSystem objects generated from a master seed. The system is designed to be highly reliable, offering multiple recovery modes to handle seeds created by different encoding systems (Original or Deviation).

The recovery flow is initiated by the user in the "Recover Code" tab of the application. The user provides a seed and selects a recovery strategy. The system then attempts to validate the seed against one or more of the generated encoding systems. A successful recovery yields the original 13-letter generator code, while a failure indicates that the provided seed is invalid for the tested system(s).

Sources: README.md, index.html:158-171

User Interaction and Recovery Modes

The user initiates the recovery process from the "Recover Code" tab. The flow begins with user input and mode selection, which dictates the strategy the application will use to find the correct generator code.

Sources: index.html:158-171

This diagram illustrates the user's journey from entering the seed to receiving the recovery result.

Recovery Modes

The UI provides three distinct modes for recovering the generator code.

Sources: index.html:162-165, index.html:168-171, index.html:1010-1017, index.html:1052-1070

High-Level Recovery Logic

The recoverGeneratorCode() function is the entry point for the entire recovery process. It orchestrates the flow based on the user's selected mode.

Sources: index.html:1006-1077

The following diagram shows the logical branching within the recoverGeneratorCode() function.

If the "Sequential Recovery" mode is chosen, the function iterates through the allSystems array. For each system, it calls system.recoverGeneratorCode(seed). If a call succeeds, the process stops, and the result is displayed. If it fails (throws an error), the loop continues to the next system. If all systems fail, a final error message is shown.

Sources: index.html:1018-1049

EncodingSystem Class and Recovery Methods

The core decoding logic resides within the EncodingSystem class, which has two distinct recovery methods corresponding to the system's type: recoverGeneratorCodeOriginal and recoverGeneratorCodeDeviation.

Sources: index.html:500-506, README.md

This class diagram shows the structure of the EncodingSystem class and its key methods.

Detailed Single-System Recovery Flow

Both recoverGeneratorCodeOriginal and recoverGeneratorCodeDeviation follow a similar pattern to reverse the encoding process. The primary difference lies in the structure of the parity data they expect to find.

1. Input Validation: The 55-letter seed is validated to ensure it contains only lowercase letters.
2. Inverse Permutation: The seed is converted from letters to numbers, and the inverse permutation is applied to restore the original order of the codeword components (message and parity).
3. Data Separation: The de-permuted codeword is split into the message part (the first 13 numbers) and the parity part(s).
4. Parity Verification: The expected parity is recalculated from the message part using matrix-vector multiplication. This calculated parity is then compared against the parity part extracted from the seed.
5. Result: If the parities match, the 13-number message is converted back to letters and returned as the recovered generator code. If they do not match, an error is thrown, indicating a failed recovery attempt for that system.

Sources: index.html:573-644, README.md

The flowchart below details these steps for a single recovery attempt.

Original System Recovery (recoverGeneratorCodeOriginal)

This method handles seeds created by an 'original' type system.

• The de-permuted codeword is split into a 13-element message and a 42-element parity.
• The expected parity is calculated by multiplying the P matrix (42x13) with the message vector.
• The result is negated (mod 26) and compared element-wise with the parity from the seed.

Sources: index.html:573-594

Deviation System Recovery (recoverGeneratorCodeDeviation)

This method handles seeds from a 'deviation' type system.

• The de-permuted codeword is split into a 13-element message, a 15-element parity1, and a 27-element parity2.
• expectedParity1 is calculated using the P1 matrix (15x13).
• expectedParity2 is calculated using the P2 matrix (27x13).
• Both calculated parities are negated (mod 26) and compared against parity1 and parity2 from the seed, respectively. Both must match for the recovery to be successful.

Sources: index.html:596-628

Conclusion

The decoding and recovery process in qib13 is a robust, multi-layered system designed for high reliability. It leverages deterministic generation from a master seed to ensure that the same systems used for encoding are available for decoding. The core of the process is the reversal of the encoding steps: applying an inverse permutation and verifying parity checks through matrix multiplication. The inclusion of multiple recovery modes, especially the sequential search, provides resilience and significantly increases the probability of successfully recovering a generator code even when the originating system is unknown.

Sources: README.md, index.html:1006-1077