Skip to main content

Module records

Module records 

Source
Expand description

The typed records of the cache database and the layout of their keys.

Every record belongs to a Family, and every key in the database starts with its family’s prefix, so a family, or a part of one, is a prefix scan. The rest of the key is the record’s RecordKey:

FamilyPrefixRest of the keyRecord
schema versionmeta/schema-versionSchemaVersion
cache identitymeta/identityCacheIdentity
step recordsstep/the 32 bytes of the StepKeyStepRecord
step positionsposition/the TaskId, then the positionStepPosition
task recordstask/the TaskIdTaskRecord
last writerswriter/the absolute path, as a PathKeyLastWriter
learned orderorder/the TaskIdLearnedOrder

A TaskId is the bytes of the absolute path of the task’s kizz.md, a zero byte, which no path contains, and the task’s index in the file as four big-endian bytes. Positions are four big-endian bytes too, so keys sort by path, then index, then position. Because keys start with absolute paths, every entry for the tasks and paths under a directory is the prefix scan of path_prefix.

Records are CBOR, encoded with minicbor by the rules of “Step keys”: definite lengths, fields in a fixed order (struct fields are arrays, in index order), and sets and maps sorted by key, so the same record always has the same bytes.

Step records hold the full step specification and the observations; their contents are in step. Later phases extend the other record contents, and a change of encoding raises SCHEMA_VERSION.

Structs§

LastWriter
The step or the task program that most recently wrote a path.
LearnedOrder
The tasks whose outputs a task consumed, in sorted order.
ModuleHash
The hash of one module a task program loads.
PathKey
The key of a last-writer entry: an absolute path.
PositionKey
The key of a step position: a task and the position of a step in its run.
SchemaKey
The key of the schema version, one of the two records of its family with the cache identity.
SchemaVersion
The version of the database’s schema, written when the database is created.
StepKey
The BLAKE3 hash that identifies a step, the key of its step record.
StepPosition
The step key a task used last time at one step position, with what that build decided about the step, so a changed key is explained by comparing the step specifications and kizz why prints the reasons the most recent build stored.
TaskId
The identity of a task: the absolute path of its kizz.md and its index among the task blocks of that file.
TaskRecord
What is recorded about a task: its program hash, the hashes of the program’s parts, how output names the task, and a summary of its last run.

Enums§

Family
The record families of the cache database.
WrittenBy
What in a task wrote a path: one of its steps, or its program.

Traits§

Record
A typed record stored in the cache database.
RecordKey
The part of a database key after the family prefix.

Functions§

database_key
The full database key of the record of type R at key.
path_prefix
The key prefix that selects every entry for the paths and tasks under dir, for the families keyed by absolute paths: step positions, task records, last writers, and learned order. The entry for dir itself is not under it.