deepclause-pi 0.3.0 → 0.5.0

package/README.md

@@ -155,15 +155,15 @@ Give me a specification-grade diagram of src/report.dml
 
 Pi calls the always-active `dc_diagram` model tool, which:
 
-1. extracts a deterministic Mermaid seed from the DML in-process,
-2. has the active pi model rewrite it in the requested grade,
+1. extracts a deterministic Mermaid seed from the DML in-process (the specification seed adds a `LOGIC` section for decision predicates and a `RULES` section for fact tables),
+2. has the active pi model rewrite it in the requested grade, preserving the seed's conditions, thresholds and outcomes,
 3. validates each attempt (structural checks, plus the real Mermaid parser when Chrome is available),
 4. writes the sidecar under `.pi/deepclause/diagrams/`, rebuilds the self-contained offline `viewer.html`, and opens it.
 
 Grades:
 
-- **presentation** — about 8-12 nodes, plain language, headline numbers; for slides and overviews.
-- **specification** — function names, task/tool roles, post-conditions; for engineers.
+- **presentation** — about 8-12 nodes, plain language, headline numbers and the headline decision; for slides and overviews.
+- **specification** — function names, task/tool roles, post-conditions, plus the core decision logic: each decision predicate with its conditions, thresholds and outcomes, and the rule fact tables; for engineers.
 
 Selecting `both` produces both sidecars. The DML source may be anywhere (workspace-relative or absolute); only the generated viewer is confined to `.pi/deepclause/`. `dc_diagram` never executes the DML and needs no shell approval. Regenerating a grade replaces only that grade's sidecar (`<name>.presentation.mmd` / `<name>.specification.mmd`). The Mermaid bundle is vendored so the viewer works offline.
 

package/dist/config.d.ts

@@ -1,4 +1,17 @@
 export type ContextMode = "turn" | "branch" | "isolated";
