@eir-labs/coltrane 0.24.37 → 0.24.39

package/skills/obligation-adjudicate/fixtures/dead-name-on-missing-fact.json

@@ -0,0 +1,47 @@
+{
+  "id": "dead-name-on-missing-fact",
+  "description": "A declared input the snapshot does not supply is DEAD_NAME, never a pass",
+  "input": {
+    "laws": [
+      {
+        "slug": "needs-fact",
+        "status": "executed",
+        "bearer": "org:eir-labs",
+        "law": {
+          "attributes": "Eir Labs Inc.",
+          "deontic": "obliged",
+          "aim": "pay the FY1 balance",
+          "conditions": "by 2027-03-31",
+          "or_else": "the GK may invoice interest",
+          "debtor": "org:eir-labs",
+          "creditor": "org:eir-gk",
+          "check": {
+            "predicate": "(= a b)",
+            "inputs": {
+              "a": "x",
+              "b": "y"
+            }
+          }
+        }
+      }
+    ],
+    "facts": {
+      "facts": {
+        "a": 1
+      },
+      "supplied_by": "org:eir-gk"
+    }
+  },
+  "assertions": [
+    {
+      "path": "results.0.outcome",
+      "op": "equals",
+      "value": "DEAD_NAME"
+    },
+    {
+      "path": "pass",
+      "op": "equals",
+      "value": false
+    }
+  ]
+}

package/skills/obligation-adjudicate/fixtures/debtor-cannot-certify-itself.json

@@ -0,0 +1,43 @@
+{
+  "id": "debtor-cannot-certify-itself",
+  "description": "A snapshot supplied by the debtor is refused",
+  "input": {
+    "laws": [
+      {
+        "slug": "self-served",
+        "status": "executed",
+        "bearer": "org:eir-labs",
+        "law": {
+          "attributes": "Eir Labs Inc.",
+          "deontic": "obliged",
+          "aim": "pay the FY1 balance",
+          "conditions": "by 2027-03-31",
+          "or_else": "the GK may invoice interest",
+          "debtor": "org:eir-labs",
+          "creditor": "org:eir-gk",
+          "check": {
+            "predicate": "(= a b)",
+            "inputs": {
+              "a": "x",
+              "b": "y"
+            }
+          }
+        }
+      }
+    ],
+    "facts": {
+      "supplied_by": "org:eir-labs",
+      "facts": {
+        "a": 1,
+        "b": 1
+      }
+    }
+  },
+  "assertions": [
+    {
+      "path": "results.0.outcome",
+      "op": "equals",
+      "value": "refused"
+    }
+  ]
+}

package/skills/obligation-adjudicate/fixtures/decides-what-it-can.json

@@ -0,0 +1,43 @@
+{
+  "id": "decides-what-it-can",
+  "description": "An obligation whose predicate uses only implemented operators is decided",
+  "input": {
+    "laws": [
+      {
+        "slug": "w8-on-file",
+        "status": "executed",
+        "bearer": "org:eir-labs",
+        "law": {
+          "attributes": "Eir Labs Inc.",
+          "deontic": "obliged",
+          "aim": "pay the FY1 balance",
+          "conditions": "by 2027-03-31",
+          "or_else": "the GK may invoice interest",
+          "debtor": "org:eir-labs",
+          "creditor": "org:eir-gk",
+          "check": {
+            "predicate": "(=> (has payee w8) (require (backed_by_form w8)))",
+            "inputs": {
+              "payee": "principal",
+              "w8": "instrument-ref"
+            }
+          }
+        }
+      }
+    ],
+    "facts": {
+      "facts": {
+        "payee": "org:eir-gk",
+        "w8": "instrument-ref:w8ben-e-2026"
+      },
+      "supplied_by": "org:eir-gk"
+    }
+  },
+  "assertions": [
+    {
+      "path": "checks.0.method",
+      "op": "equals",
+      "value": "evaluate(check, fact-snapshot)"
+    }
+  ]
+}

