The cache: what the targets of this node's references say, fetched by each reference's own script and kept here — one cache entry per reference, text in the node database, files in the cache directory. What the cache is for, and the rule that keeps a reference a pointer while its content lives here, is YmerNode.References § The membrane.

The node never fetches. Filling a cache entry is running the reference's fetch recipe — the URL action YmerNode.References.Sources derives for its uri at this moment — through YmerNode.Scripts.run/3, the door every run takes, and keeping what it answers. Read-only, never a working copy — how far an entry may lag its target is the membrane's — and every answer about one says how old it is.

flowchart TD
    Cache[YmerNode.References.Cache]

    subgraph owned
        Entry[CacheEntry schema]
        Window
        Reconcile
    end

    subgraph external
        Sources[References.Sources]
        Scripts[YmerNode.Scripts]
        Repo[(YmerNode.Repo)]
        Dir[(cache directory)]
    end

    Cache -->|"the recipe, at this moment"| Sources
    Cache -->|"run/3 on the URL action"| Scripts
    Cache --> Entry
    Cache -->|"a text entry's lines"| Window
    Cache --> Repo
    Cache -->|"file entries"| Dir
    Reconcile -->|"at boot: unnamed files go"| Dir

Filling a cache entry

The URL action is called with the reference's uri under url, its fragment under fragment where it has one, and — when the entry was filled by the same script — the reference_validator that script answered last time. A script that stores files (cache: :file in its declarations) is also handed cache_path, an absolute path in the cache directory to write the bytes to: a fresh name for every run, renamed into place when the answer is kept and deleted when it is not, so two refreshes of one reference never write one file.

What the action may answer, and what the node makes of it:

format is a media type and defaults to text/markdown; a script that stores text answers a text/* one, because text is all a text entry can be served as — anything else is converted first, or kept by a script that stores files. Text is kept up to text_limit/0 bytes. reference_validator is optional, the script's own string, and never read here. The text guard is the runner's and one of its own: an answer that is not valid UTF-8 never encodes and is refused by YmerNode.Scripts.Runner as :result_not_encodable; text carrying a NUL byte is refused here as :not_text. Every refusal — a script's error, a timeout, a guard — keeps the entry that was there.

A cache entry records the target it was fetched for — the reference's uri and fragment — and the reference is read again once the run is over: an answer for a target the reference no longer names, because it was moved or removed while the run was in flight, is refused as :reference_changed and never kept.

A cache entry records the script that filled it. When the recipe names another script today — a new claim on the host, a script removed, the web fallback taking over — the entry is a miss, refetched by the new script with no validator, because a validator means something only to the script that issued it; the file the replaced entry named, if any, goes with it. An entry fetched for another target than the reference names now is a miss too, and so is a file entry whose file is gone. A reference no script fetches any more has its entry dropped.

Serving a cache entry

format alone decides how an entry is served, never where it is kept:

• text/* by line window (YmerNode.References.Cache.Window); a file entry's text is guarded as it is read;
• image/png, image/jpeg, image/gif and image/webp, stored as a file and no larger than image_limit/0 once base64-encoded, as image content;
• anything else — only ever a file entry, since text is kept only as text/* — is described: its format, its size and its path relative to the cache directory, because a model cannot read it as it stands, and a script meant for one should convert it.

An image's size is taken from the file before it is read, so an image over the limit is never loaded to be refused.

The cache directory

dir/0. The node's, not the user's: a sibling of the files directory under the mount, never inside it, and rebuildable together with the node database: it follows the database. At boot YmerNode.References.Cache.Reconcile removes every file in it that carries the node's naming and that no entry names, so a fresh node database empties it and a run cut short leaves nothing behind, and it removes every entry whose file is gone. Between boots an entry whose file is gone is a miss, fetched again on the next read.