decodeStateRecordfunctionfunction decodeStateRecord(text: string): Result<StateRecord, string>The record from its text, or why it cannot be read: a hand-edited or damaged record is told, never guessed.
The state record (commons 0003-host FR-009 to FR-011): <home>/.ergonex/state.auto.json, which holds the path, the SHA-256 and the generator of each generated file as it was written, the hash of the last plan, the version of Ergonex and the day each tool or module outside the catalog was first seen. ergonex verify compares the disk with it and it with what the templates give now; render and apply never overwrite a file whose bytes differ from it.
Pure: it decodes and encodes text and judges what verify compares; reading and writing the file is the host layer's. The text is deterministic (keys in order, two spaces, LF, one final newline), so that the record's own hash, which the evidence of a run names, is the same for the same record. The record is data, never trusted: a hash that is not 64 hexadecimal digits is refused.
decodeStateRecordfunctionfunction decodeStateRecord(text: string): Result<StateRecord, string>The record from its text, or why it cannot be read: a hand-edited or damaged record is told, never guessed.
EMPTY_RECORDconstconst EMPTY_RECORD: StateRecordA record with nothing in it, as before the first apply.
encodeStateRecordfunctionfunction encodeStateRecord(r: StateRecord): stringThe record as text: deterministic, with the header of a generated file as _generated.
FileFactstypetype FileFacts = {
readonly path: string;
/** The SHA-256 of the bytes on disk; absent where there is no file. */
readonly onDisk?: Sha256 | undefined;
/** The SHA-256 the record holds; absent where it holds none. */
readonly recorded?: Sha256 | undefined;
/** The SHA-256 of what the templates give now; absent where they give no such file. */
readonly wanted?: Sha256 | undefined;
};What verify found of one path.
ERGONEX_VERSIONconstconst ERGONEX_VERSION: "0.5.7"The version of Ergonex the record names.
RecordedFiletypeno test imports ittype RecordedFile = {
readonly sha256: Sha256;
readonly generator: string;
};One generated file as it was written.
STATE_RECORD_PATHconstno test imports itconst STATE_RECORD_PATH: ".ergonex/state.auto.json"Where the state record is, below the root.
StateRecordtypeno test imports ittype StateRecord = {
readonly ergonex: string;
/** The SHA-256 of the last plan, as `planDigest` gives it; absent be… (452 characters)type StateRecord = {
readonly ergonex: string;
/** The SHA-256 of the last plan, as `planDigest` gives it; absent before the first apply. */
readonly plan?: Sha256;
/** The generated files as written, by path. */
readonly files: Readonly<Record<string, RecordedFile>>;
/** The day each tool or module outside the catalog was first seen, by name (never restarted by a later run). */
readonly firstSeen: Readonly<Record<string, string>>;
};The state record (ergonex:StateRecord).
verifyFindingsfunctionfunction verifyFindings(facts: readonly FileFacts[], today: string): readonly Finding[]What ergonex verify reports (0003-host FR-010): a generated file whose bytes differ from the record is an error (a hand edit); a recorded file that is missing, an .auto. file the record does not hold and a file the templates would now write differently (a drift) are each a warning. Nothing is changed. today is the day the findings are first seen.
withFilefunctionfunction withFile(r: StateRecord, file: GeneratedFile, digest: Sha256): StateRecordThe record after a file was written: its path, hash and generator.
withoutFilefunctionfunction withoutFile(r: StateRecord, path: string): StateRecordThe record after a generated file was removed.