package/skills/obligation-adjudicate/fixtures/empty-never-passes.json

@@ -0,0 +1,15 @@
+{
+  "id": "empty-never-passes",
+  "description": "No obligations supplied is not a pass",
+  "input": {
+    "laws": [],
+    "facts": {}
+  },
+  "assertions": [
+    {
+      "path": "pass",
+      "op": "equals",
+      "value": false
+    }
+  ]
+}

package/skills/obligation-adjudicate/fixtures/names-the-operator-it-wanted.json

@@ -0,0 +1,48 @@
+{
+  "id": "names-the-operator-it-wanted",
+  "description": "A payment predicate comes back UNDECIDED naming the comparison it needed",
+  "input": {
+    "laws": [
+      {
+        "slug": "fy1-balance",
+        "status": "executed",
+        "bearer": "org:eir-labs",
+        "law": {
+          "attributes": "Eir Labs Inc.",
+          "deontic": "obliged",
+          "aim": "pay the FY1 balance",
+          "conditions": "by 2027-03-31",
+          "or_else": "the GK may invoice interest",
+          "debtor": "org:eir-labs",
+          "creditor": "org:eir-gk",
+          "check": {
+            "predicate": "(>= paid_minor due_minor)",
+            "inputs": {
+              "paid_minor": "money",
+              "due_minor": "money"
+            }
+          }
+        }
+      }
+    ],
+    "facts": {
+      "facts": {
+        "paid_minor": 0,
+        "due_minor": 6151477
+      },
+      "supplied_by": "org:eir-gk"
+    }
+  },
+  "assertions": [
+    {
+      "path": "results.0.outcome",
+      "op": "equals",
+      "value": "UNDECIDED"
+    },
+    {
+      "path": "operators_wanted.0",
+      "op": "equals",
+      "value": ">="
+    }
+  ]
+}

package/skills/obligation-adjudicate/fixtures/no-check-is-not-a-pass.json

@@ -0,0 +1,35 @@
+{
+  "id": "no-check-is-not-a-pass",
+  "description": "An obligation with no check is unadjudicable, not a pass",
+  "input": {
+    "laws": [
+      {
+        "slug": "prose-only",
+        "status": "executed",
+        "law": {
+          "attributes": "Eir Labs",
+          "deontic": "obliged",
+          "aim": "use commercially reasonable efforts",
+          "conditions": "at all times",
+          "or_else": "the record states none"
+        }
+      }
+    ],
+    "facts": {
+      "facts": {},
+      "supplied_by": "org:eir-gk"
+    }
+  },
+  "assertions": [
+    {
+      "path": "results.0.outcome",
+      "op": "equals",
+      "value": "unadjudicable"
+    },
+    {
+      "path": "pass",
+      "op": "equals",
+      "value": false
+    }
+  ]
+}

package/skills/obligation-adjudicate/fixtures/proposed-is-not-in-force.json

@@ -0,0 +1,40 @@
+{
+  "id": "proposed-is-not-in-force",
+  "description": "A proposed bearing law is not adjudicated at all",
+  "input": {
+    "laws": [
+      {
+        "slug": "not-yet",
+        "status": "proposed",
+        "bearer": "org:eir-labs",
+        "law": {
+          "attributes": "Eir Labs Inc.",
+          "deontic": "obliged",
+          "aim": "pay the FY1 balance",
+          "conditions": "by 2027-03-31",
+          "or_else": "the GK may invoice interest",
+          "debtor": "org:eir-labs",
+          "creditor": "org:eir-gk",
+          "check": {
+            "predicate": "(= a b)",
+            "inputs": {
+              "a": "x",
+              "b": "y"
+            }
+          }
+        }
+      }
+    ],
+    "facts": {
+      "facts": {},
+      "supplied_by": "org:eir-gk"
+    }
+  },
+  "assertions": [
+    {
+      "path": "results.0.outcome",
+      "op": "equals",
+      "value": "not-in-force"
+    }
+  ]
+}