+export interface JevJudgeConfig {
+    /** Whether the Jev (TypeSafe System One) backend may be used. */
+    enabled: boolean;
+    /** Model alias or pinned version passed to TypeSafe. */
+    model: string;
+    /** Environment variable holding the TypeSafe API key. */
+    apiKeyEnv: string;
+}
+export interface JudgmentConfig {
+    /** Default backend name: "llm", "jev", or a name registered by an extension. */
+    default: string;
+    jev: JevJudgeConfig;
+}
 export interface DeepClauseConfig {
     version: 1;
     contextMode: ContextMode;
@@ -7,7 +20,16 @@ export interface DeepClauseConfig {
     maxTokens: number;
     verbose: boolean;
     modelToolEnabled: boolean;
+    judgment: JudgmentConfig;
 }
 export declare const DEFAULT_CONFIG: DeepClauseConfig;
 export declare function loadConfig(path: string): Promise<DeepClauseConfig>;
 export declare function setModelToolEnabled(configPath: string, enabled: boolean): Promise<DeepClauseConfig>;
+export interface JudgeConfigPatch {
+    /** Default backend name ("llm" or "jev"). */
+    default?: string;
+    /** Partial update of the Jev backend settings. */
+    jev?: Partial<JevJudgeConfig>;
+}
+/** Merge a judgment patch into the workspace config, preserving every other field. */
+export declare function setJudgeConfig(configPath: string, patch: JudgeConfigPatch): Promise<DeepClauseConfig>;

package/dist/config.js

@@ -7,6 +7,10 @@ export const DEFAULT_CONFIG = {
     maxTokens: 16_384,
     verbose: false,
     modelToolEnabled: false,
+    judgment: {
+        default: "llm",
+        jev: { enabled: false, model: "jev-latest", apiKeyEnv: "TYPESAFE_API_KEY" },
+    },
 };
 const isContextMode = (value) => value === "turn" || value === "branch" || value === "isolated";
 export async function loadConfig(path) {
@@ -40,6 +44,40 @@ export async function loadConfig(path) {
         maxTokens: positiveInteger("maxTokens", DEFAULT_CONFIG.maxTokens),
         verbose: config.verbose === true,
         modelToolEnabled: config.modelToolEnabled === true,
+        judgment: parseJudgmentConfig(config.judgment),
+    };
+}
+function parseJudgmentConfig(value) {
+    if (value === undefined)
+        return DEFAULT_CONFIG.judgment;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("judgment must be a JSON object");
+    }
+    const judgment = value;
+    const defaultBackend = judgment.default ?? DEFAULT_CONFIG.judgment.default;
+    if (typeof defaultBackend !== "string" || !defaultBackend.trim()) {
+        throw new Error("judgment.default must be a non-empty backend name");
+    }
+    const jevValue = judgment.jev ?? {};
+    if (!jevValue || typeof jevValue !== "object" || Array.isArray(jevValue)) {
+        throw new Error("judgment.jev must be a JSON object");
+    }
+    const jev = jevValue;
+    const model = jev.model ?? DEFAULT_CONFIG.judgment.jev.model;
+    const apiKeyEnv = jev.apiKeyEnv ?? DEFAULT_CONFIG.judgment.jev.apiKeyEnv;
+    if (typeof model !== "string" || !model.trim()) {
+        throw new Error("judgment.jev.model must be a non-empty string");
+    }
+    if (typeof apiKeyEnv !== "string" || !apiKeyEnv.trim()) {
+        throw new Error("judgment.jev.apiKeyEnv must be a non-empty environment variable name");
+    }
+    return {
+        default: defaultBackend.trim(),
+        jev: {
+            enabled: jev.enabled === true,
+            model: model.trim(),
+            apiKeyEnv: apiKeyEnv.trim(),
+        },
     };
 }
 export async function setModelToolEnabled(configPath, enabled) {
@@ -57,3 +95,25 @@ export async function setModelToolEnabled(configPath, enabled) {
     await writeFile(configPath, `${JSON.stringify({ ...existing, modelToolEnabled: enabled }, null, 2)}\n`, "utf8");
     return loadConfig(configPath);
 }
+/** Merge a judgment patch into the workspace config, preserving every other field. */
+export async function setJudgeConfig(configPath, patch) {
+    let existing = {};
+    try {
+        const parsed = JSON.parse(await readFile(configPath, "utf8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+            existing = parsed;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw new Error(`Invalid DeepClause config: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const record = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    const nextJudgment = {
+        ...record(existing.judgment),
+        ...(patch.default !== undefined ? { default: patch.default } : {}),
+        jev: { ...record(record(existing.judgment).jev), ...(patch.jev ?? {}) },
+    };
+    await writeFile(configPath, `${JSON.stringify({ ...existing, judgment: nextJudgment }, null, 2)}\n`, "utf8");
+    return loadConfig(configPath);
+}

package/dist/diagram/extract.d.ts

@@ -1,5 +1,7 @@
 export interface RenderOptions {
     hideOutput?: boolean;
+    /** Include core decision-logic blocks and rule facts. Defaults to true. */
+    includeLogic?: boolean;
 }
 export declare function renderDml(file: string, src: string, opts?: RenderOptions): string;
 export declare function renderSequence(file: string, src: string): string;

package/dist/diagram/extract.js

@@ -325,7 +325,7 @@ function extractClauses(src) {
                 depth++;
             else if (")]}".includes(c))
                 depth--;
-            else if (c === "." && depth === 0 && /\s|$/.test(src.charAt(b + 1)))
+            else if (c === "." && depth === 0 && (b + 1 >= src.length || /\s/.test(src.charAt(b + 1))))
                 break;
         }
         if (!clauses.has(name))
@@ -376,6 +376,158 @@ function agenticPredicates(clauses) {
         visit(n, new Set());
     return agentic;
 }
+// ---------- core logic extraction --------------------------------------------
+const JUDGE_PREDICATES = new Set([
+    "judge", "choose", "rate", "verify", "probability", "holds", "with_judgment", "require_judgment",
+]);
+const MECHANICAL_HELPERS = new Set([
+    "dget", "get_dict", "num", "to_num", "present", "lower", "lower_string", "upper",
+    "state_text", "norm_sign", "as_list", "truthy", "falsy", "format", "trunc", "basename",
+]);
+const DECISION_RE = /(?:>=|=<|<|>|=:=|\bis\b|\bbetween\b|\bmod\b|\\\+)/;
+const AGGREGATE_RE = /\b(findall|forall|setof|bagof|aggregate_all|maplist)\b/;
+/** All `name(` tokens in a clause body, with strings and chars removed. */
+function headNamesIn(text) {
+    const bare = text
+        .replace(/"(?:[^"\\]|\\.)*"/g, '""')
+        .replace(/'(?:[^'\\]|\\.)*'/g, "''");
+    const names = [];
+    for (const m of bare.matchAll(/([a-z][a-zA-Z0-9_]*)\s*\(/g)) {
+        if (m[1])
+            names.push(m[1]);
+    }
+    return names;
+}
+function predicateArity(clauses) {
+    return splitTop(clauses[0]?.args ?? "", ",").filter(Boolean).length;
+}
+function isFactClauses(clauses) {
+    return clauses.every((clause) => !clause.body.trim());
+}
+/**
+ * A predicate carries core logic when it branches, applies thresholds or
+ * generators, or consults a semantic judgment. Mechanical plumbing helpers are
+ * excluded so the logic section stays about decisions, not string handling.
+ */
+function isDecisionPredicate(name, clauses) {
+    if (MECHANICAL_HELPERS.has(name))
+        return false;
+    if (clauses.length > 1)
+        return true;
+    const body = clauses[0]?.body ?? "";
+    if (!body.trim())
+        return false;
+    if (DECISION_RE.test(body))
+        return true;
+    if (AGGREGATE_RE.test(body))
+        return true;
+    for (const h of headNamesIn(body))
+        if (JUDGE_PREDICATES.has(h))
+            return true;
+    return false;
+}
+const escLabel = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "'");
+/** Join the summaries of a conjunction/disjunction into one readable line. */
+function summarizeBody(text, max = 96) {
+    const parts = splitGoals(text)
+        .map(({ goal }) => summarizeGoal(goal, max))
+        .filter(Boolean);
+    return [...new Set(parts)].slice(-2).join("; ");
+}
+/** One short, readable line for a single body goal. */
+function summarizeGoal(goal, max = 96) {
+    const g = stripOuterParens(goal).trim();
+    if (!g)
+        return "";
+    const br = parseArrow(g);
+    if (br) {
+        const then = summarizeBody(br.then, Math.max(24, max - 12));
+        const otherwise = br.else.trim() ? summarizeBody(br.else, Math.max(24, max - 12)) : "";
+        return `if ${trunc(br.cond.replace(/\s+/g, " "), max)} -> ${then || "…"}${otherwise ? ` ; else: ${otherwise}` : ""}`;
+    }
+    return summarizeSingle(g, max);
+}
+function summarizeSingle(g, max) {
+    const h = headName(g);
+    if (!h)
+        return trunc(g.replace(/\s+/g, " "), max);
+    if (["format", "write", "print", "output", "answer"].includes(h)) {
+        const s = firstString(g);
+        if (!s)
+            return `${h}(...)`;
+        const decision = /(?:decision|answer|verdict|conclusion):.*/i.exec(s);
+        return trunc(decision ? decision[0] : s, Math.max(max, 120));
+    }
+    if (JUDGE_PREDICATES.has(h)) {
+        const label = h === "require_judgment" ? "require calibrated" : h;
+        const s = firstString(g);
+        return s ? `${label}: ${trunc(s, Math.max(16, max - label.length - 2))}` : `${label}(...)`;
+    }
+    if (["findall", "forall", "setof", "bagof", "aggregate_all"].includes(h))
+        return `${h}(...)`;
+    const args = () => splitTop(g.slice(g.indexOf("(") + 1, g.lastIndexOf(")")), ",").map((p) => p.trim());
+    if (h === "get_dict")
+        return args()[0] || "get_dict";
+    if (h === "dget" || h === "num" || h === "to_num")
+        return args()[1] || h;
+    const inside = g.slice(g.indexOf("(") + 1, g.lastIndexOf(")")).replace(/\s+/g, " ").trim();
+    return inside ? `${h}(${trunc(inside, Math.max(12, max - h.length - 3))})` : h;
+}
+/** Render one clause as an escaped `<br/>`-joined list of its meaningful goals. */
+function describeClause(clause) {
+    if (!clause.body.trim())
+        return escLabel(trunc(clause.args.replace(/\s+/g, " "), 80));
+    const seen = new Set();
+    const lines = [];
+    for (const { goal } of splitGoals(clause.body)) {
+        const line = summarizeGoal(goal);
+        if (!line)
+            continue;
+        const escaped = escLabel(line);
+        if (seen.has(escaped))
+            continue;
+        seen.add(escaped);
+        lines.push(escaped);
+    }
+    return lines.join("<br/>");
+}
+function factSummary(name, clauses) {
+    const sample = clauses
+        .slice(0, 6)
+        .map((clause) => escLabel(trunc(clause.args.replace(/\s+/g, " "), 32)))
+        .join(" · ");
+    return `${name}/${predicateArity(clauses)} — ${clauses.length} facts: ${sample}${clauses.length > 6 ? " …" : ""}`;
+}
+/** Transitive closure of decision predicates and fact tables reachable from the flow. */
+function collectLogic(clauses, roots) {
+    const logic = new Map();
+    const facts = new Map();
+    const seen = new Set();
+    const visit = (name) => {
+        if (seen.has(name))
+            return;
+        seen.add(name);
+        const bodies = clauses.get(name);
+        if (!bodies)
+            return;
+        if (isFactClauses(bodies)) {
+            if (bodies.length >= 2)
+                facts.set(name, bodies);
+            return;
+        }
+        if (isDecisionPredicate(name, bodies))
+            logic.set(name, bodies);
+        for (const clause of bodies) {
+            for (const inner of headNamesIn(clause.body)) {
+                if (inner !== name && clauses.has(inner) && !BUILTIN.has(inner))
+                    visit(inner);
+            }
+        }
+    };
+    for (const root of roots)
+        visit(root);
+    return { logic, facts };
+}
 // ---------- rendering --------------------------------------------------------
 function parseArrow(goal) {
     const t = stripOuterParens(goal);
@@ -461,6 +613,9 @@ export function renderDml(file, src, opts = {}) {
         stack: [],
         sawAnswer: false,
         phaseOpen: false,
+        includeLogic: opts.includeLogic !== false,
+        logicNodes: new Map(),
+        factRefs: new Set(),
     };
     const nid = () => `n${++state.n}`;
     const node = (shape, label, klass) => {
@@ -469,6 +624,24 @@ export function renderDml(file, src, opts = {}) {
         return id;
     };
     const edge = (a, b, label) => state.lines.push(`  ${a} ${label ? `-->|${label}|` : "-->"} ${b}`);
+    /** Record user predicates referenced by a condition so their logic still gets a block. */
+    const registerLogicRefs = (text, nodeId) => {
+        for (const name of headNamesIn(text)) {
+            const bodies = clauses.get(name);
+            if (!bodies || BUILTIN.has(name) || name === "agent_main")
+                continue;
+            if (isFactClauses(bodies)) {
+                if (bodies.length >= 2)
+                    state.factRefs.add(name);
+                continue;
+            }
+            if (agentic.has(name))
+                continue;
+            const referenced = state.logicNodes.get(name) ?? [];
+            referenced.push(nodeId);
+            state.logicNodes.set(name, referenced);
+        }
+    };
     function renderGoals(goals, ctx = "", topLevel = false) {
         let entry = null;
         let exit = null;
@@ -506,6 +679,8 @@ export function renderDml(file, src, opts = {}) {
         const br = parseArrow(goal);
         if (br) {
             const d = node(["{", "}"], `if ${trunc(br.cond, 46)}`, "det");
+            if (state.includeLogic)
+                registerLogicRefs(br.cond, d);
             const t = renderGoals(splitGoals(br.then), ctx);
             const e = br.else.trim() ? renderGoals(splitGoals(br.else), ctx) : null;
             const merge = nid();
@@ -546,15 +721,25 @@ export function renderDml(file, src, opts = {}) {
         if (h && clauses.has(h)) {
             const bodies = clauses.get(h);
             const isFact = bodies.every((c) => !c.body.trim());
-            if (isFact)
+            if (isFact) {
+                if (bodies.length >= 2)
+                    state.factRefs.add(h);
                 return null;
+            }
             if (agentic.has(h) && !state.stack.includes(h)) {
                 state.stack.push(h);
                 const seg = renderGoals(splitGoals(bodies[0]?.body ?? ""), h);
                 state.stack.pop();
                 return seg.entry ? seg : null;
             }
-            return { entry: node(["[[", "]]"], `${h}()`, "det"), exit: null };
+            const label = state.includeLogic ? `${h}/${predicateArity(bodies)}` : `${h}()`;
+            const id = node(["[[", "]]"], label, "det");
+            if (state.includeLogic) {
+                const referenced = state.logicNodes.get(h) ?? [];
+                referenced.push(id);
+                state.logicNodes.set(h, referenced);
+            }
+            return { entry: id, exit: null };
         }
         return null;
     }
@@ -579,6 +764,41 @@ export function renderDml(file, src, opts = {}) {
         tools.forEach((t, i) => state.lines.push(`    tool${i}[["${t.name}(${trunc(t.args, 26)})"]]:::tool`));
         state.lines.push("  end");
     }
+    if (state.includeLogic) {
+        const { logic, facts } = collectLogic(clauses, [...state.logicNodes.keys(), ...state.factRefs]);
+        if (logic.size || facts.size) {
+            const edges = [];
+            if (logic.size) {
+                state.lines.push('  subgraph LOGIC["core decision logic"]');
+                state.lines.push("    direction TB");
+                let index = 0;
+                for (const [name, bodies] of logic) {
+                    const sg = `lg${++index}`;
+                    state.lines.push(`    subgraph ${sg}["${name}/${predicateArity(bodies)}"]`);
+                    state.lines.push("      direction TB");
+                    bodies.forEach((clause, ci) => {
+                        const description = describeClause(clause) || "(clause)";
+                        state.lines.push(`      ${sg}c${ci}["${ci + 1}) ${description}"]:::det`);
+                    });
+                    state.lines.push("    end");
+                    for (const nodeId of state.logicNodes.get(name) ?? []) {
+                        edges.push(`  ${nodeId} -.->|"core logic"| ${sg}`);
+                    }
+                }
+                state.lines.push("  end");
+            }
+            if (facts.size) {
+                state.lines.push('  subgraph RULES["rule facts"]');
+                state.lines.push("    direction LR");
+                let index = 0;
+                for (const [name, bodies] of facts) {
+                    state.lines.push(`    rf${++index}["${factSummary(name, bodies)}"]:::det`);
+                }
+                state.lines.push("  end");
+            }
+            state.lines.push(...edges);
+        }
+    }
     state.lines.push("  classDef start fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;", "  classDef terminal fill:#e3f2fd,stroke:#1565c0;", "  classDef llm fill:#fff8e1,stroke:#f9a825,stroke-width:2px;", "  classDef det fill:#eceff1,stroke:#546e7a;", "  classDef host fill:#f3e5f5,stroke:#6a1b9a;", "  classDef out fill:#fafafa,stroke:#bdbdbd;", "  classDef tool fill:#ede7f6,stroke:#4527a0;");
     return state.lines.join("\n");
 }

package/dist/diagram/grade.d.ts

@@ -1,7 +1,7 @@
 import type { CheckResult, MermaidView } from "./validate.js";
 export type DiagramGrade = "presentation" | "specification";
 export type RequestedGrade = DiagramGrade | "both";
-export declare const GRADE_SYSTEM_PROMPT = "You are a meticulous Mermaid v11 diagram editor. You output only valid Mermaid source, never wrapped in code fences, and you keep all facts accurate.";
+export declare const GRADE_SYSTEM_PROMPT = "You are a meticulous Mermaid v11 diagram editor. You output only valid Mermaid source, never wrapped in code fences, and you keep all facts and decision logic accurate. Never invent or drop a rule, threshold, or outcome.";
 export declare const GRADE_PROMPTS: Record<DiagramGrade, string>;
 /**
  * Map free-form user/tool wording onto a supported grade. Returns undefined when

package/dist/diagram/grade.js

@@ -1,7 +1,7 @@
-export const GRADE_SYSTEM_PROMPT = "You are a meticulous Mermaid v11 diagram editor. You output only valid Mermaid source, never wrapped in code fences, and you keep all facts accurate.";
+export const GRADE_SYSTEM_PROMPT = "You are a meticulous Mermaid v11 diagram editor. You output only valid Mermaid source, never wrapped in code fences, and you keep all facts and decision logic accurate. Never invent or drop a rule, threshold, or outcome.";
 export const GRADE_PROMPTS = {
-    presentation: "Produce a PRESENTATION-GRADE version: about 8-12 nodes, plain non-technical language, NO function names or framework jargon, highlight the headline numbers and the main steps, and add 1-2 short callouts. Keep it accurate but simple enough for a general audience.",
-    specification: "Produce a SPECIFICATION-GRADE (detailed engineering) version: keep the technical detail (function names, task/tool roles, post-conditions, seed data), but improve labels, grouping and readability so an engineer can follow it precisely.",
+    presentation: "Produce a PRESENTATION-GRADE version: about 8-12 nodes, plain non-technical language, NO function names or framework jargon, highlight the headline numbers, the main steps and the headline decision, and add 1-2 short callouts. Keep it accurate but simple enough for a general audience; you may compress the detailed logic but must not change the final decision or omit a rule that flips it.",
+    specification: "Produce a SPECIFICATION-GRADE (detailed engineering) version: keep the technical detail (function names, task/tool roles, post-conditions, seed data) AND the domain decision logic. Preserve the decision predicates from the seed's `LOGIC` section — each with its exact conditions, thresholds and outcomes — and every `RULES` fact table. You may group or collapse pure arithmetic, date and formatting helpers, but never drop or alter a domain rule, threshold or outcome. Expand each retained logic block from the DML source. Improve labels, grouping and readability so an engineer can trace every domain decision precisely.",
 };
 /**
  * Map free-form user/tool wording onto a supported grade. Returns undefined when
@@ -29,7 +29,7 @@ function buildPrompt(grade, view, source, seed, feedback) {
     return [
         GRADE_PROMPTS[grade],
         "",
-        `Rules: output ONLY Mermaid v11 source (no code fences); keep it a '${syntax}' diagram; keep the facts accurate; do not use reserved words such as 'end' as node ids or class names.`,
+        `Rules: output ONLY Mermaid v11 source (no code fences); keep it a '${syntax}' diagram; keep the facts and decision logic accurate; preserve the seed's domain LOGIC blocks (conditions, thresholds, outcomes) and RULES facts instead of collapsing them into generic nodes, while grouping pure arithmetic/date/format helpers; do not use reserved words such as 'end' as node ids or class names.`,
         "",
         "DML source:",
         source,

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export interface ParsedRun {
     contextMode?: ContextMode;
     verbose: boolean;
     debug: boolean;
+    judge?: string;
 }
 interface ParsedPlan {
     request: string;
@@ -22,5 +23,14 @@ export declare function parsePlan(input: string): ParsedPlan;
  * A clean tree is what lets the next /dc-apply take a rollback snapshot.
  */
 export declare function offerCommit(pi: ExtensionAPI, ctx: ExtensionContext, action: string, change: string): Promise<void>;
+/**
+ * Ask the user a DeepClause question.
+ *
+ * Pi's interactive text-input dialog renders only its title: the placeholder
+ * argument is ignored by `ExtensionInputComponent`. Passing the question as the
+ * placeholder (as the extension used to) made it invisible, so put the whole
+ * question in the title and label which run is asking.
+ */
+export declare function requestDeepClauseInput(ctx: Pick<ExtensionContext, "ui">, label: string, prompt: string, signal: AbortSignal): Promise<string | undefined>;
 export default function deepClauseExtension(pi: ExtensionAPI): void;
 export {};