[PLUGIN] Add lib_deontic: a defeasible deontic logic reasoning engine

docs/deontic/README.md

@@ -0,0 +1,185 @@
+# OmegaClaw Deontic Engine
+
+A **defeasible deontic logic reasoner** with a **task-orchestration layer** on top,
+implemented natively in MeTTa on the PeTTa interpreter. It answers two questions
+that graded-belief engines (NAL/PLN) do not:
+
+- **What defeasibly holds** when rules conflict — conclusions that a later fact can
+  *retract* (non-monotonic), resolved by rule specificity / priority.
+- **What is obligated, permitted, or forbidden** — and whether an action complies,
+  violates, or sits in an unresolved dilemma, including over time.
+
+If you need *retractable* conclusions, *rule priority*, *norms* (O/P/F, compliance,
+deadlines), or *temporal* reasoning (Event Calculus, Allen intervals), this is the
+engine. The **directive** layer then uses it to coordinate tasks: a plan of work
+plus dependency rules, from which the engine derives what is actionable and a
+claim/complete lifecycle is enforced.
+
+---
+
+## What's in the box
+
+| Piece | File | What it does |
+|---|---|---|
+| **Core reasoner** | `lib_deontic.metta` | Defeasible Logic DL(d) + Standard Deontic Logic + Event Calculus + trust |
+| **Directive layer** | `lib_directive.metta` | Task orchestration on top of the reasoner (dependency-ordered work) |
+| Reference | [`reference-lib-deontic.md`](../reference-lib-deontic.md) | Full reasoner API |
+| Reference | [`reference-lib-directive.md`](../reference-lib-directive.md) | Full directive API |
+
+Optional feature layers live on their own branches (see *Layered architecture*).
+
+---
+
+## The theory it implements
+
+- **Defeasible Logic** (Nute; Antoniou et al.) — strict (`->`), defeasible (`=>`),
+  and defeater (`~>`) rules, a **superiority** relation, ambiguity blocking, and the
+  four DL(d) provability tags **±Δ** (definite) / **±∂** (defeasible).
+- **Standard Deontic Logic** (Governatori) — obligation/permission/prohibition with
+  `F p ≡ O ¬p`, **contrary-to-duty** ⊗-reparation chains, and **deontic dilemmas**.
+- **Event Calculus** + the 13 **Allen** interval relations + temporal-deontic
+  **deadlines** (achievement / maintenance).
+- **Weakest-link trust** over multi-source claims, with per-source weights and gates.
+
+Conclusions are a set of `(tag literal)` pairs; tags are `pD`/`nD` (±Δ) and `pd`/`nd`
+(±∂). A literal is `(lit <sign> <mode> <temporal> <functor> <args>)`. See the
+[reasoner reference](../reference-lib-deontic.md) for the full tag/literal model.
+
+---
+
+## Theories and plans are ordinary `.metta` files
+
+There is **no bespoke parser**: a theory/plan is read by PeTTa's own loader, so it is
+just MeTTa atoms. The surface forms:
+
+| form | meaning |
+|---|---|
+| `(given p)` | a fact |
+| `(always L a b)` / `(normally L a b)` / `(except L a b)` | strict / defeasible / defeater rule |
+| `(prefer L1 L2)` | superiority: rule `L1` out-ranks `L2` |
+| `(not p)` · `(must p)` · `(forbidden p)` · `(permitted p)` | negation · deontic O/F/P |
+| `(deadline …)` | temporal-deontic deadline obligation |
+| `(happens e t)` · `(initiates e f t)` · `(terminates e f t)` · `(during LIT ?T)` | Event Calculus / Allen |
+| `(claims src … )` · `(trusts src v)` · `(threshold n v)` | sourced facts / trust weights / gates |
+
+The arrow-syntax `.dfl` format is also accepted (same theory, textbook notation).
+
+---
+
+## Quickstart
+
+`examples/deontic/penguin.metta` — the specific rule defeats the general one:
+
+```metta
+(given bird) (given penguin)
+(normally r1 bird flies)
+(normally r2 penguin (not flies))
+(prefer r2 r1)                 ; penguins are more specific
+```
+
+```metta
+!(import! &self (library OmegaClaw-Core lib_deontic))
+!(dl-run (dl-path examples/deontic/penguin.metta))
+; => includes (pd (lit neg none none flies ()))  — defeasibly NOT flies
+;            and (nd (lit pos none none flies ())) — r2 defeats r1
+```
+
+Key entry points: `(dl-run <path>)` for the conclusion set, `(dl-run-deontic <path>)`
+for the SDL closure, `(dl-run-at <path> <time>)` for as-of reasoning,
+`(deontic-compliance <path>)` / `(deontic-dilemmas <path>)` for norm analysis, and the
+non-monotonic queries `(dl-what-if …)` / `(dl-why-not …)` / `(dl-abduce …)` /
+`(dl-requires …)`. Full tables in the [reference](../reference-lib-deontic.md).
+
+---
+
+## Two reasoning backends — the engine toggle
+
+The same theory runs through either of two interchangeable backends, with
+**identical conclusions**:
+
+| backend | what it is | when |
+|---|---|---|
+| `prolog` *(default)* | the fast indexed Prolog kernel (`grounding.pl` / `reason.pl`) | grounding-heavy theories (variable rules over lots of data) |
+| `native` | the atomspace-native MeTTa engine (`ground.metta` / `reason.metta`) | propositional / coordination plans, and inspection / debugging |
+
+Switch per run with `(dl-engine! native)` or `$OMEGACLAW_DL_ENGINE=native`.
+
+**Why two?** Native reasoning is at parity, but native *grounding* (instantiating
+variable rules) runs ~4–5× slower than the Prolog kernel on grounding-heavy theories
+— the cost is per-operation MeTTa-eval overhead, not the algorithm (semi-naive and
+functor-indexed variants were measured; neither closes it). So `prolog` is the
+default for variable-rule-heavy work, while `native` is free where it matters
+(propositional plans, where grounding is trivial) and keeps every rule/atom
+inspectable in the atomspace. See the perf note in `src/deontic/ground.metta`.
+
+---
+
+## The directive layer — dependency-ordered task coordination
+
+`lib_directive.metta` turns the reasoner into a **task orchestrator**. A plan lists
+tasks and **readiness rules** (a task becomes ready once its dependencies complete);
+the defeasible engine derives what is actionable, and a claim/complete lifecycle is
+enforced so nothing happens out of order.
+
+```metta
+!(import! &self (library OmegaClaw-Core lib_directive))
+!(directive-next   <plan>)     ; the assignments whose dependencies are satisfied
+!(directive-status <plan>)     ; tasks / ready / claimed / blocked / completed
+!(directive-claim    <plan> <task> <agent> False)
+!(directive-complete <plan> <task> <agent>)   ; completing deps unlocks dependents
+```
+
+Claims/completions are **appended** to the plan `.metta` file with version-superiority
+blocks, so the plan is its own durable, auditable state. Blocking propagates through
+the dependency DAG (`directive-block` → downstream `upstream-blocked`). Full API in the
+[directive reference](../reference-lib-directive.md).
+
+---
+
+## Layered architecture
+
+The engine is the base; each capability is an **independently selectable layer**
+(each on its own branch, all building on the core):
+
+| layer | branch | adds |
+|---|---|---|
+| **core reasoner** | `deontic-core` | the DL(d) / SDL / EC / trust engine |
+| **directive** | `deontic-directive` | task orchestration (this branch) |
+| NAL/PLN bridge | `deontic-nal-bridge` | feed graded-belief conclusions into deontic rules |
+| agent skill | `deontic-skill` | expose the reasoner as an agent skill |
+| policy guardrail | `deontic-policy-guardrail` | gate agent actions against a deontic policy |
+| semantic | `deontic-semantic` | semantic retrieval into the reasoning loop |
+
+The reasoner itself is a thin MeTTa facade (`src/deontic/*.metta` — `engine`, `query`,
+`deontic`, `eventcalc`, `trust`, `ground`, `reason`) over a deterministic kernel
+(`src/deontic/platform/*.pl`). `platform.metta` is the only module that knows the
+engine runs on PeTTa.
+
+---
+
+## Running the tests
+
+```sh
+SWIPL=…/swipl    # the PeTTa build
+$SWIPL --stack_limit=8g -q -s PeTTa/src/main.pl -- tests/deontic/test_core.metta --silent
+```
+
+The suite is **139 tests** across `tests/deontic/` (core, CTD, deadline, deontic, dfl,
+eventcalc, incremental, query, temporal, trust) and `tests/integration/` (directive,
+analyze, inspect, mining). It passes identically under **both** engine backends
+(`OMEGACLAW_DL_ENGINE=prolog` and `=native`).
+
+---
+
+## When to use this vs NAL / PLN
+
+| You need… | Use |
+|---|---|
+| Retractable (non-monotonic) conclusions, rule priority | this engine |
+| Norms: O/P/F, compliance, dilemmas, deadlines | this engine |
+| Temporal reasoning (Event Calculus, Allen intervals) | this engine |
+| Dependency-ordered task coordination | the directive layer |
+| Graded belief from noisy multi-source evidence | NAL / PLN |
+
+NAL/PLN decide *how much you believe* a fact; this engine decides *what defeasibly
+holds and what you ought to do* given those facts.