package/skills/obligation-adjudicate/fixtures/unattributed-snapshot-refused.json

@@ -0,0 +1,47 @@
+{
+  "id": "unattributed-snapshot-refused",
+  "description": "A snapshot naming no supplier is refused: absence declines rather than passes",
+  "input": {
+    "laws": [
+      {
+        "slug": "anon",
+        "status": "executed",
+        "bearer": "org:eir-labs",
+        "law": {
+          "attributes": "Eir Labs",
+          "deontic": "obliged",
+          "aim": "pay",
+          "conditions": "by then",
+          "or_else": "interest",
+          "debtor": "org:eir-labs",
+          "creditor": "org:eir-gk",
+          "check": {
+            "predicate": "(= a b)",
+            "inputs": {
+              "a": "x",
+              "b": "y"
+            }
+          }
+        }
+      }
+    ],
+    "facts": {
+      "facts": {
+        "a": 1,
+        "b": 1
+      }
+    }
+  },
+  "assertions": [
+    {
+      "path": "results.0.outcome",
+      "op": "equals",
+      "value": "refused"
+    },
+    {
+      "path": "pass",
+      "op": "equals",
+      "value": false
+    }
+  ]
+}

package/skills/obligation-adjudicate/meta.json

@@ -0,0 +1,12 @@
+{
+  "slug": "obligation-adjudicate",
+  "version": 1,
+  "skill_type": "verification",
+  "input_type": "bearing-law",
+  "output_type": "obligation-adjudication",
+  "determinism_ratio": 1.0,
+  "permission": {
+    "tier": 1
+  },
+  "description": "The first caller of evaluate(). Takes executed bearing laws and a fact snapshot, evaluates each law's check, and seals one verdict per obligation: PERMIT, DENY, UNDECIDED (with the operators the predicate asked for and the evaluator does not implement), DEAD_NAME (a declared input the snapshot does not supply), unadjudicable (no check), not-in-force (status proposed), or refused (the snapshot came from the debtor — an obligor does not certify its own discharge). It does not widen the operator set: the operators an obligation actually wanted are reported, so the next one implemented is chosen by a real obligation rather than a design guess. Tier 1 because it imports the engine's evaluator."
+}

package/skills/obligation-adjudicate/skill.mjs

