Shared types#
This page is generated from the code and must not be edited by hand.
Types that more than one record uses: enumerations, which are lists of the values a field may take, and small records nested inside others.
AllenRelation#
Allen’s thirteen interval relations, recorded as a parameter on succeeds.
Files and sessions have extents, not only instants, and “overlaps” is different evidence from “before”. These are parameters on an existing primitive rather than primitives of their own: they qualify an ordering, they do not constitute a new kind of relationship.
DURING and CONTAINS_INTERVAL are Allen’s *during* and *contains*. The second is spelled out to keep it clearly distinct from the contains primitive, which is filesystem containment and unrelated.
Values: "before", "after", "meets", "met_by", "overlaps", "overlapped_by", "starts", "started_by", "during", "contains_interval", "finishes", "finished_by", "equals"
BindingAlternative#
One sense that stood equal to the winner, or was shadowed by it.
An ambiguity is not resolved by picking. Where two senses stand equal, nothing about the token distinguishes them and choosing would invent a fact. Where one shadowed the other, a rule attenuating the winner needs somewhere to fall back to, and a lookup that discarded the loser leaves it nowhere.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
|
yes |
|
|
whole number |
yes |
|
|
text |
no |
|
|
|
yes |
|
|
yes or no |
no |
|
|
text |
yes |
|
|
text |
yes |
BindingMethod#
How a resolver reached a sense.
Recorded rather than derived, because the two paths do not agree about precedence. A surface lookup ranks candidates by scope and then origin and returns the winner. The unit table resolves a term directly and returns whichever section was loaded last, so the origin on such a binding is not the origin of a precedence winner. A rule attenuating by origin has to be able to exclude those rows, and inferring which path ran from the component’s type would be exactly the habit this record exists to break.
Values: "surface", "unit_table"
CaseReadingStated#
How a run read the spellings a capital divides (1.22, a compatible addition): the settings dictionary.case_reading held when the names were read.
A partial rebind carries every name it does not read again with the reading its parent gave it, so a run reading the carried names’ spellings with another ratio would read one spelling two ways; the partial rebind compares this with its own and refuses.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
yes or no |
yes |
|
|
text |
no |
|
|
text |
yes |
|
|
number (more than 0.0) |
yes |
CaseSensitivity#
Whether a root’s filesystem distinguishes names differing only in case.
Recorded per root rather than assumed globally, because one project can span a case-sensitive volume and a case-insensitive one and the same name means different things on each.
Values: "sensitive", "insensitive", "unknown"
ClockKind#
Which clock a time-consuming rule reads.
Exposed as a rule parameter so a user can see and change which clock a conclusion rests on, rather than discovering it by reading code.
Values: "event", "recorded", "either"
ClockTier#
How much a time is worth, graded by whether it survives being copied.
The ordering principle is copy-robustness, not accuracy. Tiers one to three travel with the bytes; four and five describe this copy on this disk. A filesystem clock can be exact to the nanosecond and still be a fact about when somebody moved a folder, and an instrument’s acquisition time can be coarse and still be the answer to when the measurement happened.
Framed that way the ladder is principled rather than arbitrary, and it produces the scope boundary as a consequence rather than as a rule: prefer copy-robust clocks and the engine stops caring how files moved.
Every rung has a source. Tier one is filled by the ND2, LIF and LI-FLIM readers, from vendors’ own formats that the engine claims by name; tier two by the format extractors that read a document’s own metadata; and three, four and five have worked since the census.
Values: "instrument", "document", "name", "mtime", "filesystem", "unavailable"
ComponentActivation#
One optional component’s state during a run.
Every run states which optional components were configured, which were enabled, and which could actually run, so a measured result is attributable to a configuration.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
yes or no |
yes |
|
|
yes or no |
yes |
|
|
text |
yes |
|
|
text |
yes |
|
|
text |
no |
|
|
text |
yes |
DecisionStatus#
The standing of an assertion in the published graph.
Values: "asserted", "blocked", "superseded", "withdrawn"
DecisionTier#
The lexicographic classification of a candidate’s evidence.
Classification replaces summation. Three views of one underlying fact do not become three pieces of evidence by being added together, and a threshold on such a sum cannot be defended. The tier decides; a score orders candidates within a tier and nothing else.
Values: "direct", "anchored", "circumstantial", "blocked"
Defeater#
A recorded reason a claim would be retracted.
Defeasible and abductive claims must be able to name what would defeat them. A defeater is a visible event: evidence either raises a claim’s tier, leaves it unchanged, or introduces one of these. It never quietly erodes a score.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
yes or no |
no |
|
|
list of text |
no |
|
|
text |
yes |
|
|
text |
yes |
|
|
text |
yes |
|
|
text |
no |
|
DictionaryOrigin#
Where a Dictionary entry came from.
Values: "builtin", "pack", "user", "discovered"
DictionaryStatus#
Whether a Dictionary entry is in force.
Values: "active", "proposed", "rejected"
EntryKind#
Whether an entry is a filesystem object or a promoted derived stream.
Values: "filesystem", "derived"
EntryType#
What kind of filesystem object an entry is.
Values: "file", "directory", "symlink", "other"
ExcludedNames#
How many names of one kind a census left out of one root, and why.
Counted where each was left out, and never beneath it. An excluded folder is one excluded name of type directory: the walk does not descend into it, so what it holds is neither indexed nor counted, and the record says a folder was not walked rather than inventing a figure for its contents. Counting beneath one would walk exactly what a person excluded to avoid walking, which on a home directory’s hidden folders is most of the machine.
Nothing is indexed that was not, and the run says so. A census that skipped a name and kept no trace of it could not say that part of a drive, or a recycle bin, had never been seen, and a person asking why the engine does not see their files would get no answer from the run.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
whole number (at least 1) |
yes |
|
|
|
yes |
|
|
text or null |
no |
|
|
|
yes |
|
|
text |
yes |
|
|
text |
no |
|
ExclusionReason#
Why a census left a name out of the walk.
Values: "hidden", "exclude_glob", "max_depth"
ExpansionState#
Why the engine stopped expanding a container. Required on every embeds.
This field is what makes the absence of an embedding edge readable. Without it, “the archive holds nothing else” and “the engine did not look far enough” are the same silence, and a closed-world statement could rest on the second.
Values: "complete", "bounded", "refused", "failed"
ExtractionTier#
How far an observation sits from the bytes on the storage device.
Six graded tiers, lettered A to F for continuity with the source analysis, plus two states that are not points on the ladder at all. INACCESSIBLE and NOT_EXAMINED record that the ladder was never climbed, and treating them as a seventh and eighth rung would make “we could not read it” look like a weak reading.
Values: "literal", "mechanically_exposed", "decoded", "formally_extracted", "heuristic", "semantic", "inaccessible", "not_examined"
FailureClass#
What kind of thing failed, and therefore where the fix belongs.
Failure is a phenotype, and the partition routes the remedy. A rule failing four times in five whose failures are predominantly comprehension needs no modification at all: it is being starved of inputs, and loosening it would compensate for missing data by degrading a rule that was correct. That is the most common way rule tuning makes a system worse, and classifying prevents it without anybody having to notice.
Three classes, because there are three different people who can fix a thing: whoever administers the machine, whoever writes extractors, and whoever writes rules.
Values: "access", "comprehension", "interpretation"
FindingSubject#
What a raised finding is about.
Values: "entry", "group", "scope"
IdentityScope#
How much of an entry an identity method read.
Values: "whole", "sampled", "header"
InferenceTier#
The kind of reasoning that produced a claim.
Four kinds, and the differences between them are differences in what could make the claim wrong, which is why they are a vocabulary rather than a number.
Values: "entailed", "defeasible", "abductive", "testified"
InvariantOutcome#
The result of one publication invariant on one run.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
list of text |
no |
|
|
text |
yes |
|
|
yes or no |
no |
|
|
yes or no |
yes |
|
|
text |
no |
|
|
text |
yes |
|
|
whole number |
no |
|
LocatorStep#
One step into the interior of a file.
A locator step says how to get from a container to something inside it. A chain of them addresses a stream at any depth: the third sheet of a workbook inside a zip archive is two steps.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
whole number |
no |
|
|
text |
yes |
|
|
text |
yes |
MatchQuality#
How a token matched a Dictionary surface, which is evidence in itself.
Case matters in scientific notation and losing it is not a small error. nM is nanomolar and nm is nanometre; mM is millimolar and mm is a millimetre. A lookup that folds case reports a length where a concentration was written, wrong by nine orders of magnitude and silently so.
Lives here rather than beside the lookup that computes it, because a record field cannot reference a type owned by a subpackage that imports this one.
Values: "exact", "case_folded", "loose"
MentionTally#
How many mentions of one shape files of one extension made, in one run.
The tally is kept by the mentioning file’s extension and by shape, so a run report states how many mentions came from scripts and notebooks, and how many from the include and import lines inside a bundled program, without a query over the observations.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
text |
yes |
|
|
whole number (at least 0) |
yes |
|
|
whole number (at least 0) |
yes |
|
|
text |
no |
|
|
text |
yes |
MovedBy#
How a walk knew a file at a new path is a file an earlier census held elsewhere (1.22).
An observation about the filesystem between two censuses, derived from both and so reproducible from the Index; never a person’s decision and never a claim. Ordered from the strongest to the weakest evidence. A walk reads no content, so at walk time a match is usually by name, size and time; the next dive that reaches the file computes a digest, and an equal digest confirms the move.
Values: "whole_digest", "sampled_digest", "same_file", "birth_time", "name_size_time", "neighbours", "contents", "copied", "copied_same_bytes", "copied_contents", "digest_differs"
NameSlot#
One position in an entry’s name, and what stands there.
A slot addresses an occurrence; a component addresses a value. The distinction is load-bearing and was missing. A component is deduplicated to one row per distinct normalized value per entry, so it keeps the *first* spelling of several normalized-equivalent occurrences and nothing else. Two instances of 40min in one name therefore shared a component row and, with a start offset but no end, could not be told apart or read back off the name. Every layer above this one — grammar, role assignment, attachment — needs the occurrence rather than the value, so the gap is closed here rather than worked around there.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
text or null |
no |
|
|
text |
yes |
|
|
text |
yes |
|
|
whole number |
no |
|
|
whole number |
no |
|
|
whole number |
yes |
|
|
text or null |
no |
|
|
text |
no |
|
|
text |
no |
|
|
whole number |
no |
|
|
text or null |
no |
|
PackInForce#
One laboratory pack a run’s vocabulary loaded.
Reproducing a run means installing what it names: a pack’s senses are part of the Dictionary the run consulted, and dictionary_hash says the composed vocabulary differed without saying why. The name and version say which pack; the digest over its files says which copy.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
text |
yes |
|
|
text |
yes |
|
|
text |
no |
|
|
text |
yes |
ParameterSpec#
One typed, bounded, documented rule parameter.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
list of text |
no |
|
|
text |
yes |
|
|
text |
no |
|
|
number or null |
no |
|
|
number or null |
no |
|
|
text |
yes |
|
|
text |
no |
|
|
|
yes |
ParameterType#
The type of a rule parameter.
Typed and bounded so the interface renders a control without bespoke code: an enumeration becomes a dropdown, a bounded number a slider, a list a chip editor. This is how a parameter becomes a real control rather than a line in a configuration file.
Values: "boolean", "integer", "real", "string", "enum", "string_list", "mapping", "duration"
PlatformRecord#
The machine a run happened on.
Recorded because several fields in Entry are platform-dependent and several time semantics differ between operating systems. A result that cannot be attributed to a platform cannot be compared with one from another.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
|
no |
|
|
text |
yes |
|
|
text |
yes |
|
|
text |
yes |
|
|
text |
no |
|
|
text |
yes |
Primitive#
The eight relation primitives. The set is closed.
Values: "contains", "embeds", "derives", "identical", "equivalent", "succeeds", "references", "concerns"
QualityState#
Whether a quality figure holds a count, and if not, why not.
Three states kept apart, as absence is everywhere in the engine: a figure no pass has reached yet is not a figure the engine does not keep, and neither is a zero.
Values: "counted", "not_run", "not_recorded"
QuotientOrigin#
Whether an edge at a coarse level was lifted from below or asserted there.
Some relationships exist only at a coarse level and have no fine-grained counterpart: two sets of experiments relate within a month while their movie files relate within a day. A model that only lifts cannot express that, so rules may attach to a level and assert natively at it.
Values: "lifted", "native"
RecognisedAs#
What of the engine’s own a census found in a data pool: a directory, or, for the project a run writes, a file or folder of its own.
Nothing is opened to tell: a directory is recognized from the names it holds, and the project a run writes by its folder’s device and file number or its path.
Values: "installation", "project", "run", "this_project"
RecognisedPath#
One path a census recognized as the engine’s own, and what it did about it: a directory, or a file or folder of the project the run writes.
Listed in the run record whether or not it was indexed, so a pool holding an earlier run’s results says so, and entries missing from the Index have a stated reason rather than a silent one.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
yes or no |
no |
|
|
|
yes |
|
|
text |
yes |
|
|
text |
yes |
|
|
text |
no |
|
RecordEventKind#
The kinds of decision a person can make.
Values: "confirm", "reject", "merge", "split", "assign", "define", "override", "annotate", "note", "withdraw"
ReferenceResolution#
How well a reference string resolved. Recorded on every references.
These are not interchangeable, and keeping them apart is what lets the engine say “this script claims to write that file, and that file does not exist”, which is a finding rather than an error.
Values: "exact", "unique_suffix", "unique_basename", "ambiguous", "unresolved"
ResolutionStatus#
Whether a question about an entity has been settled, and if not, why not.
Three of these four are absence states and they mean different things. A coverage figure computed over their union is not a coverage figure; it is the conflation this vocabulary exists to prevent.
Values: "unexamined", "examined_no_evidence", "examined_conflicting", "resolved"
ResolutionTally#
What one inference’s resolution made of the mentions of one shape, by extension.
The exit measurement of reference resolution, in the run record: resolved, abstained, or outside the pool, by the mentioning file’s extension and the mention’s shape, so a report has the figure without a query and two runs’ figures compare.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
text |
yes |
|
|
whole number (at least 0) |
yes |
|
|
whole number (at least 0) |
yes |
|
|
text |
yes |
|
|
text |
no |
|
|
text |
yes |
ReuseDecision#
Why a re-scan did or did not reuse a previous record.
Counted into every run record so that “why was reuse lower than expected” is a query rather than an investigation. The order is the order the decision is made in.
Values: "no_previous_record", "stat_changed", "processing_changed", "previous_incomplete", "reuse"
RuleComposition#
Boolean composition over predicates.
Boolean composition is sufficient for a first version and a general expression language would be the wrong place to spend the schedule. This already expresses “treat two folders as replicates when the conditions match and the dates differ and neither is named like a rerun”, which covers the realistic cases. The grammar is left open for an expression syntax later without anything depending on one now.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
list of text |
no |
|
|
list of text |
no |
|
|
list of text |
no |
|
|
text |
no |
|
RuleEffect#
What a rule does. This is the type system of the Rulebook.
A rule’s effect says where in the pipeline it runs, which means rule ordering is *derived* rather than configured. That is what prevents the Rulebook from becoming an unordered pile whose behavior depends on file order.
Values: "constraint", "proposes", "classifies", "groups", "flags", "enumerates"
RuleStatus#
Whether a person has confirmed a rule, on DictionaryStatus’s precedent.
Kept out of the digest, as the rationale is: confirming a rule changes nothing it concludes, so it must not make two runs of one Rulebook look different.
Values: "active", "provisional"
Salience#
How much of a person’s limited attention something deserves.
Independent of confidence, and the two must not be collapsed. A byte-identical duplicate among ten thousand thumbnails is maximally confident and nearly worthless; a tentative link between an instrument export and a manuscript figure is low-confidence and extremely valuable.
Four terms, kept separate so a ranking can be explained rather than only produced.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
number (at least 0.0) |
no |
|
|
number (at least 0.0) |
no |
|
|
number (at least 0.0) |
no |
|
|
text |
no |
|
|
number (at least 0.0) |
no |
|
ScanOutcome#
What the last run actually did with an entry.
Read by the reuse decision, which must know not only whether the file changed but whether the previous record *delivers what today’s policy asks for*. A metadata-only record cannot satisfy a run with extraction enabled, and an error or a deferral is never reusable: failure is never cached, so a scan interrupted by a stalled filesystem retries exactly the files that failed rather than serving their failures forever.
Values: "metadata_only", "skipped_by_policy", "extracted", "extracted_with_fallback", "deferred", "content_error", "changed_during_read", "skipped_by_settings"
Scope#
Where a rule, assertion or decision applies.
Scope is first-class because the most common real correction is not “this rule is wrong” but “this rule is wrong *here*”. Without scoping, a user disables a good rule globally in order to fix one folder.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
|
yes |
|
|
text or null |
no |
|
ScopeKind#
The kind of region a rule, an assertion or a decision applies to.
Values: "project", "root", "folder", "selection", "level", "file_type"
SourceScope#
Where in an entry a component or observation came from.
Values: "name", "path", "header", "content", "user", "declared"
SupportComponent#
One named piece of positive support for a candidate or a claim.
Components are kept as a vector and never summed into a scalar before the decision is made. Summation is what triple-counts one underlying fact seen three ways, and it is why family exists: components sharing a family are views of one fact and must not compound with each other.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
text |
yes |
|
|
text |
yes |
|
|
list of text |
no |
|
|
text |
no |
|
|
number (at least 0.0) |
yes |
SymlinkState#
Whether a symlink’s target is there, which is not the same as whether the link is.
Resolved, never traversed. Stating a target exists costs one stat; walking into it turns the containment forest into a graph and can turn a scan into an infinite one, which is why ScanSettings.follow_symlinks is frozen shut.
The engine keeps these states apart for a link as it does everywhere. A link whose target is gone and a link the engine could not ask about are different states, and both differ from a link that resolves. A stub standing in for a file that exists elsewhere is somebody’s data; a stub standing for nothing is not, and only the first is worth a person’s attention.
Values: "not_a_link", "resolves", "broken", "unreadable", "outside_root"
TimeSource#
Where a recorded time came from. Every clock carries one.
Kept explicitly because a time whose provenance is unrecorded cannot be reasoned about, and the filesystem’s own clocks are the least trustworthy it offers: creation time does not exist on every filesystem, st_ctime means metadata change on POSIX and creation on Windows, and copying a file usually resets both.
The content sources are split rather than gathered under one embedded, because an instrument’s acquisition time and a word processor’s “created” field are not the same kind of fact and ClockTier grades them differently. One value covering both would make the tier unrecoverable from the source, which is the whole thing the pair exists to prevent.
Values: "birthtime", "ctime", "mtime", "mtime_fallback", "instrument", "document", "filename", "unavailable"
ValueKind#
The type of an observation’s value.
An observation’s value is stored in a typed column chosen by this discriminator rather than stringified into one. Columnar storage rewards that, and it keeps a numeric comparison from silently becoming a string comparison.
Values: "text", "integer", "real", "boolean", "structure", "negative"
WarningTally#
Every warning of one kind a run raised, counted, with a bounded sample (1.22).
A library can warn once per file, and a run over a large pool then held every message in memory before summarizing them. A tally keeps the count exactly and the words boundedly: the first message, the last, and at most a few between, so the record of a pathological run is the size of a healthy one’s.
Field |
Type |
Required |
If left out |
|---|---|---|---|
|
whole number (at least 1) |
yes |
|
|
text |
yes |
|
|
text |
yes |
|
|
list of text |
no |
|
|
text |
no |
|
|
text |
yes |
|
|
text |
yes |