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:
| Family | Prefix | Rest of the key | Record |
|---|---|---|---|
| schema version | meta/ | schema-version | SchemaVersion |
| cache identity | meta/ | identity | CacheIdentity |
| step records | step/ | the 32 bytes of the StepKey | StepRecord |
| step positions | position/ | the TaskId, then the position | StepPosition |
| task records | task/ | the TaskId | TaskRecord |
| last writers | writer/ | the absolute path, as a PathKey | LastWriter |
| learned order | order/ | the TaskId | LearnedOrder |
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§
- Last
Writer - The step or the task program that most recently wrote a path.
- Learned
Order - The tasks whose outputs a task consumed, in sorted order.
- Module
Hash - The hash of one module a task program loads.
- PathKey
- The key of a last-writer entry: an absolute path.
- Position
Key - The key of a step position: a task and the position of a step in its run.
- Schema
Key - The key of the schema version, one of the two records of its family with the cache identity.
- Schema
Version - 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.
- Step
Position - 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 whyprints the reasons the most recent build stored. - TaskId
- The identity of a task: the absolute path of its
kizz.mdand its index among the task blocks of that file. - Task
Record - 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.
- Written
By - What in a task wrote a path: one of its steps, or its program.
Traits§
- Record
- A typed record stored in the cache database.
- Record
Key - The part of a database key after the family prefix.
Functions§
- database_
key - The full database key of the record of type
Ratkey. - 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 fordiritself is not under it.