@@ -0,0 +1,91 @@
+// obligation-adjudicate — the first caller of the predicate evaluator. Deterministic, no model.
+//
+// evaluate() has been in this engine with no production call-site: a mechanism with passing tests
+// and nothing wired to it. This chair is the wire. It takes bearing-law records and a fact
+// snapshot, evaluates each law's `check`, and seals one verdict per obligation.
+//
+// It deliberately does NOT widen the operator set. Every obligation whose predicate needs an
+// operator the evaluator lacks comes back UNDECIDED, named, with the operator that was missing —
+// so the next operator to implement is chosen by an obligation that asked for it rather than by
+// a design guess. U is never rounded into a decision; that is the evaluator's own discipline and
+// this chair keeps it.
+//
+// Decisions it makes on its own, and why:
+//   - an obligation with NO check is `unadjudicable`, not a pass. A clause the machine cannot
+//     decide is prose-tier work and belongs with a person.
+//   - a `proposed` bearing law is not adjudicated at all: nothing is in force until it is executed.
+//   - an obligor may not certify its own discharge, so this chair refuses to adjudicate a law whose
+//     fact snapshot was supplied by the debtor (`facts.supplied_by === law.debtor`).
+import { evaluate, KNOWN_OPERATORS } from "../../dist/src/institution_enforcement.js";
+
+/** Operators a predicate names that the evaluator does not implement. Textual, deliberately: the
+ *  point is to REPORT what an obligation asked for, not to decide it. */
+function missingOperators(predicate) {
+  const heads = String(predicate ?? "").match(/\(\s*([^\s()]+)/g) ?? [];
+  const named = heads.map((h) => h.replace(/^\(\s*/, ""));
+  // The evaluator's own set, imported rather than copied: a copy would keep naming an operator as
+  // missing after it was implemented, which is backwards for a field whose whole job is "build this
+  // one next". One home, two readers.
+  return [...new Set(named.filter((op) => !KNOWN_OPERATORS.has(op)))];
+}
+
+export default function run(input, context) {
+  const up = context && Array.isArray(context.upstream) ? context.upstream : [];
+  const laws = input?.laws ?? up.filter((u) => u?.domain_type === "bearing-law").map((u) => u.data) ?? [];
+  const snapshot = input?.facts ?? {};
+  const facts = snapshot.facts ?? snapshot;
+
+  const results = [];
+  for (const law of laws) {
+    const slug = String(law?.slug ?? law?.subject_ref ?? "(unnamed)");
+    const status = String(law?.status ?? "");
+    const check = law?.law?.check;
+    const debtor = law?.law?.debtor ?? law?.bearer;
+
+    if (status === "proposed") {
+      results.push({ obligation: slug, outcome: "not-in-force", why: "status is proposed; nothing is in force until it is executed" });
+      continue;
+    }
+    if (!check || !check.predicate) {
+      results.push({ obligation: slug, outcome: "unadjudicable", why: "the law carries no check — a clause the machine cannot decide is a person's" });
+      continue;
+    }
+    // An obligor does not certify its own discharge — and an UNATTRIBUTED snapshot cannot be shown
+    // not to come from the debtor, so absence declines rather than passes. A settlement resting on
+    // facts nobody stands behind is the case this rule exists for.
+    if (!snapshot.supplied_by) {
+      results.push({ obligation: slug, outcome: "refused", why: "the fact snapshot names no supplier; an unattributed snapshot cannot be shown not to come from the debtor" });
+      continue;
+    }
+    if (debtor && snapshot.supplied_by === debtor) {
+      results.push({ obligation: slug, outcome: "refused", why: `the fact snapshot was supplied by the debtor (${debtor}); an obligor does not certify its own discharge` });
+      continue;
+    }
+    const verdict = evaluate({ predicate: check.predicate, inputs: check.inputs ?? {} }, facts);
+    const missing = verdict === "UNDECIDED" ? missingOperators(check.predicate) : [];
+    results.push({
+      obligation: slug,
+      outcome: verdict,
+      why: verdict === "DEAD_NAME" ? "a declared input the snapshot does not supply" :
+           verdict === "UNDECIDED" ? (missing.length ? `operators the evaluator does not implement: ${missing.join(", ")}` : "the predicate could not be reduced from these facts") :
+           "decided from the snapshot",
+      needs_operators: missing,
+    });
+  }
+
+  const settled = results.filter((r) => r.outcome === "PERMIT" || r.outcome === "DENY");
+  const needs_person = results.filter((r) => !["PERMIT", "DENY", "not-in-force"].includes(r.outcome));
+  return {
+    id: "obligation-adjudication",
+    target_ref: String(input?.matter ?? "obligations"),
+    // An empty set is not a clean sweep: nothing adjudicated is nothing proved.
+    pass: results.length > 0 && needs_person.length === 0,
+    checks: results.length
+      ? results.map((r) => ({ method: "evaluate(check, fact-snapshot)", target_ref: r.obligation, result: `${r.outcome}: ${r.why}` }))
+      : [{ method: "evaluate(check, fact-snapshot)", target_ref: "none", result: "no obligations supplied" }],
+    results,
+    settled: settled.map((r) => r.obligation),
+    needs_person: needs_person.map((r) => r.obligation),
+    operators_wanted: [...new Set(results.flatMap((r) => r.needs_operators ?? []))],
+  };
+}