DKE Library — Specification

1.1 Conformance language

MUST / MUST NOT state a requirement; violating one is an error, though not always one a machine catches — §5.4 says exactly which are checked. SHOULD states a strong recommendation with a stated cost for departing. MAY states a permission. A conformant producer is any program that writes facts a published module reasons over, whether or not it uses dkepy.

2.1 Naming

• A kind name is scoped to its module: code.Function and finance.Function are different kinds and never read each other’s data.
• Kind names are CapitalizedWords. Field names are lower_snake_case.
• A producer MUST write the kind name exactly as the module declares it. Case and spelling are the whole of the matching; nothing corrects a near miss. §5.4 names the one check that catches this and the ones that do not.
• A subject identifies one thing of that kind. Subjects are the producer’s to choose, MUST be stable across loads for the same thing, and MUST be used consistently: §3.3 gives the case where a display name in a subject position silently corrupts every answer.

2.2 Value classes

A field declares one of the writable value classes of the DKE Python language — string, int, bool, and the others given in the Language Specification §5. This document adds no value classes and no coercions. A producer SHOULD write the declared class; a mismatch is not caught by any library-level check (§5.4).

2.3 Three ways a field gets its value

This distinction is load-bearing throughout §3, and getting it wrong is the most common way a store produces confident wrong answers.

A producer MUST NOT write a derived field or a rule conclusion. They are maintained for you and carry a derived provenance rather than a source, so a conclusion is always distinguishable from something you were told.

2.4 Absence is a value

Several rules in §3 read the absence of a field, not its contents. This is the sharpest edge in the library, so it is stated as a requirement rather than as advice:

A producer MUST write an absence-read field only where the thing it records is actually true, and MUST NOT write a placeholder, an empty string, or a default into one.

Writing such a field everywhere does not make a rule fire everywhere — it silences the rule everywhere, and the store then answers every question with the same list while nothing reports a fault. §3.3 names which fields these are. checkup distinguishes “nothing reaches these” from “nothing was looked for”; §4.4 says how.

3.1 What a module may declare

Four declaration forms, all of which become part of your store the moment you import the module:

A module MUST NOT contain anything else that persists. Module semantics in general — how import resolves, how namespacing works, what re-submitting does — are the language’s, in the DKE Python Reference §9.

A standing rule ranges over one kind. This is a property of the language, not a style choice, and it explains several fields in §3.3 that look redundant: a question about another kind cannot be a premise, so the observation is recorded on the side that needs it.

3.2 The published modules

One module is published: code, which reasons about a codebase. Its source is served at /source/code/ under its version, with a latest alias. §3.3 through §3.6 specify it.

code reasons about whatever codebase you load. It describes no particular one, and it ships no facts.

3.3 code — declared fields

A producer writes these. Fields marked absence-read are governed by §2.4.

Function

Class — name: string, module: string, methods: int, language: string (optional, as on Function).

Call — caller: string, callee: string, site: string.

caller and callee MUST hold the subject of a Function, never its display name. The queries compare; they cannot tell a name from a subject. A display name here makes every function look uncalled, and nothing reports an error.

UnresolvedCall — caller: string (a Function subject), site: string, text: string (the callee as written).

A call whose target could not be named. No edge is asserted here, and a producer MUST NOT assert one. A missing edge is a known gap; a guessed edge is a wrong answer the queries cannot tell from a fact. Absent-tolerant: record none and everything else works, with dispatch_sites() returning nothing.

Rationale — subject: string (the Function or Class it explains), marker: string, text: string, site: string.

Stated, never inferred. Which comments count is the producer’s decision. Whatever convention is chosen, it SHOULD be one an author had to type on purpose: a convention wide enough to sweep ordinary comments turns every line into a fact and the query into noise.

Import — importer: string, imported: string, root: string.

Dependency — name: string, version: string, direct: bool, pinned: bool.

Counterpart — name: string, left: string, right: string, relation: string, left_covers: int, right_covers: int.

Two functions that have to agree. Stated, never inferred — agreement is a claim about intent and no call graph can see it. relation names what is being counted, because it differs per pair; left_covers and right_covers count members of that set and are comparable to each other and to nothing else. This is the one kind no producer LangSyn publishes writes (§5.2).

3.4 code — derived fields

Maintained by the engine. A producer MUST NOT write one.

Both directions of the gap are kept, each reading as a positive magnitude where it applies, because a query cannot negate a claim’s value.

3.5 code — standing rules

Each holds continuously: its conclusion is in force exactly while its condition holds over your data, and withdraws itself when the condition stops holding.

Two notes that are contract rather than commentary:

• The thresholds are values, not percentiles. > 10, > 200, > 20, > 5 select whatever your store has, and select nothing when your store has nothing. A percentile would always name someone, including in a codebase with no hub at all. They are yours to argue with; they are not adaptive.
• A rule cannot be all absences. untested and uncalled_fn carry a positive premise (lines > 0, lines >= 0) as a range, not a filter — a rule whose every premise is an absence has no set to work over and is refused.

3.6 code — queries

Called by name after import code. Every one answers over the facts you have loaded, and over nothing else.

impact_of walks to a fixed depth, not to a fixpoint. That is a stated bound, not an approximation to be improved: the language guarantees termination and a reachability closure is not something it will run.

