kyo-system layering proposal (getkyo/kyo#1852)

kyo-system-layering-dark.svg

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
 "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<!-- Generated by graphviz version 15.1.1 (20260805.0921)
 -->
<!-- Title: kyo_layering Pages: 1 -->
<svg width="825pt" height="541pt"
 viewBox="0.00 0.00 825.00 541.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 537.32)">
<title>kyo_layering</title>
<text xml:space="preserve" text-anchor="start" x="179.28" y="-515.12" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="16.00" fill="#e6edf3">kyo&#45;system provides file operations to every schema format</text>
<text xml:space="preserve" text-anchor="start" x="139.9" y="-492.87" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#a8b3c0">Solid = depends on. &#160;&#160;Dashed = provides </text>
<text xml:space="preserve" text-anchor="start" x="338.65" y="-492.87" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="11.00" fill="#a8b3c0">path.readAs[A]</text>
<text xml:space="preserve" text-anchor="start" x="418.15" y="-492.87" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#a8b3c0"> / </text>
<text xml:space="preserve" text-anchor="start" x="427.15" y="-492.87" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="11.00" fill="#a8b3c0">path.writeAs[A]</text>
<text xml:space="preserve" text-anchor="start" x="508.9" y="-492.87" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#a8b3c0"> to every format via the Codec SPI.</text>
<text xml:space="preserve" text-anchor="start" x="406.9" y="-481.87" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e6edf3"> </text>
<!-- system -->
<g id="node1" class="node">
<title>system</title>
<path fill="#3b2f52" stroke="#b69be0" stroke-width="2" d="M207.18,-452.41C207.18,-452.41 12,-452.41 12,-452.41 6,-452.41 0,-446.41 0,-440.41 0,-440.41 0,-405.19 0,-405.19 0,-399.19 6,-393.19 12,-393.19 12,-393.19 207.18,-393.19 207.18,-393.19 213.18,-393.19 219.18,-399.19 219.18,-405.19 219.18,-405.19 219.18,-440.41 219.18,-440.41 219.18,-446.41 213.18,-452.41 207.18,-452.41"/>
<text xml:space="preserve" text-anchor="middle" x="109.59" y="-430.7" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="13.00" fill="#e6edf3">kyo&#45;system</text>
<text xml:space="preserve" text-anchor="middle" x="109.59" y="-417.2" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="13.00" fill="#e6edf3">Path · FileSystem · Process</text>
<text xml:space="preserve" text-anchor="middle" x="109.59" y="-403.7" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="13.00" fill="#e6edf3">codec&#45;generic file operations</text>
</g>
<!-- sjson -->
<g id="node2" class="node">
<title>sjson</title>
<path fill="#22392a" stroke="#6fc98a" stroke-width="1.6" d="M478.81,-444.91C478.81,-444.91 302.38,-444.91 302.38,-444.91 296.38,-444.91 290.38,-438.91 290.38,-432.91 290.38,-432.91 290.38,-412.69 290.38,-412.69 290.38,-406.69 296.38,-400.69 302.38,-400.69 302.38,-400.69 478.81,-400.69 478.81,-400.69 484.81,-400.69 490.81,-406.69 490.81,-412.69 490.81,-412.69 490.81,-432.91 490.81,-432.91 490.81,-438.91 484.81,-444.91 478.81,-444.91"/>
<text xml:space="preserve" text-anchor="middle" x="390.59" y="-424.15" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="12.00" fill="#e6edf3">kyo&#45;schema&#45;json</text>
<text xml:space="preserve" text-anchor="middle" x="390.59" y="-411.4" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="12.00" fill="#e6edf3">Json · Json.Lines · Jsonl.pipe</text>
</g>
<!-- system&#45;&gt;sjson -->
<g id="edge12" class="edge">
<title>system&#45;&gt;sjson</title>
<path fill="none" stroke="#b69be0" stroke-width="1.8" stroke-dasharray="5,2" d="M220.18,-422.8C240.02,-422.8 259.85,-422.8 279.69,-422.8"/>
<polygon fill="#b69be0" stroke="#b69be0" stroke-width="1.8" points="287.55,-422.8 279.55,-426.4 285.74,-423.2 279.55,-423.2 279.55,-422.8 279.55,-422.4 285.74,-422.4 279.55,-419.2 287.55,-422.8"/>
</g>
<!-- syaml -->
<g id="node3" class="node">
<title>syaml</title>
<path fill="#22392a" stroke="#6fc98a" d="M646.68,-440.8C646.68,-440.8 538.5,-440.8 538.5,-440.8 532.5,-440.8 526.5,-434.8 526.5,-428.8 526.5,-428.8 526.5,-416.8 526.5,-416.8 526.5,-410.8 532.5,-404.8 538.5,-404.8 538.5,-404.8 646.68,-404.8 646.68,-404.8 652.68,-404.8 658.68,-410.8 658.68,-416.8 658.68,-416.8 658.68,-428.8 658.68,-428.8 658.68,-434.8 652.68,-440.8 646.68,-440.8"/>
<text xml:space="preserve" text-anchor="middle" x="592.59" y="-417.78" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="12.00" fill="#e6edf3">kyo&#45;schema&#45;yaml</text>
</g>
<!-- system&#45;&gt;syaml -->
<g id="edge13" class="edge">
<title>system&#45;&gt;syaml</title>
<path fill="none" stroke="#b69be0" stroke-width="1.4" stroke-dasharray="5,2" d="M220.01,-453.37C296.5,-470.15 400.39,-484.19 490.59,-465.91 510.99,-461.78 532.38,-453.43 550.28,-445.17"/>
<polygon fill="#b69be0" stroke="#b69be0" stroke-width="1.4" points="557.22,-441.87 551.54,-448.55 555.23,-443.03 550.08,-445.48 549.99,-445.3 549.91,-445.12 555.06,-442.67 548.45,-442.05 557.22,-441.87"/>
</g>
<!-- sother -->
<g id="node4" class="node">
<title>sother</title>
<path fill="#22392a" stroke="#6fc98a" d="M804.81,-444.91C804.81,-444.91 706.38,-444.91 706.38,-444.91 700.38,-444.91 694.38,-438.91 694.38,-432.91 694.38,-432.91 694.38,-412.69 694.38,-412.69 694.38,-406.69 700.38,-400.69 706.38,-400.69 706.38,-400.69 804.81,-400.69 804.81,-400.69 810.81,-400.69 816.81,-406.69 816.81,-412.69 816.81,-412.69 816.81,-432.91 816.81,-432.91 816.81,-438.91 810.81,-444.91 804.81,-444.91"/>
<text xml:space="preserve" text-anchor="middle" x="755.59" y="-424.15" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="12.00" fill="#e6edf3">msgpack · bson</text>
<text xml:space="preserve" text-anchor="middle" x="755.59" y="-411.4" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="12.00" fill="#e6edf3">ion · protobuf</text>
</g>
<!-- system&#45;&gt;sother -->
<g id="edge14" class="edge">
<title>system&#45;&gt;sother</title>
<path fill="none" stroke="#b69be0" stroke-width="1.4" stroke-dasharray="5,2" d="M219.89,-453.39C243.07,-458.6 267.49,-463.2 290.59,-465.91 371.81,-475.45 578.59,-482.89 658.59,-465.91 674.87,-462.46 691.72,-456.08 706.73,-449.27"/>
<polygon fill="#b69be0" stroke="#b69be0" stroke-width="1.4" points="713.79,-445.95 708.08,-452.61 711.8,-447.1 706.64,-449.53 706.55,-449.35 706.47,-449.17 711.63,-446.74 705.02,-446.09 713.79,-445.95"/>
</g>
<!-- schema -->
<g id="node5" class="node">
<title>schema</title>
<path fill="#1e4630" stroke="#5fb87a" stroke-width="1.6" d="M593.18,-338.19C593.18,-338.19 470,-338.19 470,-338.19 464,-338.19 458,-332.19 458,-326.19 458,-326.19 458,-305.97 458,-305.97 458,-299.97 464,-293.97 470,-293.97 470,-293.97 593.18,-293.97 593.18,-293.97 599.18,-293.97 605.18,-299.97 605.18,-305.97 605.18,-305.97 605.18,-326.19 605.18,-326.19 605.18,-332.19 599.18,-338.19 593.18,-338.19"/>
<text xml:space="preserve" text-anchor="middle" x="531.59" y="-317.43" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="12.00" fill="#e6edf3">kyo&#45;schema</text>
<text xml:space="preserve" text-anchor="middle" x="531.59" y="-304.68" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="12.00" fill="#e6edf3">Schema · Codec SPI</text>
</g>
<!-- system&#45;&gt;schema -->
<g id="edge2" class="edge">
<title>system&#45;&gt;schema</title>
<path fill="none" stroke="#c0a5e8" stroke-width="2.2" d="M219.91,-394.42C290.82,-376.83 381.53,-354.32 446.79,-338.12"/>
<polygon fill="#c0a5e8" stroke="#c0a5e8" stroke-width="2.2" points="447.12,-340.93 454.21,-336.28 445.77,-335.49 447.12,-340.93"/>
</g>
<!-- core -->
<g id="node6" class="node">
<title>core</title>
<path fill="#4a3620" stroke="#e0a857" stroke-width="1.6" d="M227.43,-338.19C227.43,-338.19 99.75,-338.19 99.75,-338.19 93.75,-338.19 87.75,-332.19 87.75,-326.19 87.75,-326.19 87.75,-305.97 87.75,-305.97 87.75,-299.97 93.75,-293.97 99.75,-293.97 99.75,-293.97 227.43,-293.97 227.43,-293.97 233.43,-293.97 239.43,-299.97 239.43,-305.97 239.43,-305.97 239.43,-326.19 239.43,-326.19 239.43,-332.19 233.43,-338.19 227.43,-338.19"/>
<text xml:space="preserve" text-anchor="middle" x="163.59" y="-317.43" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="12.00" fill="#e6edf3">kyo&#45;core</text>
<text xml:space="preserve" text-anchor="middle" x="163.59" y="-304.68" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="12.00" fill="#e6edf3">Sync · Async · Scope</text>
</g>
<!-- system&#45;&gt;core -->
<g id="edge1" class="edge">
<title>system&#45;&gt;core</title>
<path fill="none" stroke="#c0a5e8" stroke-width="2.2" d="M124.78,-392.35C131.79,-378.76 140.12,-362.6 147.26,-348.74"/>
<polygon fill="#c0a5e8" stroke="#c0a5e8" stroke-width="2.2" points="149.75,-350.03 150.93,-341.63 144.77,-347.46 149.75,-350.03"/>
</g>
<!-- sjson&#45;&gt;schema -->
<g id="edge3" class="edge">
<title>sjson&#45;&gt;schema</title>
<path fill="none" stroke="#a8b3c0" stroke-width="1.2" d="M419.81,-400.1C441.55,-383.95 471.38,-361.8 494.75,-344.44"/>
<polygon fill="#a8b3c0" stroke="#a8b3c0" stroke-width="1.2" points="496.2,-346.85 500.95,-339.83 492.86,-342.36 496.2,-346.85"/>
</g>
<!-- prelude -->
<g id="node7" class="node">
<title>prelude</title>
<path fill="#1f3552" stroke="#7fb0e8" stroke-width="1.6" d="M400.18,-238.97C400.18,-238.97 277,-238.97 277,-238.97 271,-238.97 265,-232.97 265,-226.97 265,-226.97 265,-194 265,-194 265,-188 271,-182 277,-182 277,-182 400.18,-182 400.18,-182 406.18,-182 412.18,-188 412.18,-194 412.18,-194 412.18,-226.97 412.18,-226.97 412.18,-232.97 406.18,-238.97 400.18,-238.97"/>
<text xml:space="preserve" text-anchor="middle" x="338.59" y="-218.21" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="12.00" fill="#e6edf3">kyo&#45;prelude</text>
<text xml:space="preserve" text-anchor="middle" x="338.59" y="-205.46" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="12.00" fill="#e6edf3">Stream · Pipe · Abort</text>
<text xml:space="preserve" text-anchor="middle" x="338.59" y="-192.71" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="12.00" fill="#e6edf3">(pure, no threads)</text>
</g>
<!-- sjson&#45;&gt;prelude -->
<g id="edge6" class="edge">
<title>sjson&#45;&gt;prelude</title>
<path fill="none" stroke="#79b8ff" stroke-width="2.6" d="M379.88,-399.97C372.19,-383.4 362.19,-359.84 356.34,-338.19 348.62,-309.63 344.13,-276.48 341.6,-251.26"/>
<polygon fill="#79b8ff" stroke="#79b8ff" stroke-width="2.6" points="344.4,-251.19 340.87,-243.49 338.83,-251.71 344.4,-251.19"/>
<text xml:space="preserve" text-anchor="start" x="379.97" y="-322.58" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="10.00" fill="#79b8ff"> &#160;NEW &#160;</text>
<text xml:space="preserve" text-anchor="start" x="356.34" y="-312.58" font-family="Helvetica,sans-Serif" font-size="10.00" fill="#79b8ff"> &#160;streaming without</text>
<text xml:space="preserve" text-anchor="start" x="370.59" y="-302.58" font-family="Helvetica,sans-Serif" font-size="10.00" fill="#79b8ff"> &#160;the runtime</text>
</g>
<!-- syaml&#45;&gt;schema -->
<g id="edge4" class="edge">
<title>syaml&#45;&gt;schema</title>
<path fill="none" stroke="#a8b3c0" stroke-width="1.2" d="M582.52,-404.51C573.46,-388.96 559.96,-365.78 549.13,-347.19"/>
<polygon fill="#a8b3c0" stroke="#a8b3c0" stroke-width="1.2" points="551.58,-345.83 545.13,-340.33 546.74,-348.65 551.58,-345.83"/>
</g>
<!-- sother&#45;&gt;schema -->
<g id="edge5" class="edge">
<title>sother&#45;&gt;schema</title>
<path fill="none" stroke="#a8b3c0" stroke-width="1.2" d="M709.45,-400.23C674,-383.66 624.89,-360.7 587.26,-343.11"/>
<polygon fill="#a8b3c0" stroke="#a8b3c0" stroke-width="1.2" points="588.52,-340.6 580.09,-339.75 586.15,-345.68 588.52,-340.6"/>
</g>
<!-- data -->
<g id="node10" class="node">
<title>data</title>
<path fill="#2a3340" stroke="#8aa0bc" d="M477.18,-36C477.18,-36 420,-36 420,-36 414,-36 408,-30 408,-24 408,-24 408,-12 408,-12 408,-6 414,0 420,0 420,0 477.18,0 477.18,0 483.18,0 489.18,-6 489.18,-12 489.18,-12 489.18,-24 489.18,-24 489.18,-30 483.18,-36 477.18,-36"/>
<text xml:space="preserve" text-anchor="middle" x="448.59" y="-12.97" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="12.00" fill="#e6edf3">kyo&#45;data</text>
</g>
<!-- schema&#45;&gt;data -->
<g id="edge7" class="edge">
<title>schema&#45;&gt;data</title>
<path fill="none" stroke="#a8b3c0" stroke-width="1.2" d="M525.49,-293.31C510.55,-240.03 472.21,-103.25 456,-45.43"/>
<polygon fill="#a8b3c0" stroke="#a8b3c0" stroke-width="1.2" points="458.76,-44.92 453.91,-37.97 453.37,-46.43 458.76,-44.92"/>
</g>
<!-- core&#45;&gt;prelude -->
<g id="edge8" class="edge">
<title>core&#45;&gt;prelude</title>
<path fill="none" stroke="#a8b3c0" stroke-width="1.2" d="M200.28,-293.36C224.16,-279.22 255.78,-260.5 282.76,-244.53"/>
<polygon fill="#a8b3c0" stroke="#a8b3c0" stroke-width="1.2" points="283.95,-247.08 289.41,-240.6 281.1,-242.26 283.95,-247.08"/>
</g>
<!-- scheduler -->
<g id="node8" class="node">
<title>scheduler</title>
<path fill="#3d2e1c" stroke="#e0a857" d="M208.31,-232.6C208.31,-232.6 118.88,-232.6 118.88,-232.6 112.88,-232.6 106.88,-226.6 106.88,-220.6 106.88,-220.6 106.88,-200.38 106.88,-200.38 106.88,-194.38 112.88,-188.38 118.88,-188.38 118.88,-188.38 208.31,-188.38 208.31,-188.38 214.31,-188.38 220.31,-194.38 220.31,-200.38 220.31,-200.38 220.31,-220.6 220.31,-220.6 220.31,-226.6 214.31,-232.6 208.31,-232.6"/>
<text xml:space="preserve" text-anchor="middle" x="163.59" y="-211.84" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="12.00" fill="#e6edf3">kyo&#45;scheduler</text>
<text xml:space="preserve" text-anchor="middle" x="163.59" y="-199.09" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="12.00" fill="#e6edf3">(threads)</text>
</g>
<!-- core&#45;&gt;scheduler -->
<g id="edge9" class="edge">
<title>core&#45;&gt;scheduler</title>
<path fill="none" stroke="#a8b3c0" stroke-width="1.2" d="M163.59,-293.36C163.59,-278.62 163.59,-258.91 163.59,-242.52"/>
<polygon fill="#a8b3c0" stroke="#a8b3c0" stroke-width="1.2" points="166.39,-242.63 163.59,-234.63 160.79,-242.63 166.39,-242.63"/>
</g>
<!-- kernel -->
<g id="node9" class="node">
<title>kernel</title>
<path fill="#2a3340" stroke="#8aa0bc" d="M417.43,-127C417.43,-127 349.75,-127 349.75,-127 343.75,-127 337.75,-121 337.75,-115 337.75,-115 337.75,-103 337.75,-103 337.75,-97 343.75,-91 349.75,-91 349.75,-91 417.43,-91 417.43,-91 423.43,-91 429.43,-97 429.43,-103 429.43,-103 429.43,-115 429.43,-115 429.43,-121 423.43,-127 417.43,-127"/>
<text xml:space="preserve" text-anchor="middle" x="383.59" y="-103.97" font-family="Helvetica,sans-Serif" font-weight="bold" font-size="12.00" fill="#e6edf3">kyo&#45;kernel</text>
</g>
<!-- prelude&#45;&gt;kernel -->
<g id="edge10" class="edge">
<title>prelude&#45;&gt;kernel</title>
<path fill="none" stroke="#a8b3c0" stroke-width="1.2" d="M351.36,-181.24C357.8,-167.01 365.55,-149.87 371.84,-135.97"/>
<polygon fill="#a8b3c0" stroke="#a8b3c0" stroke-width="1.2" points="374.24,-137.47 374.99,-129.02 369.14,-135.16 374.24,-137.47"/>
</g>
<!-- kernel&#45;&gt;data -->
<g id="edge11" class="edge">
<title>kernel&#45;&gt;data</title>
<path fill="none" stroke="#a8b3c0" stroke-width="1.2" d="M396.12,-90.84C405.77,-77.63 419.26,-59.17 430.14,-44.27"/>
<polygon fill="#a8b3c0" stroke="#a8b3c0" stroke-width="1.2" points="432.35,-45.99 434.8,-37.88 427.82,-42.69 432.35,-45.99"/>
</g>
</g>
</svg>

kyo-system-layering.dot

digraph kyo_layering {
    rankdir=TB;
    bgcolor="white";
    compound=true;
    node [shape=box, style="filled,rounded", fontname="Helvetica-Bold", fontsize=12, margin="0.22,0.13"];
    edge [fontname="Helvetica", fontsize=10, color="#5A6472", arrowsize=0.8, penwidth=1.2];
    graph [fontname="Helvetica", fontsize=11, ranksep=0.75, nodesep=0.5];

    labelloc="t";
    label=<<b><font point-size="16">kyo-system provides file operations to every schema format</font></b><br/><br/><font point-size="11" color="#5A6472">Solid = depends on.   Dashed = provides <b>path.readAs[A]</b> / <b>path.writeAs[A]</b> to every format via the Codec SPI.</font><br/> >;

    // ============ LAYER 4 : system ============
    system [label="kyo-system\nPath · FileSystem · Process\ncodec-generic file operations",
            fillcolor="#E2D7F0", color="#8B6FB8", penwidth=2.0, fontsize=13];

    // ============ LAYER 3 : formats ============
    sjson  [label="kyo-schema-json\nJson · Json.Lines · Jsonl.pipe", fillcolor="#DCEFE0", color="#7FB08D", penwidth=1.6];
    syaml  [label="kyo-schema-yaml",  fillcolor="#DCEFE0", color="#7FB08D"];
    sother [label="msgpack · bson\nion · protobuf", fillcolor="#DCEFE0", color="#7FB08D"];

    // ============ LAYER 2 : schema core + runtime ============
    schema [label="kyo-schema\nSchema · Codec SPI", fillcolor="#CFE6D4", color="#5F9B70", penwidth=1.6];
    core   [label="kyo-core\nSync · Async · Scope", fillcolor="#F5D3A4", color="#C79A55", penwidth=1.6];

    // ============ LAYER 1 : pure foundation ============
    prelude   [label="kyo-prelude\nStream · Pipe · Abort\n(pure, no threads)", fillcolor="#C6D4E8", color="#5C7CA6", penwidth=1.6];
    scheduler [label="kyo-scheduler\n(threads)", fillcolor="#F7DFC0", color="#C79A55"];

    // ============ LAYER 0 ============
    kernel [label="kyo-kernel", fillcolor="#DCE4EE", color="#8FA3BC"];
    data   [label="kyo-data",   fillcolor="#DCE4EE", color="#8FA3BC"];

    // ---- rank bands ----
    { rank=same; sjson; syaml; sother; }
    { rank=same; schema; core; }
    { rank=same; prelude; scheduler; }

    // ---- dependencies ----
    system -> core   [color="#7A5BA6", penwidth=2.2];
    system -> schema [color="#7A5BA6", penwidth=2.2];

    sjson  -> schema;
    syaml  -> schema;
    sother -> schema;

    sjson -> prelude [color="#1F6FB2", penwidth=2.6,
                      label=<<font color="#1F6FB2"><b>  NEW  </b><br/>  streaming without<br/>  the runtime</font>>];

    schema -> data;
    core   -> prelude;
    core   -> scheduler;
    prelude -> kernel;
    kernel  -> data;

    // ---- capability edge, drawn separately so it reads as "provides", not "depends" ----
    system -> sjson [style=dashed, color="#8B6FB8", penwidth=1.8, constraint=false, arrowhead=vee];
    system -> syaml  [style=dashed, color="#8B6FB8", penwidth=1.4, constraint=false, arrowhead=vee];
    system -> sother [style=dashed, color="#8B6FB8", penwidth=1.4, constraint=false, arrowhead=vee];
}

kyo-system-layering.svg