docs/reference-lib-deontic.md

@@ -0,0 +1,140 @@
+# Reference — `lib_deontic.metta`
+
+Defeasible, deontic, and temporal reasoning. Where `lib_nal`/`lib_pln` grade **how much** a fact is believed, `lib_deontic` answers what **defeasibly holds** under conflicting rules and what is **obligated, permitted, or forbidden** — non-monotonic and normative reasoning. It is the engine to reach for when conclusions must be *retractable* (a later fact can overturn an earlier one) or when an action must be checked against norms.
+
+Theory: Nute/Antoniou **Defeasible Logic**, Governatori **defeasible deontic logic**, the **Event Calculus** + the 13 **Allen** interval relations for time. It also fills the gap [reference-lib-nal.md](./reference-lib-nal.md) notes — "real-time / temporal reasoning is not served by a stock engine."
+
+---
+
+## Conclusion tags
+
+Reasoning over a theory yields a set of `(tag literal)` conclusions. Tags are the four standard Defeasible-Logic provability degrees:
+
+| tag | DL notation | meaning |
+|---|---|---|
+| `pD` | +Δ | **definitely** provable (facts + strict rules alone) |
+| `nD` | −Δ | definitely refuted |
+| `pd` | +∂ | **defeasibly** provable (a rule fires and every attacker is defeated or out-ranked) |
+| `nd` | −∂ | defeasibly refuted |
+
+A literal is `(lit <sign> <mode> <temporal> <functor> <args>)`: `sign` ∈ `pos|neg`, `mode` ∈ `none|O|P|F` (obligation / permission / prohibition), `temporal` ∈ `none|(iv <start> <end>)`.
+
+---
+
+## Theory surface syntax (MeTTa / DFL)
+
+A theory is a `.metta` (or arrow-format `.dfl`) file:
+
+| form | meaning |
+|---|---|
+| `(given p)` | a **fact** |
+| `(claims src p)` | a fact asserted **by a source** (carries provenance for trust) |
+| `(always L a b)` | **strict** rule `a -> b` (classical: if `a` then `b`) |
+| `(normally L a b)` | **defeasible** rule `a => b` (`b` unless defeated) |
+| `(except L a b)` | **defeater** `a ~> b` (blocks the opposite of `b` without proving `b`) |
+| `(prefer L1 L2)` | **superiority**: rule `L1` out-ranks `L2` |
+| `(not p)` | classical negation |
+| `(must p)` / `(forbidden p)` / `(permitted p)` | deontic mode O / F / P on `p` (`F p ≡ O ¬p`) |
+| `(deadline …)` | a temporal-deontic deadline obligation (achievement / maintenance) |
+| `(happens e t)` / `(initiates e f t)` / `(terminates e f t)` | Event-Calculus events/effects |
+| `(during LIT ?T)` | bind an interval handle for Allen-relation constraints |
+| `(trusts src v)` / `(threshold name v)` | per-source trust weight / a trust gate |
+
+---
+
+## API
+
+Reach the engine through the `(metta …)` skill. A theory is loaded from a path via `(dl-path <repo-relative-file>)`.
+
+### Defeasible reasoning
+| call | returns |
+|---|---|
+| `(dl-run <path>)` | the full sorted `(tag lit)` conclusion set |
+| `(dl-run-at <path> <ref>)` | conclusions **as of** a reference time (drops temporally-inactive atoms) |
+| `(dl-run-deontic <path>)` | conclusions under the Standard Deontic Logic closure (`F p ≡ O ¬p`, `O p → P p`) |
+| `(dl-print <path>)` | pretty-prints each conclusion (`  +D penguin`) |
+
+### Deontic analysis
+| call | returns |
+|---|---|
+| `(deontic-compliance <path>)` | per-obligation verdict report: fulfilled / violated / pending |
+| `(deontic-dilemmas <path>)` | obligations in conflict (`O p` and `O ¬p` both applicable, neither resolved) |
+| `(deadline-status <path> <now> <functor>)` | deadline verdict (achievement vs maintenance) at time `now` |
+
+### Non-monotonic queries
+| call | returns |
+|---|---|
+| `(dl-what-if <path> <hyps> <goal>)` | the goal's status and newly-provable literals after assuming `<hyps>` |
+| `(dl-why-not <goal>)` | the rules/defeats that block a goal |
+| `(dl-abduce <goal>)` | minimal fact-sets that would make the goal provable |
+| `(dl-requires <path> <goal>)` | support the goal cannot do without |
+
+### Trust & explanation
+| call | returns |
+|---|---|
+| `(trust-of <lit>)` | weakest-link trust over the proof tree, `[0,1]` |
+| `(justify <lit>)` | bundled DL status + proof tree + trust + sources + confidence |
+| `(dl-trust-run <path>)` | conclusions annotated with trust + sources |
+
+### Temporal (Event Calculus)
+`(ec-intervals …)`, `(ec-holds-at …)`, `(ec-violated-at …)`, `(ec-timeline …)`.
+
+### Engine backends
+The reasoner ships two interchangeable backends with **identical conclusions**:
+`prolog` (default — the fast indexed kernel) and `native` (the atomspace-native MeTTa
+engine). Switch with `(dl-engine! native)` or `$OMEGACLAW_DL_ENGINE=native`. Use
+`prolog` for grounding-heavy theories and `native` for propositional plans /
+inspection — see [deontic/README.md](./deontic/README.md#two-reasoning-backends--the-engine-toggle).
+
+---
+
+## Worked examples
+
+### Defeasible: the penguin overrides the bird rule
+`examples/deontic/penguin.metta`:
+```
+(given bird) (given penguin)
+(normally r1 bird flies)
+(normally r2 penguin (not flies))
+(prefer r2 r1)            ; penguins are more specific
+```
+```metta
+!(import! &self (library OmegaClaw-Core lib_deontic))
+!(dl-run (dl-path examples/deontic/penguin.metta))
+```
+Conclusion set includes `(pd (lit neg none none flies ()))` (defeasibly **not** flies) and `(nd (lit pos none none flies ()))` — the specific rule `r2` defeats `r1`.
+
+### Deontic: an unresolved dilemma
+`examples/deontic/deontic_dilemma.metta`:
+```
+(given a)
+(normally r1 a (must p))
+(normally r2 a (forbidden p))
+```
+```metta
+!(deontic-dilemmas (dl-path examples/deontic/deontic_dilemma.metta))
+```
+Returns one dilemma: `O p` and `O ¬p` are both applicable and neither is ranked above the other, so neither obligation is discharged.
+
+---
+
+## When to use `lib_deontic` vs. NAL / PLN
+
+| Situation | Engine |
+|---|---|
+| Conclusions that a later fact can **retract** (non-monotonic) | `lib_deontic` |
+| Rule **priority** / specificity conflicts (superiority) | `lib_deontic` |
+| **Norms**: obligations / permissions / prohibitions, compliance, dilemmas, deadlines | `lib_deontic` |
+| **Temporal** reasoning (Event Calculus, Allen intervals) | `lib_deontic` |
+| Graded **belief** from noisy multi-source evidence | NAL / PLN |
+| Inheritance / implication chains with confidence decay | NAL `\|-` |
+| Property-based categorical inference | PLN `\|~` |
+
+The two are complements: NAL/PLN decide *how much you believe* a fact; `lib_deontic` decides *what defeasibly holds and what you ought to do* given those facts.
+
+---
+
+## See also
+- [reference-lib-nal.md](./reference-lib-nal.md) — evidential (NARS) reasoning.
+- [reference-lib-pln.md](./reference-lib-pln.md) — probabilistic reasoning.
+- [reference-orchestration.md](./reference-orchestration.md) — picking an engine.

examples/deontic/deadline_demo.metta

@@ -0,0 +1,5 @@
+;; Temporal-deontic deadlines (Governatori et al. 2007), a temporal-deontic extension.
+;; Achievement: pay by 30 (sanction: fine). Maintenance: no trespass in [0,100].
+(deadline (must pay) achieve 0 30 fine)
+(deadline (forbidden trespass) maintain 0 100 penalty)
+(given (during pay 25 25))

examples/deontic/deontic_dilemma.metta

@@ -0,0 +1,4 @@
+;; Deontic dilemma: obligation vs prohibition of p, no superiority to resolve.
+(given a)
+(normally r1 a (must p))
+(normally r2 a (forbidden p))

examples/deontic/penguin.metta

@@ -0,0 +1,11 @@
+; Classic Tweety/Penguin example
+; Penguins are birds that don't fly
+
+(given bird)
+(given penguin)
+
+(normally r1 bird flies)
+(normally r2 penguin (not flies))
+
+; Penguins are more specific than birds
+(prefer r2 r1)

lib_deontic.metta

@@ -0,0 +1,28 @@
+; lib_deontic — Defeasible + Deontic + Temporal logic for OmegaClaw.
+;
+; A reasoning library, sibling to lib_nal / lib_pln. Where NAL/PLN grade how much
+; a fact is believed, this library answers what *defeasibly holds* under
+; conflicting rules and what is *obligated / permitted / forbidden* — that is,
+; non-monotonic and normative reasoning (Nute's Defeasible Logic + Standard
+; Deontic Logic, with Event-Calculus temporal grounding). Pure library: it
+; defines vocabulary and inference; it registers no agent skill and does not
+; touch the loop.
+;
+; Theory of operation, end to end:
+;   load   — parse a theory (facts; strict -> / defeasible => / defeater ~> rules;
+;            superiority) into spaces;
+;   ground — instantiate variable rules over the Herbrand base (Datalog join);
+;   reason — DL(d) fixpoints produce four provability tags: +D/-D (definite, the
+;            monotonic core) and +d/-d (defeasible, ambiguity-blocking);
+;   read   — enumerate the tagged conclusion set; the deontic, temporal, and
+;            trust analyses all fold over it.
+!(import! &self (library OmegaClaw-Core src/deontic/platform/platform))
+!(import! &self (library OmegaClaw-Core src/deontic/types))
+!(import! &self (library OmegaClaw-Core src/deontic/ground))
+!(import! &self (library OmegaClaw-Core src/deontic/reason))
+!(import! &self (library OmegaClaw-Core src/deontic/engine))
+!(import! &self (library OmegaClaw-Core src/deontic/query))
+!(import! &self (library OmegaClaw-Core src/deontic/explain))
+!(import! &self (library OmegaClaw-Core src/deontic/trust))
+!(import! &self (library OmegaClaw-Core src/deontic/deontic))
+!(import! &self (library OmegaClaw-Core src/deontic/eventcalc))

lib_omegaclaw.metta

@@ -4,6 +4,7 @@
 !(import! &self (library lib_combinatorics))
 !(import! &self (library OmegaClaw-Core lib_nal))
 !(import! &self (library OmegaClaw-Core lib_pln))
+!(import! &self (library OmegaClaw-Core lib_deontic))
 !(import! &self (library OmegaClaw-Core lib_llm_ext.py))
 !(import! &self (library OmegaClaw-Core ./src/helper.py))
 !(import! &self (library OmegaClaw-Core ./src/agentverse.py))