vaelii.host.sync — com.vaelii/vaelii 0.26.0

Bring a KB's shipped contexts up to the running engine's.

A KB stores the starter ontology it was built with, and the engine that opens it later ships its own: a strength marked set/monotonic, a vocabulary term added to core.txt, a disjointness the ontology stopped stating. sync! makes the KB state what this engine ships, context by context, and leaves everything else alone.

What is shipped is what starter/load-into produces, read off a scratch in-memory KB it is loaded into — not the text of the files. The two differ: genlCx edges are stored in CxUniverse whichever file states them, and the closing unary_predicate batch is stated by no file. Each premise is attributed to the load that stored it: CxUniverse for the upper ontology, the middle context for a middle file.

Which contexts are synced exactly: CxUniverse and the kb/middle/ contexts. A premise there that the engine does not ship is retracted, a strength that differs is restated, and a missing one is asserted. CxUniverse is locked to the files with two exceptions, which sync neither retracts nor restates: a genlCx premise, stored in CxUniverse whichever file or author states it, and a sentex that is not a premise (a lifted decontextualized_predicate copy, a rule firing). An author's own context, wired below CxUniverse, is not one of them and is not read.

Only added to: any other context a shipped file's content is stored in.

Only the layers a KB has. A middle file whose context holds nothing in the KB is not loaded into it. The upper ontology is loaded only into a KB whose CxUniverse holds a premise the upper load ships, and the unary_predicate batch only into one that also holds a mark the batch ships.

Comparison is by the form a KB file writes (text/premise-entries): a fact or rule under its strength wrapper, an exceptWhen as the wrapper it was asserted as. A strength the engine raised is only an assertion, since assert raises a held premise's strength in place; one it lowered is the form retracted and the weaker one asserted, since nothing lowers a strength in place.

One batch. The sync is one v/edit!: the additions first, then the retractions, one settle. So the belief a retraction would sweep and the addition rebuild keeps its witness through the batch, where retracting first tore the TMS down only to build it back up. What cannot go in that order — a retraction of a record an addition lands on — goes before it (sync!).

Write-back is the other direction: write-back! edits the shipped files to state what a KB's exact contexts gained and lost since a held reading, one line per premise. The development browser runs it for the starter (docs/catalog.md).

context-files clj

(context-files context)

The shipped files context's premises are written in, as java.io.Files, the one a premise about no defined term is appended to first: core.txt and the other upper files for CxUniverse, kb/middle/<context>.txt for a middle context. Nil where the layer is not a directory on the classpath.

exact-contexts clj

(exact-contexts)

The contexts sync! makes state exactly what the engine ships: CxUniverse and the middle layer's contexts, as discovered on the classpath.

held clj

(held kb)

{[context form] entry} for every premise kb stores in the exact contexts, less the genlCx premises in CxUniverse: the reading two write-back! changes are diffed from.

plan clj

(plan kb)

(plan kb shipped)

What sync! would change in kb, without changing it:

:add {:context :form} the shipped content kb lacks, in the layers it has, in premises's order :remove {:context :form :handles} premises in an exact context the engine does not ship

A premise the engine ships at a higher strength is an :add alone: asserting it raises the held one. One it ships at a lower strength is a :remove and an :add.

shipped defaults to a fresh (premises).

premises clj

(premises)

Every premise the starter stores, as {:context c :form f :file ctx}: the form a KB file writes it in, the context it is stored in, and the context of the load that stored it — CxUniverse for the upper ontology, :unary-predicates for the closing batch no file states. In the order the load stored them, which is an order they assert in: the load retried what arrived before its dependencies. Built in a scratch in-memory KB that is cleared before this returns.

sync! clj

(sync! kb)

(sync! kb ships)

Make kb's shipped contexts state what this engine ships (see the namespace doc), as one v/edit!: the additions, then the retractions, one settle. Returns

{:added n :removed n :refused [{:context :form :type :message} …]}

A retraction goes first only when an addition lands on a record it retracts: a strength the engine lowered, whose weaker form would otherwise be asserted onto the premise and then retracted with it, or an exceptWhen restated around a rule the KB keeps. Those are their own edit! before the batch.

An addition the batch refuses is set aside, the batch rolled back and run without it, so the rest lands in one settle. The ones set aside are asserted after it, retrying while a round makes progress (add!): the batch's refusal can be an order the batch could not fix, or content its own retractions then took away. What still refuses is :refused. Each refusal costs the batch one rollback.

kb must accept writes (v/write-hazards empty). ships is (premises), passed by a caller that syncs more than one KB or prices the sync apart from the scratch load.

write-back! clj

(write-back! kb changes)

(write-back! kb {:keys [add remove]} files-of)

Edit the shipped files to state changes, {:add [entry …] :remove [entry …]} of {:context :form} as held spells them, one line edit each:

• a removal deletes the lines of the file form whose sentence matches, compared as kb stores it in the context, so variable names and antecedent order do not count;
• a removal and an addition of one sentence rewrite that form in place: a strength change;
• an addition is one line after the forms of the (comment T …) block of the first term it is about that a file defines (subject-terms), or appended to the context's first file when none is.

Every other line stays, comments and order included. files-of maps a context to its files and defaults to context-files. Returns {:written n :skipped [entry …]}, a skipped entry being a removal no file states or one in a context with no file.