An empty answer is an answer. It means no loaded fact satisfies the question — which is different from the question being unanswerable, and different again from the field being empty because nobody wrote it. §4.4.

4.1 What the package guarantees about itself

These are properties, asserted in the package’s own suite, that a caller may depend on:

• No network. No module in the package opens a connection, except dke.client, whose entire purpose is to.
• No subprocess. The package spawns nothing.
• Zero runtime dependencies. Nothing beyond the Python standard library.
• Python 3.10 or later, a hard floor with a named cause.
• No engine code. The package contains none and never will.

4.2 dke.factwriter — domain-free

The layer that knows how to write a fact-loading program and nothing about what the facts mean. Public surface:

FactProgram.put(attr, value) is the one way a target cell is named, and its argument is the Kind.subject.field path of §2.1. A producer that writes through anything else is outside what §5.4’s check can see.

dke.factwriter is re-exported at the package root: from dke import FactProgram, Ids, sanitize.

4.3 dke.ingest — the code readers

Readers for one domain — source code — that are both consumers of dke.factwriter and the worked example of §5. dke.ingest.core holds the domain-shared layer and MODULE = "code", which names the module these facts are for, and one reader submodule per source language sits beside it.

Naming asymmetry, stated because it will otherwise look like a bug. The reader class for code.Class is spelled Klass in Python, because class is a Python keyword. The fact it writes is code.Class. The Python spelling is the producer’s business; the kind name is the contract.

Exit statuses are part of the contract: EXIT_OK, EXIT_NO_SUCH_PATH, EXIT_NOTHING_TO_READ. A reader that read nothing MUST NOT exit zero — an empty load and a successful one are the two outcomes it exists to distinguish.

4.4 dke.client — reaching the service

The wire client. DEFAULT_ENDPOINT and PROTOCOL_VERSION name what it talks to. Its error hierarchy is a contract: DkeError is the base, TransportError carries an HTTP status, ProtocolError carries a wire code, and PaymentRequired is a ProtocolError a caller SHOULD handle distinctly.

On telling an empty answer from an empty store. When a query returns nothing and you cannot tell which it is, checkup reports unmet <Kind>.<field> for a cell a standing rule reads that holds nothing — including the case where a field is absent-read and was never recorded anywhere. That is the difference between no test reaches these and no test was looked for, and it is the intended instrument for §2.4 going wrong.

5.1 Requirements on a producer

1. A producer MUST write only into fields the module declares (§3.3). A field the module does not declare is a fact that lands where nothing reads.
2. A producer MUST NOT write a derived field (§3.4) or a rule conclusion (§3.5).
3. A producer MUST write absence-read fields only where true (§2.4).
4. A producer MUST use subjects, not display names, wherever a field holds a reference to another fact (§3.3, Call).
5. A producer MUST NOT assert an edge it did not resolve; it SHOULD record the unresolved call instead (§3.3, UnresolvedCall).
6. A producer SHOULD write every field it can determine. Writing fewer narrows what the module can conclude; it does not make anything wrong.

5.2 What is normal and not an error

A field the module declares that no producer writes is fine, and expected. Several exist. Some a customer supplies by hand — Function.deprecated. One whole kind, Counterpart, is written by nothing LangSyn publishes, because it records a claim about intent that only a reader can make.

This asymmetry is deliberate: the contract is one-way. A module may declare more than any producer writes. A producer may not write more than the module declares.

5.3 Compatibility

• Adding a class, a field, a rule or a query to a module is a compatible change. Existing producers keep working; the new field is simply unwritten.
• Removing or renaming a class or field a producer writes is a breaking change, and the module’s version reflects it.
• Changing a rule’s threshold changes what your store concludes without changing any name. It is a semantic change, and it is checked: the thresholds in §3.5 and the module’s own must agree, so a threshold cannot move without this document moving with it.
• Changing a rule’s condition in any other way — which fields it reads, how they combine — is a semantic change that no mechanical check sees (§5.4). It is visible in the module’s version and in §3.5’s prose, and nowhere else.
• The two artifacts version independently: dkepy and each module carry their own versions, and this specification carries its own. Read a version from the artifact it belongs to, never from prose.

5.4 What is mechanically checked, and what is not

Stated plainly, because the gap is where a producer author will otherwise assume protection that does not exist.

Checked.

• One direction of §5.1(1): a field written by any dkepy emitter that the module does not declare fails a gate before release. The check spans every generation of the emitter the published surface has ever held, not just the current one, because a customer may hold any of them.
• This document against the module it specifies, in both directions: every kind, field, derived field, rule and query the module declares is named here, and every rule, query and derived field this document promises exists there. Rule thresholds, the kind a rule ranges over, the field it concludes, and a derived field’s definition are compared as values, not merely as names.

Not checked, and each of these is real:

• Types. A field declared string that a producer writes as an int passes every check here.
• What a rule reads. Thresholds are compared, but the rest of a condition is not: a module can keep every field name and every threshold and still change which fields a rule combines, or how.
• Producers we do not publish. A producer you wrote is bound by §5.1 and measured by nothing. checkup is the instrument that answers from your own store.
• Absence discipline. §2.4 is a requirement no gate enforces. Its failure mode is a plausible answer rather than an error, which is exactly why it is written as a MUST.