nordisk/dwarves

.nornir/assets/auto-materialize.svg

<svg xmlns="http://www.w3.org/2000/svg" width="820" height="340" font-family="monospace" font-size="13">
  <style>
    .box{fill:#0f2233;stroke:#6fd3f5;stroke-width:1.5}
    .reuse{fill:#12331f;stroke:#7fe0a0;stroke-width:1.5}
    .t{fill:#dbeafe}.dim{fill:#9fb6c6}.acc{fill:#7fe0a0}
    .arr{stroke:#6fd3f5;stroke-width:1.5;fill:none;marker-end:url(#a)}
    .arr2{stroke:#7fe0a0;stroke-width:1.5;fill:none;marker-end:url(#b)}
  </style>
  <defs>
    <marker id="a" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 Z" fill="#6fd3f5"/></marker>
    <marker id="b" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 Z" fill="#7fe0a0"/></marker>
  </defs>

  <text x="12" y="20" class="acc">cache-hit auto-materialize — restore the reused step's BYTES to disk (the inverse of the push)</text>

  <!-- reused step -->
  <rect class="reuse" x="12" y="46" width="200" height="72"/>
  <text x="24" y="68" class="acc">a step is REUSED</text>
  <text x="24" y="86" class="dim">CacheHit / Unchanged</text>
  <text x="24" y="104" class="dim">skipped — no bytes made</text>

  <!-- action cache -->
  <rect class="box" x="262" y="46" width="200" height="72"/>
  <text x="274" y="68" class="t">action cache (INDEX)</text>
  <text x="274" y="86" class="dim">input_id -&gt; artifact_id</text>
  <text x="274" y="104" class="dim">the id is fed forward</text>

  <!-- holger -->
  <rect class="box" x="512" y="34" width="292" height="96"/>
  <text x="524" y="56" class="acc">holger (artifact registry)</text>
  <text x="524" y="76" class="dim">store.get(artifact_id)</text>
  <text x="524" y="92" class="dim">single id -&gt; bytes</text>
  <text x="524" y="108" class="dim">manifest id -&gt; every member</text>

  <line class="arr2" x1="212" y1="82" x2="260" y2="82"/>
  <line class="arr" x1="462" y1="82" x2="510" y2="82"/>

  <!-- materialize -->
  <rect class="reuse" x="262" y="160" width="200" height="76"/>
  <text x="274" y="182" class="acc">materialize(dir)</text>
  <text x="274" y="200" class="dim">write bytes to disk:</text>
  <text x="274" y="216" class="dim">member -&gt; dir/name</text>
  <text x="274" y="230" class="dim">single -&gt; dir/step</text>

  <!-- downstream real step -->
  <rect class="box" x="512" y="160" width="292" height="76"/>
  <text x="524" y="182" class="t">downstream REAL step</text>
  <text x="524" y="200" class="dim">finds the upstream output ON DISK</text>
  <text x="524" y="216" class="dim">even on a fresh workspace /</text>
  <text x="524" y="230" class="dim">a second machine</text>

  <line class="arr2" x1="658" y1="130" x2="658" y2="158"/>
  <line class="arr2" x1="462" y1="198" x2="510" y2="198"/>
  <line class="arr2" x1="362" y1="118" x2="362" y2="158"/>
  <text x="368" y="142" class="dim">DWARVES_MATERIALIZE_DIR</text>

  <text x="12" y="278" class="dim">No materialize dir  ⇒  id-only reuse (no disk write, pre-materialize behaviour).</text>
  <text x="12" y="298" class="dim">No artifact store  ⇒  a no-op (the bytes live in the store; nothing to restore).</text>
  <text x="12" y="318" class="dim">A restore that fails NEVER breaks the build (best-effort; the downstream step just rebuilds).</text>
</svg>