Fragmental Overlap Storage System (FOSS) JSON Ladder Specification (README)

Overview
The JSON Ladder defines how data is segmented, searched, and resolved during ingestion.
It is a deterministic execution plan, not a heuristic.

This means:  
    Same input -> same fragments -> same output  
    No randomness  
    No probabilistic matching  

Core Concept

Traditional systems:
	Try to optimize full files

FOSS:  
    Decomposes data into fragments using a structured traversal model  

The ladder defines a deterministic segmentation control structure that governs:  
    Candidate fragment sizes  
    Traversal order  
    Boundary-aligned region evaluation  
    Emission behavior for fragment descriptors and literals  

Example (Slide Mode)
{
"fallback": 1024,
"resolve": "longest",
"tie_break": "head",
"entry": "<",
"chain": [
{
"mode": "slide",
"stride": 128,
"peel": "forward",
"dir": "desc",
"min": 128,
"max": 1024,
"ladder": [1024,768,512,256,192,128]
}
]
}

Example (Nest Mode)
{
"fallback": 1024,
"resolve": "longest",
"tie_break": "head",
"entry": "<",
"chain": [
{
"mode": "nest",
"peel": "forward",
"dir": "desc",
"min": 128,
"max": 1024,
"ladder": [1024,768,512,256,192,128]
}
]
}

Example (Step Mode)
{
"fallback": 1024,
"resolve": "longest",
"tie_break": "head",
"entry": "<",
"chain": [
{
"mode": "step",
"peel": "forward",
"dir": "desc",
"min": 128,
"max": 1024,
"ladder": [1024,768,512,256,192,128]
}
]
}

Top-Level Fields

fallback  
    "fallback": 1024  

    Defines the literal emission size when no candidate fragment match is identified.  
    Guarantees forward progress of traversal.  

    Constraint:  
        fallback must be greater than 0 and less than or equal to the remaining region length.  

    Rule:  
        if fallback == 0 or fallback > remaining:  
            fallback = remaining  

resolve  
    "resolve": "longest"  

    Defines deterministic selection behavior when multiple candidate fragment matches exist at a given evaluation step.  

    Options:  
        "longest" selects the largest matching candidate region.  
        "first" selects the first matching candidate encountered according to traversal order.  

tie_break  
    "tie_break": "head"  

    Defines deterministic selection when multiple candidate matches are equal in size.  

    Options:  
        "head" selects the earliest boundary-aligned region.  
        "tail" selects the latest boundary-aligned region.  

entry  
    "entry": "<"  

	Defines the deterministic entry condition for ladder evaluation at the start of segmentation.  

	Entry specifies a constraint governing how candidate fragment sizes are evaluated relative to the current region during initial segmentation.  

	Entry controls whether the segmentation engine prioritizes subdivision of the region or permits evaluation of candidate regions that may span a larger portion of the current region.  

	In certain embodiments, entry influences whether evaluation begins with ladder-defined fragment sizes that enforce immediate subdivision or allows evaluation of candidate regions that may correspond to the full extent of the current region.  

	Entry operates as a deterministic constraint on candidate region evaluation and does not define traversal direction.  
	Traversal direction is defined separately by the peel parameter.  

	The interpretation of entry values is implementation-defined but must remain deterministic and consistent across executions.   

Chain Execution
	"chain": [ ... ]

	Defines the ordered sequence of deterministic segmentation strategies applied to the input region.  
	Each element in the chain represents a traversal mode executed under fixed rules.  

	The segmentation engine processes each chain element sequentially while consuming the input region through emission of fragment descriptors and literal segments.  

Chain Element Fields

mode  
    "mode": "slide"  

    Defines the deterministic traversal mode used to evaluate candidate regions.  

Modes

slide  
    Evaluates candidate fragment sizes across multiple shifted boundary-aligned positions within the remaining input region.  
    Boundary positions are advanced using a fixed deterministic increment.  

    For a given ladder rung, all candidate positions within the defined search range are evaluated prior to advancing to the next rung.  

    If a match is found, a fragment descriptor is emitted and traversal advances.  
    If no match is found across all positions and all rungs, a literal is emitted.  

    Slide mode enables complete positional coverage under defined increment and range conditions.  

step  
    Evaluates ladder-defined candidate sizes sequentially at the current boundary-aligned position.  
    Each evaluation results in emission of either a fragment descriptor or a literal.  
    Traversal advances after each evaluation regardless of match.  

    Step mode guarantees linear deterministic progression through the input region.  

nest  
    Performs recursive refinement within a region when larger ladder rungs do not produce a match.  
    Smaller ladder rungs are evaluated within the same region.  

    Nest mode enables identification of sub-fragments and hierarchical decomposition of the input region.  

stride  
    "stride": 128  

    Defines the boundary increment used in slide mode.  

    Constraint:  
        stride must only appear in slide mode and must not be present in nest or step.  

peel  
    "peel": "forward"  

    Defines the direction in which matched or emitted regions are removed from the remaining input region.  

    Options:  
        "forward" consumes regions from the start of the remaining region.  
        "reverse" consumes regions from the end of the remaining region.  

dir  
    "dir": "desc"  

    Defines the deterministic ordering of ladder evaluation.  

    Options:  
        "desc" evaluates larger fragment sizes first.  
        "asc" evaluates smaller fragment sizes first.
        "none" evaluates unordered list of fragment sizes.		

min / max  
    "min": 128  
    "max": 1024  

    Define the allowed bounds for candidate fragment sizes.  

ladder  
    "ladder": [1024,768,512,256,192,128]  

    Defines the ordered set of candidate fragment sizes used during evaluation.  
    Each value represents a ladder rung.  

Execution Model (Simplified)

The segmentation process begins according to the defined entry condition and traversal configuration.  

For each chain element:  
    Candidate fragment regions are selected according to ladder-defined sizes and traversal rules.  
    Boundary-aligned regions are evaluated for fragment matching.  
    The resolve and tie_break rules determine deterministic selection when multiple matches exist.  

    If a match is identified:  
        A fragment descriptor is emitted.  
        The matched region is removed from the remaining input region.  

    If no match is identified:  
        A literal segment is emitted using the fallback size.  
        The corresponding region is removed from the remaining input region.  

The process continues until the input region is fully consumed.  

Key Properties

Deterministic  
    No randomness  
    Identical inputs produce identical outputs  

Complete Coverage  
    All bytes are consumed  
    No gaps or ambiguity exist  

Symmetric  
    The same ladder and traversal configuration enable ingest, reconstruction, and verification  

Design Philosophy

The ladder is not configuration.
It is a declarative execution program that defines how data is segmented, interpreted, and reconstructed under deterministic rules.  

Practical Guidance

Larger ladder rungs should be evaluated early to maximize fragment reuse.
Smaller ladder rungs ensure coverage when larger matches are not found.
Slide mode should be used when alignment uncertainty exists.
Nest mode should be used for structural refinement.
Step mode guarantees deterministic completion of traversal.

Important Note

This system is not heuristic, not probabilistic, and not approximate.
It is deterministic structural decomposition.  

One-Line Summary

The JSON Ladder defines a deterministic execution framework for fragmenting data into reusable regions using fixed traversal rules and reproducible segmentation behavior.