A belief image: the whole belief state of a KB, written as three files and installed
into an empty KB in place of a recover. Two places hold one: a :disk-snapshot KB's own
directory, under <dir>/belief/, and an export dump, under <dump>/belief/.
network.bin — the dense network (dense/write-image): every node, justification
column, label, defeat-class, defeat, block and supersession;state.nippy — the taxonomy's relations and caches, less the slots the live KB
owns (taxonomy-side-slots), and the KB atoms recovery fills or the closing settle
leaves (state-atoms);manifest.edn — the stamp, written last, so a directory with no manifest holds no
image.The two layout numbers, a records fingerprint, the source identity's digest, and the two
policies that move belief (checks/arbitrating? and config/assertive-arg-types?). The
records fingerprint differs by place, because each place is checked against something
different. A disk image carries the record store's belief-fingerprint, read off the
slots without decoding a record. A dump's image carries content fingerprints of the
sentexes and the justifications the dump streams (fingerprint/accumulator), which an
import recomputes while it lands them.
install-from! installs an image when every one of these holds, and otherwise leaves the
KB untouched for the full recover:
refusal): a registered prover or
evaluatable runs code the source identity does not cover;decision).Both sections are read in full before anything moves into the KB, so a torn or
truncated section costs the recover and never leaves a half-installed network.
install! is the disk image's case: a :disk-snapshot KB (applies?) against its own
directory.
save! writes a :disk-snapshot KB's image after a full recover, and register-close!
arranges a refresh when the directory closes if the records moved since the image was
written. The records stamp is read before and after the sections are written, and an
image whose records moved during the write is abandoned. A close-time write is also
skipped when the source identity at close differs from the one belief was derived under
at open: a REPL can reload engine code mid-session, and an image carries the digest of
the source that derived its belief, never the digest of source loaded afterwards.
vaelii.impl.io.export writes a dump's image through write-sections!. Neither place
takes an image of a KB whose network does not cover its records (writable?).
The records stay the only source of truth. An image is installed whole, against the exact records, source and policies it was written under, or discarded whole; nothing reconciles an image against records that moved. So a KB that installs an image is the KB that wrote it, field for field. An image written after a recover is that recover. An image written by a KB built assert by assert carries that KB's labels, which equal a recover's because belief is order independent, and that KB's derivation depths and settle readings, which a recover rebuilds from the records instead of reading (docs/defenses.md, "A belief image is installed whole or not at all").
A **belief image**: the whole belief state of a KB, written as three files and installed into an empty KB in place of a recover. Two places hold one: a `:disk-snapshot` KB's own directory, under `<dir>/belief/`, and an export dump, under `<dump>/belief/`. ## What is in it - `network.bin` — the dense network (`dense/write-image`): every node, justification column, label, defeat-class, defeat, block and supersession; - `state.nippy` — the taxonomy's relations and caches, less the slots the live KB owns (`taxonomy-side-slots`), and the KB atoms recovery fills or the closing settle leaves (`state-atoms`); - `manifest.edn` — the stamp, written last, so a directory with no manifest holds no image. ## The stamp The two layout numbers, a records fingerprint, the source identity's digest, and the two policies that move belief (`checks/arbitrating?` and `config/assertive-arg-types?`). The records fingerprint differs by place, because each place is checked against something different. A disk image carries the record store's `belief-fingerprint`, read off the slots without decoding a record. A dump's image carries content fingerprints of the sentexes and the justifications the dump streams (`fingerprint/accumulator`), which an import recomputes while it lands them. ## When one is installed `install-from!` installs an image when every one of these holds, and otherwise leaves the KB untouched for the full recover: - the KB is on the dense network, and its network holds no node; - its provers and its solver are the defaults (`refusal`): a registered prover or evaluatable runs code the source identity does not cover; - the manifest's stamp equals the KB's (`decision`). Both sections are read in full before anything moves into the KB, so a torn or truncated section costs the recover and never leaves a half-installed network. `install!` is the disk image's case: a `:disk-snapshot` KB (`applies?`) against its own directory. ## When one is written `save!` writes a `:disk-snapshot` KB's image after a full recover, and `register-close!` arranges a refresh when the directory closes if the records moved since the image was written. The records stamp is read before and after the sections are written, and an image whose records moved during the write is abandoned. A close-time write is also skipped when the source identity at close differs from the one belief was derived under at open: a REPL can reload engine code mid-session, and an image carries the digest of the source that derived its belief, never the digest of source loaded afterwards. `vaelii.impl.io.export` writes a dump's image through `write-sections!`. Neither place takes an image of a KB whose network does not cover its records (`writable?`). ## What an installed image equals The records stay the only source of truth. An image is installed whole, against the exact records, source and policies it was written under, or discarded whole; nothing reconciles an image against records that moved. So a KB that installs an image is the KB that wrote it, field for field. An image written after a recover is that recover. An image written by a KB built assert by assert carries that KB's labels, which equal a recover's because belief is order independent, and that KB's derivation depths and settle readings, which a recover rebuilds from the records instead of reading ([docs/defenses.md](docs/defenses.md), "A belief image is installed whole or not at all").
(applies? kb)Does kb keep a belief image in its own directory — a :disk-snapshot KB (the one
carrying a :snapshot-dir) over the durable record store, on the dense network?
Does `kb` keep a belief image in its own directory — a `:disk-snapshot` KB (the one carrying a `:snapshot-dir`) over the durable record store, on the dense network?
(decision manifest now)Why the image manifest describes cannot be installed into a KB whose stamp is now,
or nil when it can. One reason per mismatch class: :absent, :format-changed,
:records-differ, :source-differs, :policy-differs.
Why the image `manifest` describes cannot be installed into a KB whose stamp is `now`, or nil when it can. One reason per mismatch class: `:absent`, `:format-changed`, `:records-differ`, `:source-differs`, `:policy-differs`.
The image's own layout number, beside dense/image-version (the network section's).
An image of any other number is discarded.
The image's own layout number, beside `dense/image-version` (the network section's). An image of any other number is discarded.
(install! kb)Install a :disk-snapshot KB's own image in place of a recover — install-from! over
its directory, against the record store's belief-fingerprint.
Install a `:disk-snapshot` KB's own image in place of a recover — `install-from!` over its directory, against the record store's `belief-fingerprint`.
(install-from! kb dir records-fn)Install the image in dir into kb in place of a recover. records-fn returns the
KB's records fingerprint in the form the image's manifest carries; it runs only once the
cheaper conditions hold. Returns {:belief :installed :source d}, or {:belief :recover :reason r} with the KB untouched — r one of decision's reasons, a refusal,
:not-applicable, :network-populated or :unreadable. :source is the source
identity's digest, which register-close! takes.
Install the image in `dir` into `kb` in place of a recover. `records-fn` returns the
KB's records fingerprint in the form the image's manifest carries; it runs only once the
cheaper conditions hold. Returns `{:belief :installed :source d}`, or `{:belief :recover
:reason r}` with the KB untouched — `r` one of `decision`'s reasons, a `refusal`,
`:not-applicable`, `:network-populated` or `:unreadable`. `:source` is the source
identity's digest, which `register-close!` takes.(read-manifest dir)The committed manifest of the image in dir, or nil when there is none or it does not
read.
The committed manifest of the image in `dir`, or nil when there is none or it does not read.
(refusal kb)Why kb may neither write nor install an image, or nil. A prover or evaluatable
beyond the defaults, or a solver other than the local one, runs code the source identity
does not cover.
Why `kb` may neither write nor install an image, or nil. A prover or evaluatable beyond the defaults, or a solver other than the local one, runs code the source identity does not cover.
(register-close! kb source)Arrange for kb's image to be refreshed when its directory closes. source is the
source identity's digest belief was derived under, and the digest now when the caller
has none. A no-op for a KB that does not keep an image, or that refusal names a
reason for.
Arrange for `kb`'s image to be refreshed when its directory closes. `source` is the source identity's digest belief was derived under, and the digest now when the caller has none. A no-op for a KB that does not keep an image, or that `refusal` names a reason for.
(save! kb)Write a :disk-snapshot KB's image into its own directory, and return the manifest —
or nil when nothing was written: the KB does not keep one (applies?, writable?), or
its records moved while the sections were written. A failure is logged and returns nil:
the image is a cache of a recover, and the next open recovers without it.
Write a `:disk-snapshot` KB's image into its own directory, and return the manifest — or nil when nothing was written: the KB does not keep one (`applies?`, `writable?`), or its records moved while the sections were written. A failure is logged and returns nil: the image is a cache of a recover, and the next open recovers without it.
(stamp kb records)What an image of kb whose records fingerprint is records is valid against.
:libraries is carried for a reader of the manifest; the source digest already covers
it.
What an image of `kb` whose records fingerprint is `records` is valid against. `:libraries` is carried for a reader of the manifest; the source digest already covers it.
The KB atoms an image carries: each one recovery fills, or the closing settle leaves
holding something the next settle reads. belief_image_test fails on a KB atom that is
in neither this list nor unimaged-atoms.
The KB atoms an image carries: each one recovery fills, or the closing settle leaves holding something the next settle reads. `belief_image_test` fails on a KB atom that is in neither this list nor `unimaged-atoms`.
The taxonomy keys an image leaves as the open made them: the two callbacks
kb/open-kb installs, which close over the KB, and the three side caches, which are
atoms stamped by a relation's own :gen.
The taxonomy keys an image leaves as the open made them: the two callbacks `kb/open-kb` installs, which close over the KB, and the three side caches, which are atoms stamped by a relation's own `:gen`.
The KB atoms an image leaves as the open made them. :taxonomy has its own section.
:provers and :solver are configuration the caller sets, held to the defaults by
refusal. :settle-stats and :chain-stats count work this process did. :qcn,
:qcn-joined, :matches and :closures are bounded caches a missing read refills.
:unrecovered is the write-hazard record recovery clears after an install. :feed
holds the change feed's subscriptions, which a caller in this process registered.
:violations is the log of what writes newly exposed; a restore exposes nothing
(settle/*rebuilding?*), so an installed KB starts it empty, as a recovered one does.
The KB atoms an image leaves as the open made them. `:taxonomy` has its own section. `:provers` and `:solver` are configuration the caller sets, held to the defaults by `refusal`. `:settle-stats` and `:chain-stats` count work this process did. `:qcn`, `:qcn-joined`, `:matches` and `:closures` are bounded caches a missing read refills. `:unrecovered` is the write-hazard record recovery clears after an install. `:feed` holds the change feed's subscriptions, which a caller in this process registered. `:violations` is the log of what writes newly exposed; a restore exposes nothing (`settle/*rebuilding?*`), so an installed KB starts it empty, as a recovered one does.
(writable? kb)May kb's belief be written as an image: the dense network, no refusal, and a
network that covers the records?
May `kb`'s belief be written as an image: the dense network, no `refusal`, and a network that covers the records?
(write-sections! kb dir stamp)(write-sections! kb dir stamp commit?)Write kb's network and state into dir, then a manifest carrying stamp, and return
the manifest — or nil when commit?, asked after both sections are written, answers
false. The manifest is deleted first and written last, so from the first byte until the
commit dir holds no image rather than an old manifest over new sections. The caller
holds the KB still; nothing here stops a writer.
Write `kb`'s network and state into `dir`, then a manifest carrying `stamp`, and return the manifest — or nil when `commit?`, asked after both sections are written, answers false. The manifest is deleted first and written last, so from the first byte until the commit `dir` holds no image rather than an old manifest over new sections. The caller holds the KB still; nothing here stops a writer.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |