DKE MCP — Wire & Tool Contract

4.1 compile — validate and store a module

Turn a module’s source into a named, stored unit (“compile and keep”). This is the only path that creates durable state (stored modules, scripts, rules, kinds). A .dpy source is a module (Reference §9.1): compile stores the module text under name and runs its body — executing its data declarations, installing its rules, and making its defs callable.

• Params:
  • name (required, string) — the module’s name in the store. It MUST be a single identifier of the same shape import <name> accepts in DKE Python: an XID_Start character followed by XID_Continue characters, with no dot and no hyphen. A module you cannot name in an import statement is a module you cannot use, so the name is held to the language’s own rule.
  • source (string, optional) — the module text; omit to reload an already-stored module (re-run its body).
  • version (string, optional) — your label for this revision of the module, e.g. "2.1.0". Recorded as metadata and reported by info_module; it changes nothing about how the module resolves or runs. Compared for equality and never ordered, so any different value is a change — including going back to a label you used before. Omitting it on a later compile leaves the version already recorded alone, so an unrelated edit cannot erase a label. A module you never versioned simply has none.
  • language (enum, default "eng") — see §8.
  • store_id (string, default "default").
• Success: _meta.status = "success", the module’s identity and the module.script names it installed.
• Invalid source: isError = true, _meta.status = "compile_error", _meta.compile_status ∈ { parse_error, type_error }, _meta.diagnostics = [{ class, line, col, message, fix? }]. Nothing is stored: a module that does not compile leaves the store as it was.

The service MUST:

1. Lex, parse, and typecheck the source.
2. If any check fails, refuse the operation; no storage occurs.
3. Otherwise, store every declaration of the unit under its own declared name, atomically (all of the unit or none of it), each executable by name, and run the module body once.

A unit that is exactly one def is just a one-declaration module — compile submits it like any other; there is no separate single-script verb.

What the response says. It acknowledges the submission, states what it installed — the classes, scripts, rules and computed fields the unit declared — and then reports what the module body did: its print output and its store effects, in execution order, because running the body is part of submitting the source (step 3 above).

Each part appears only when it has something to say. A module that declares nothing installable — a data declaration alone — states no installs; a module with no body reports none; a module with neither is acknowledged on its own. The installs are what this submission installed, so reloading a stored module by name states none: its declarations are already stored, and only its body is run again.

Name resolution, re-submission reconciliation, and namespacing are specified in Reference §9.

4.2 run — execute

Execute instructions and return a transcript plus usage.

• source (string, required) — a program: statements that read, write, and call compiled scripts. Compiled and executed once, not stored; anything it remembers persists, but nothing is left callable and nothing appears in list. A source with no statements has nothing to execute and is refused.
• language (enum, default "eng"), store_id.

A program has no parameters — write the values you want into the instructions — and it cannot create definitions. A source declaring a def, a class, a @rule, or a computed field is refused, with a message directing you to compile it. A program cannot return either; a value it wants to report, it prints or binds.

To execute something you compiled, import its module and call it:

{"source": "import inventory\ninventory.restock(\"widget-1\")"}

A value script composes the same way, its result bound in the program (n = inventory.count_on_hand("widget-1")); the binding appears in the transcript as a typed entry carrying the value.

What a run reports. The run executes against the store’s current state. The transcript renders in the natural language the source was compiled in (§8), and covers everything the run did, in execution order, including the effects of any module the program imported. Its call frame is the response header, not a body line: a successful run is headed OK program: <verdict> and a failed one error: program failed — <reason>. The verdict tallies what the run did — the count of claims written, claims removed, and print lines. Both store counts are in claims, not statements, and a statement that changed no state reports no effect at all — it earns no place in a tally of what changed, and its target is not listed among the effects either. One forget removes every claim at the address it names, so a statement that removed three reports three and one that found nothing to remove reports nothing. A range forget is the exception to that first clause and not to the second: it names the older versions before an instant rather than everything at the address, so it can report fewer than the address holds — and it never removes the value in force, which is why the count it reports can be zero at a cell that plainly has a value. A remember of a value a source has already recorded at that cell is likewise no change: the store is idempotent, so the write succeeds, adds no claim, and is reported as adding none. (update replaces rather than matching, so it records a claim even when the value is the one already there.) The body then lists, in execution order, the run’s output (the values the program prints) and its store effects (the remember/update/forget writes, each naming its target cell). Statements that change no state stay silent — assignment bindings, control flow (if/match/for), transaction verbs (branch/commit/rollback), and read/query calls — so the body carries the run’s outputs and durable effects, not its execution mechanics.

This human-readable render is presentation, not a versioned contract: a conforming implementation MAY format the header, verdict, and effect lines differently. What is pinned is that the render is deterministic (same source + same store → byte-identical transcript) and that the machine-readable result carries the run’s terminal status and its print sequence.

A run is not transactional: a failed run does not undo writes already executed by earlier statements (its data writes persist either way); only a branch block groups writes transactionally.

6.1 The repair loop — a rejected submission, its fix, and the resubmit

A compile_error is not a dead end, and this is the loop most agent workflows spend most of their turns in. Every diagnostic carries message for a person and, where the correction is mechanical, fix for a program. They are separate fields on purpose: one response serves a reader and a client without serving either badly, and a client applying fix never has to parse prose.

Submit a module written on Python reflexes:

{ "name": "watch",
  "source": "def watch(n: int):\n    i = 0\n    while i < n:\n        print(\"checking\")\n" }

The submission is refused whole — nothing is stored — and the diagnostic says both what is wrong and what to write instead:

{ "isError": true,
  "_meta": {
    "status": "compile_error",
    "compile_status": "parse_error",
    "diagnostics": [{
      "class": "parse_error",
      "line": 3, "col": 5,
      "message": "DKE Python has no `while` loop — iteration is bounded: `for <var> in <finite collection>:` over a store-derived collection (e.g. `list attributes of K`). Bounded iteration is the termination guarantee; there is no unbounded loop.",
      "fix": "for <var> in <collection>:"
    }]
  }}

line and col say where, fix says what to write, and the resubmission is the same call with that edit applied:

{ "name": "watch",
  "source": "def watch(k: string):\n    for a in list attributes of k:\n        print(a)\n" }

Two properties make this a loop a client can drive rather than a message a person must read:

• A rejected compile stores nothing. The store is exactly as it was, so a retry is a retry and never a partial write to undo (§4.1).
• fix is present only when the correction is mechanical. Its absence is not an omission — it means the diagnostic has no single edit to offer, and message is the whole of what the service can say. Treat fix as optional and fall back to message; never require it.

The diagnostics most worth expecting are the ones where a Python habit is the wrong reflex here — no while, no recursion, procedures do not return a value, and a list has no .append. Each of those refuses with the DKE Python form to write instead, so the first submission an agent writes from Python memory is usually one edit from compiling rather than a rewrite.

8.1 What language selects

language selects the keyword surface — the words the runtime reserves — and nothing else. Verbs, keywords and the words in the response are in the tag you ask for; the kinds, subjects, attributes and values you supply are your data and are stored and returned exactly as written.

The same program in both surfaces:

{"name": "run", "arguments": {
  "language": "eng",
  "source": "remember(Sensor.s1.room, \"kitchen\", \"survey\")\nc = current(Sensor.s1.room)\nprint(c.value)"}}

{"name": "run", "arguments": {
  "language": "nob",
  "source": "husk(Sensor.s1.room, \"kitchen\", \"survey\")\nc = gjeldende(Sensor.s1.room)\nskriv(c.value)"}}

Both write the same claim and both print kitchen. Sensor, s1, room, kitchen and survey are yours and do not change; remember/husk, current/gjeldende and print/skriv are ours and do. value does not: a field of a result is addressed by the same name in every surface.

This has three consequences worth stating plainly:

• A store is not language-scoped. A module compiled under "nob" is read, invoked and forgotten by exactly the same names as one compiled under "eng", and the two see each other’s claims. There is no separate Norwegian store and no migration between surfaces.

• Two words are English on every surface. The two diagnostic verbs, which exist only in English — a program in any surface writes them in English or the call is not recognised. Everything else in the keyword surface localises, the except handler kinds and the compound verb heads included. Reference §12 carries the same list, and the same check holds both.

  English on every surface. why_not what_needs

• A module remembers the surface it was compiled in. info_module reports it as the module’s init language, and a script’s transcript renders in that surface — so a Norwegian module keeps answering in Norwegian even when a later call omits language and takes the "eng" default.

The verbs that operate on a stored script — list, info, forget — are edition-neutral and take no edition: only the source-carrying verbs, compile and run, select one.

9.1 Language

• spec(edition, topic?) — serve the DKE Python language contract, full or a topic slice ∈ { header, types, verbs, statements, scripts }.

9.2 Scripts — address by module.script

• list(target = scripts | rules | kinds) — stored module.script signatures, standing-rule names, or the kinds your data is stored under (§9.2.1). A script’s line carries its full call signature: the name and its typed parameters in declaration order (inventory.ingest(id: int, payload: string, dry_run: bool)). Listing order is implementation-defined but MUST be stable across reads with no intervening compile / forget. In expression position inside a program, list_scripts() evaluates to a string_list of those names — the one lifecycle read that is also callable in-language, because it is a read-only data read.
• info(name) — a script’s compile provenance: the compiling authority, the natural language the source was compiled in, and the manifest version the compiled form was produced against. Invocations are not tracked — info describes the compilation event, not any run. (For a data derivation, use the in-language why(K.s.a), which returns a proof_tree; info’s response is text, not a typed value.)
• forget(name) — remove one script. Idempotent: if no script with that name exists, the call succeeds.

9.3 Standing declarations — address by module.<name>

A rule and a constraint are both standing declarations a module installs, and both are addressed the same way. They are removed by different verbs because they remove different amounts: one withdraws what it derived, the other has derived nothing.

• forget_rule(name) — remove one standing rule, leaving the rest of its module in place. The facts the rule concluded are removed with it; the facts it concluded from are untouched, so re-compileing the module brings the rule and its conclusions back. A conclusion that another standing rule still supports survives. Removing a rule that is already gone succeeds. Use list(target = rules) to see the names.
• forget_constraint(name) — remove one standing constraint, leaving the rest of its module in place. Nothing is reclaimed: a constraint concludes nothing, so there is no derived fact to withdraw, and the data it watched is untouched — including the subjects that breached it. Stopping the watch is not fixing the breach. Re-compileing the module brings the constraint back. Removing one that is already gone succeeds. checkup() prints the names, in its violated findings.

9.4 Modules — address by bare module name

• list_modules() — module handles (name, script count, created-at). Listing order is implementation-defined but MUST be stable across reads with no intervening compile / forget_module.
• info_module(name) — a module’s record: its init language (the natural language its body was compiled in), the module.script names it defines, the classes it declares when it declares any, its version if it has one, updated-at, and created-at. created is when the module was first stored; updated is when its content last changed, and a compile that submits identical content leaves it alone. Worth reading when a module you import may have moved: a call is resolved when the calling module is compiled, so a caller keeps running the callee body present at that moment until you compile the caller again. An unknown module is a clean not-found.
• forget_module(name, confirm=true) — remove a module as a unit. confirm=true is required; it cascade-removes the module’s scripts, kinds, and their data, and is not reversible. It refuses, naming the referrer, if another stored module still references the target — so no dangling references can exist. Forgetting a module that does not exist is a clean not-found.

name here is the bare module name, never a module.script address.

9.5 Store

• stores() — your store’s id, size, and created-at. Your key addresses exactly one store. Everything that acts on the store ITSELF — creating it, deleting it, snapshotting it, restoring it from a snapshot — happens in the account dashboard, not on this wire. Your key governs what may be done to the DATA INSIDE your store; the store’s own lifecycle belongs to the account that owns it.

9.6 Checkup — does your store meet the reasoning over it?

• checkup() — no arguments, changes nothing, needs only a read key.

Reach for it when a query returns nothing and you cannot tell whether the answer is genuinely no. A rule that never fired and a rule that fired and found nothing produce the same empty result, and when the reasoning came from a module you did not write, nothing in the result tells you which one happened.

The report is a counts line followed by findings, one per line:

A near line is the one to read first. Writing your facts under a kind spelled one letter differently from the one the reasoning reads produces both an unread line and an unmet line, and the pair names the mis-spelling in a way neither line does alone.

Findings name cells, not rules: what an unmet cell needs is your data, and the address of the data is the actionable part. Rules are counted rather than named.

An empty store reports its counts and nothing else. Listing order is stable across reads with no intervening change.