world_vcs.derive

The derive-hook registry. A hook is a computation that produces an output from the content a stage holds, so the output lands in the commit with the content it was computed from.

• register(hook) / unregister(name) / hooks() manage the registered hooks, listed in name order; allHooks() lists them together with the hook each asset type exports.
• planFor(refs) returns one { hook, ref } per staged world asset an asset-scope hook's matches accepts.
• cache.get / cache.put keep up to 64 results and 32 MiB by hook and fingerprint, least recently used out first.

local derive = require("modules.world_vcs.derive")
derive.register({
    name = "thumbs", scope = "asset", output = "thumb.png",
    matches = function(ref) return ref.type == "texture" end,
    module = "@root::thumbs", fingerprint = "fingerprint", compute = "compute",
})

world.derive(name, spec) registers the same hook; spec = nil removes it.

An asset type registers a hook by exporting derive from its behavior.luau: a hook without name, named <type>.<output>, matching refs of that type unless it states its own matches. planFor consults the behavior of each type among the staged refs, hookNamed(name) answers a registered hook or a type's export, and allHooks() reads every type's export beside the registered hooks, each from the behavior.luau its type holds at the call, so a type's output is left out of an asset's inputs (snapshot.outputsExcluded) and zm derived retry of its committed output finds its hook the way it does a registered one's.

derive.runner reserves the planned outputs and computes them on workers; derive.worker holds the entries a worker runs (fingerprint, compute), each calling the entry of the hook's module that the hook names.

A reservation whose stage leaves the output's inputs as the tree the commit lands on holds them settles done on the output that tree already holds, with nothing computed, when the working tree holds the same bytes at the output's path. The inputs are compared by snapshot.inputLines: the asset's files and the version of every asset they reference, where an asset the engine reads from a library it carries (/zero/source/libs/) is named by its guid alone, so a stage that only moves a library pin to another commit recomputes nothing.