How to Recover a Generator Code

Relevant source files

The following files were used as context for generating this wiki page:

• index.html
• README.md
• LICENSE
• .gitignore

The qib13 system provides a mechanism to recover a 13-character generator code from a 55-character seed. This process is the reverse of seed generation and relies on the same deterministic, reproducible encoding systems. Successful recovery is contingent on using the exact same masterSeed that was used to generate the systems during the initial encoding phase. The recovery feature is designed to be robust, with options to try multiple encoding systems sequentially to find the correct one.

Sources: README.md:10-14, index.html:151-153

Prerequisites: System Generation

Before a generator code can be recovered, the set of EncodingSystem objects must be present in the application's memory. These systems are generated deterministically from a masterSeed. To recover a code, you must first generate the systems using the same master seed that was used to create the original seed.

The UI provides two ways to do this in the "Generate Systems" tab:

1. generateSystems(): Uses a user-provided masterSeed and a specified number of deviation systems. If no master seed is provided, it falls back to a default value.
2. useDefaultSystems(): A convenience function that generates a predefined set of 1 original and 10 deviation systems using a hardcoded default master seed.

This diagram illustrates the prerequisite step of system generation.

Recovery User Interface

The recovery functionality is accessed via the "Recover Code" tab in the web interface.

Sources: index.html:89-91, index.html:151-167

The UI consists of the following components:

Component	ID / Name	Description
Seed Input	seedInput	A text field for entering the 55-letter seed that needs to be decoded.
Recovery Mode	recoverMode	A set of radio buttons to select the recovery strategy.
Specific System Index	specificSystemIndex	A number input that appears when "Try Specific System" is selected, allowing the user to target one system.
Recover Button	N/A	The button that triggers the recoverGeneratorCode() function.
Result Display	recoverResult	A div element where the outcome (success or failure) of the recovery attempt is displayed.

Sources: index.html:153-166

Recovery Modes

The user can choose from three different recovery strategies, which determine how the application attempts to find the correct encoding system.

Mode	Value	Behavior
Sequential Recovery	sequential	Tries every available system (allSystems array) in order until one successfully recovers the code. This is the most robust method.
Try Original Only	original	Attempts recovery using only the first system (allSystems[0]), which is the 'original' type.
Try Specific System	specific	Attempts recovery using only the system at the user-specified index.

Sources: index.html:156-158, index.html:1044-1081

Recovery Process Flow

The recovery process is initiated by the recoverGeneratorCode() function, which orchestrates the decoding attempt based on the selected mode.

This sequence diagram shows the interaction when a user clicks the "Recover Generator Code" button in 'Sequential' mode.

recoverGeneratorCode() Function Logic

This function acts as the main controller for the recovery operation.

1. It first checks if the allSystems array has been populated. If not, it displays an error.
2. It reads the 55-letter seed from the input field and gets the selected mode.
3. Based on the mode, it calls the recoverGeneratorCode(seed) method on the appropriate EncodingSystem object(s).
   • sequential: It iterates through the allSystems array, calling the method on each system. The loop breaks on the first successful recovery. If all fail, a final error is shown.
   • original: It calls the method only on allSystems[0].
   • specific: It calls the method on the system at the user-provided index (allSystems[systemIndex]).
4. Any successful recovery is displayed to the user. Errors from individual system attempts are caught and, in sequential mode, logged.

Sources: index.html:1042-1120

// File: index.html
function recoverGeneratorCode() {
    const seed = document.getElementById('seedInput').value.trim();
    const mode = getSelectedMode('recover');
    // ...
    try {
        let generatorCode;
        let attempts = [];

        if (mode === 'sequential') {
            for (let i = 0; i < allSystems.length; i++) {
                const system = allSystems[i];
                try {
                    generatorCode = system.recoverGeneratorCode(seed);
                    // ... display success and return
                    return;
                } catch (e) {
                    attempts.push(`System ${system.id}: ${e.message}`);
                }
            }
            throw new Error(`All ${allSystems.length} systems failed.`);
        } else if (mode === 'original') {
            // ... try allSystems[0]
        } else if (mode === 'specific') {
            // ... try system at specific index
        }
        // ... display success
    } catch (error) {
        // ... display error
    }
}

Sources: index.html:1042-1120

Core Decoding Algorithm

The actual decoding logic resides within the EncodingSystem class, specifically in the recoverGeneratorCodeOriginal and recoverGeneratorCodeDeviation methods. Both methods follow a similar pattern of reversing the encoding process.

Sources: index.html:565-643

The general algorithm is as follows:

1. Input Validation: Check if the seed is 55 lowercase letters.
2. Convert to Numbers: Transform the 55-letter seed into an array of 55 numbers (0-25).
3. Inverse Permutation: Apply the system's inversePermutation to the numeric array to undo the shuffling from the encoding step.
4. Split Codeword: Separate the unshuffled numeric array into the message (first 13 numbers) and parity parts.
5. Parity Verification:
   • Recalculate the expected parity by performing matrix-vector multiplication (matrixVectorMultiplyMod26) between the system's parity matrix (e.g., P, P1, P2) and the recovered message.
   • Negate the result ((-x + 26) % 26).
   • Compare the recalculated, negated parity with the parity part recovered from the seed.
6. Result: If all parity checks pass, convert the message numbers back to letters and return the 13-character generator code. If any check fails, throw an error.

This flowchart details the internal steps of the recovery algorithm within an EncodingSystem object.

Algorithm Variants

The EncodingSystem class has two types, original and deviation, each with a slightly different recovery method.

• recoverGeneratorCodeOriginal(seed): This method expects a single parity block of 42 numbers. It performs one parity check using the matrices.P (a 42x13 matrix).
• recoverGeneratorCodeDeviation(seed): This method expects two parity blocks: parity1 (15 numbers) and parity2 (27 numbers). It performs two separate parity checks: one for parity1 using matrices.P1 (15x13) and another for parity2 using matrices.P2 (27x13). Both must pass for the recovery to be successful.

Sources: index.html:584-605, index.html:607-643

Conclusion

Recovering a generator code in qib13 is a deterministic process that reverses the steps of seed generation. Its success hinges on having the correct masterSeed to reproduce the exact set of encoding systems. The system's architecture, particularly the "Sequential Recovery" mode, provides a high degree of reliability by systematically trying all possible decoding schemes until the correct one is found. This multi-system approach makes the recovery process resilient to scenarios where the exact encoding system used is unknown.

Sources: README.md:10-14, README.md:148-151