The Guidedoc engine
===================

Guidedoc is the conversion core. It borrows storage from its caller.
It reads a source, builds a semantic tree, runs passes, measures the output,
and emits bytes. It does not open files or publish artifacts.

.. graphviz::
   :caption: Effects belong to the host; document semantics belong to Guidedoc.
   :alt: The CLI calls the project host, which supplies fixed storage to the conversion core.

   digraph layers {
     graph [rankdir=TB, bgcolor="transparent", pad="0.3"];
     node [shape=box, style="rounded,filled", fillcolor="#edf5f2",
           color="#216553", fontname="Helvetica", fontcolor="#16382f"];
     edge [color="#216553"];
     cli [label="CLI\narguments · terminal presentation"];
     project [label="Project host\nfiles · graph · budget · publication"];
     core [label="Guidedoc\nreaders · semantic tree · passes · renderers"];
     native [label="Native dependencies\nGraphviz · Typst · source parsers"];
     cli -> project; project -> core; project -> native;
   }

The boundary
------------

Core conversion performs no allocation.
The caller supplies node columns, text storage, diagnostics, and output capacity.
A host may allocate while preparing those buffers.
A third-party compiler has its own allocation rules.
The guarantee names the conversion boundary, not the whole process.

The tree
--------

Nodes have typed IDs. Hot columns hold the kind and subtree range.
Cold tables hold payloads needed by particular node kinds.
A flat preorder representation lets a traversal skip a whole subtree
without following a chain of heap pointers.

For node :math:`i`, let :math:`e_i` be its exclusive subtree end.
The subtree occupies :math:`[i,e_i)`.
A leaf has :math:`e_i=i+1`. A parent closes after its descendants.
See :doc:`algorithms` for the interval proof.

The API
-------

The core API is explicit: initialize storage, convert, inspect the result, reset.
Registries are values containing reader, pass, and renderer descriptors.
There is no runtime plugin discovery or global registration side effect.
The small set of verbs is meant to remain easy to use from another Odin program.

Ownership is the key rule. Views into a workspace expire on reset or reuse.
A result held by the host must own any text that outlives the session.
Use :doc:`../api/core` for exact signatures. It is generated from the same Odin
source as the separate ``docs/api`` project. The manual's PDF includes that reference
in the same book, with internal links. The design record is GDS 0003 in ``docs/gds``.