@cavelang/cli 0.27.14 → 0.29.0

package/dist/internal/rules/declare.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Rule lifecycle (spec §24.1) — declaring rules from a rule file,
+ * listing what a store believes its rules are, and retracting a rule
+ * together with everything it derived.
+ *
+ * A rule file is an ordinary CAVE document in which structural lines with
+ * a top-level `=>` are rules; everything else — verb declarations the
+ * rules need, comments, blanks — is prelude, ingested first so the rules
+ * fire against the vocabulary they assume. Declaring is idempotent: rule
+ * identity is the normalized-text digest, and an unchanged rule (or
+ * prelude) appends nothing.
+ */
+import { type Store } from '@cavelang/store';
+import * as Rule from './rule.ts';
+export type Declaration = {
+    /** Rules newly declared (or re-declared after retraction). */
+    readonly declared: number;
+    /** Rules whose declaration is already current — nothing appended. */
+    readonly unchanged: number;
+    /** Claims appended by the file's prelude (0 when unchanged). */
+    readonly prelude: number;
+    readonly rules: readonly Rule.t[];
+    readonly problems: readonly {
+        line: number;
+        message: string;
+    }[];
+};
+/**
+ * Declares the rules of a rule file into the store — prelude first, then
+ * one `rule/<digest> HAS rule: …` claim per rule (§24.1), each skipped
+ * when already current.
+ */
+export declare const declareRules: (store: Store, text: string) => Declaration;
+export type ListedRule = {
+    /** Declaration subject, conventionally `rule/<digest>`. */
+    readonly subject: string;
+    readonly text: string;
+    readonly label?: string;
+    readonly ok: boolean;
+    readonly problems: readonly string[];
+};
+/** Current positive rules of a store, in declaration order. */
+export declare const listRules: (store: Store) => ListedRule[];
+export type Retraction = {
+    readonly ok: true;
+    readonly subjects: readonly string[];
+    readonly derived: number;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Retracts a rule — by declaration subject, digest, or unambiguous digest
+ * prefix — together with every claim it derived (§24.5): a derivation's
+ * justification does not outlive its rule.
+ */
+export declare const retractRule: (store: Store, ref: string) => Retraction;
+//# sourceMappingURL=declare.d.ts.map

package/dist/internal/rules/declare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declare.d.ts","sourceRoot":"","sources":["../../src/declare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAO,KAAK,KAAK,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAkBjC,MAAM,MAAM,WAAW,GAAG;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC,CAAC,EAAE,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAChE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,KAAK,EAAE,MAAM,MAAM,KAAG,WAwDzD,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC,CAAA;AAED,+DAA+D;AAC/D,eAAO,MAAM,SAAS,GAAI,OAAO,KAAK,KAAG,UAAU,EAc7C,CAAA;AAEN,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAElD;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,KAAK,EAAE,KAAK,MAAM,KAAG,UA8CvD,CAAA"}

package/dist/internal/rules/declare.js

@@ -0,0 +1,152 @@
+/**
+ * Rule lifecycle (spec §24.1) — declaring rules from a rule file,
+ * listing what a store believes its rules are, and retracting a rule
+ * together with everything it derived.
+ *
+ * A rule file is an ordinary CAVE document in which structural lines with
+ * a top-level `=>` are rules; everything else — verb declarations the
+ * rules need, comments, blanks — is prelude, ingested first so the rules
+ * fire against the vocabulary they assume. Declaring is idempotent: rule
+ * identity is the normalized-text digest, and an unchanged rule (or
+ * prelude) appends nothing.
+ */
+import { Claim, Key, Value } from '@cavelang/core';
+import { Row } from '@cavelang/store';
+import * as Rule from "./rule.js";
+import { provenanceContext, ruleAttribute, ruleSubject } from "./engine.js";
+/** Subject of the prelude digest bookkeeping claim. */
+const preludeSubject = 'derive/prelude';
+const preludeDigestAttribute = 'derive-digest';
+const bookkeepingContexts = [provenanceContext];
+const declarationKey = (subject, attribute) => Key.of(Claim.of({
+    subject: Claim.entity(subject),
+    verb: 'HAS',
+    payload: Claim.attribute(attribute, Value.parse('x')),
+    contexts: bookkeepingContexts
+}));
+/**
+ * Declares the rules of a rule file into the store — prelude first, then
+ * one `rule/<digest> HAS rule: …` claim per rule (§24.1), each skipped
+ * when already current.
+ */
+export const declareRules = (store, text) => {
+    const problems = [];
+    const rules = [];
+    const preludeLines = [];
+    const ruleLines = [];
+    text.split(/\r?\n/).forEach((line, index) => {
+        if (Rule.isRuleLine(line)) {
+            ruleLines.push({ line, at: index + 1 });
+        }
+        else {
+            preludeLines.push(line);
+        }
+    });
+    return store.transaction(() => {
+        let prelude = 0;
+        const preludeText = preludeLines.join('\n');
+        if (preludeText.trim() !== '') {
+            const digest = Rule.digestOf(preludeText);
+            const known = store.currentBelief(declarationKey(preludeSubject, preludeDigestAttribute));
+            if (known === undefined || known.conf <= 0 || known.value_text !== digest) {
+                const result = store.ingest(preludeText, { source: 'cave-derive' });
+                problems.push(...result.problems);
+                prelude = result.ids.length;
+                store.ingest(`${preludeSubject} HAS ${preludeDigestAttribute}: ${digest} @${provenanceContext}`);
+            }
+        }
+        let declared = 0;
+        let unchanged = 0;
+        for (const { line, at } of ruleLines) {
+            const parsed = Rule.parse(line);
+            if (!parsed.ok) {
+                problems.push(...parsed.problems.map(message => ({ line: at, message })));
+                continue;
+            }
+            const rule = parsed.rule;
+            rules.push(rule);
+            const literal = !rule.text.includes('`') ? `\`${rule.text}\`` :
+                !rule.text.includes('"') ? `"${rule.text}"` :
+                    undefined;
+            if (literal === undefined) {
+                problems.push({ line: at, message: 'rule text contains both " and ` — cannot be stored as a literal' });
+                continue;
+            }
+            const known = store.currentBelief(declarationKey(ruleSubject(rule.digest), ruleAttribute));
+            if (known !== undefined && known.conf > 0 && known.value_text === literal) {
+                unchanged += 1;
+                continue;
+            }
+            const label = rule.label === undefined ? '' : ` ; ${rule.label}`;
+            store.ingest(`${ruleSubject(rule.digest)} HAS ${ruleAttribute}: ${literal} @${provenanceContext}${label}`);
+            declared += 1;
+        }
+        return { declared, unchanged, prelude, rules, problems };
+    });
+};
+/** Current positive rules of a store, in declaration order. */
+export const listRules = (store) => store.currentBeliefs()
+    .filter(row => row.verb === 'HAS' && row.attribute === ruleAttribute && row.negated === 0 && row.conf > 0 && row.value_text !== null)
+    .map(row => {
+    const text = Row.parseValue(row.value_text).raw;
+    const parsed = Rule.parse(text);
+    const label = (parsed.ok ? parsed.rule.label : undefined) ?? row.comment ?? undefined;
+    return {
+        subject: row.subject,
+        text,
+        ...label === undefined ? {} : { label },
+        ok: parsed.ok,
+        problems: parsed.ok ? [] : parsed.problems
+    };
+});
+/**
+ * Retracts a rule — by declaration subject, digest, or unambiguous digest
+ * prefix — together with every claim it derived (§24.5): a derivation's
+ * justification does not outlive its rule.
+ */
+export const retractRule = (store, ref) => {
+    const declarations = store.currentBeliefs().filter(row => row.verb === 'HAS' && row.attribute === ruleAttribute && row.negated === 0 && row.conf > 0);
+    const matches = declarations.filter(row => row.subject === ref || row.subject === ruleSubject(ref) ||
+        (ref.length >= 4 && row.subject.startsWith(ruleSubject(ref))));
+    const subjects = [...new Set(matches.map(row => row.subject))];
+    if (subjects.length === 0) {
+        return { ok: false, error: `no current rule matches ${JSON.stringify(ref)}` };
+    }
+    if (subjects.length > 1) {
+        return { ok: false, error: `${JSON.stringify(ref)} is ambiguous — matches ${subjects.join(', ')}` };
+    }
+    return store.transaction(() => {
+        let derived = 0;
+        for (const declaration of matches) {
+            store.insertResult({
+                claims: [{ claim: { ...store.toClaim(declaration), conf: 0, raw: '', comment: 'retracted: cave derive --retract' }, line: 0 }],
+                edges: [],
+                registry: store.registry(),
+                problems: []
+            });
+            const rows = store.byProvenance('run', declaration.subject);
+            const latest = new Map();
+            for (const row of rows) {
+                const seen = latest.get(row.claim_key);
+                if (seen === undefined || seen.tx < row.tx) {
+                    latest.set(row.claim_key, row);
+                }
+            }
+            for (const row of latest.values()) {
+                if (row.conf <= 0 || (row.verb === 'REVERSE' || row.verb === 'RENAMED-TO' ||
+                    (row.verb === 'IS' && row.object === 'verb'))) {
+                    continue;
+                }
+                store.insertResult({
+                    claims: [{ claim: { ...store.toClaim(row), conf: 0, raw: '', comment: 'retracted: rule retracted' }, line: 0 }],
+                    edges: [],
+                    registry: store.registry(),
+                    problems: []
+                });
+                derived += 1;
+            }
+        }
+        return { ok: true, subjects, derived };
+    });
+};
+//# sourceMappingURL=declare.js.map

package/dist/internal/rules/declare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declare.js","sourceRoot":"","sources":["../../src/declare.ts"],"names":[],"mappings":"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"}

package/dist/internal/rules/engine.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The forward-chaining derivation engine (spec §24.2–§24.5).
+ *
+ * Rules live in the store as ordinary claims (§24.1's declaration shape),
+ * so derived claims can point lineage edges at them:
+ *
+ * ```cave
+ * rule/9f30ac9be4dd HAS rule: `?x NEEDS ?y, ?y NEEDS ?z => ?x NEEDS ?z` @src:cave-derive
+ * ```
+ *
+ * `derive` fires every current positive rule over current beliefs and
+ * appends what follows:
+ *
+ * - premises join left-to-right, each partial binding specializing the
+ *   next pattern and running it through the ordinary CAVE-Q compiler —
+ *   inverse verbs, transitive hops and the alias closure come for free;
+ * - conclusion confidence is noisy-AND (`@cavelang/fusion`, the
+ *   independence assumption explicit): rule conf × Π premise-row confs;
+ *   several derivations of one conclusion keep the strongest (§24.2);
+ * - derived rows are stamped `@src:rule/<digest>` (§9.5) and linked
+ *   `BECAUSE` to their specific premise rows and `VIA` to the rule's
+ *   declaration row (§24.3);
+ * - re-runs are idempotent — a conclusion equal to current belief appends
+ *   nothing — and incremental by per-rule tx watermark claims: a rule
+ *   re-fires only when rows recorded since its watermark could extend a
+ *   premise match, and a watermark predating the rule's current
+ *   declaration row is stale — a re-declared rule fires from scratch
+ *   (§24.4);
+ * - support is recomputed on every firing: previously-derived claims the
+ *   rule no longer concludes are retracted `@ 0%`, and while a fired
+ *   rule's earlier derivations are being re-established they are invisible
+ *   to premise matching unless re-supported — so retracting a premise
+ *   retracts the whole dependent chain, mutually-supporting cycles
+ *   included (§24.5).
+ */
+import { Claim, Value } from '@cavelang/core';
+import { type Store } from '@cavelang/store';
+import { type Pattern } from '@cavelang/query';
+import * as Rule from './rule.ts';
+/** Attribute of rule declaration claims: `rule/<digest> HAS rule: …`. */
+export declare const ruleAttribute = "rule";
+/** Attribute of per-rule watermark claims (§24.4). */
+export declare const watermarkAttribute = "derive-watermark";
+/** Source context stamped on declarations and bookkeeping (like `src:cave-connect`). */
+export declare const provenanceContext = "src:cave-derive";
+/** Declaration subject of a rule: its digest under the `rule/` scope. */
+export declare const ruleSubject: (digest: string) => string;
+export type DeriveOptions = {
+    /** Ignore stored watermarks — re-fire every rule (§24.4). */
+    readonly full?: boolean;
+    /** Run everything inside a rolled-back transaction; report only. */
+    readonly dryRun?: boolean;
+    /** Premises match through the alias closure (spec §13.6). */
+    readonly aliases?: boolean;
+    /** Conclusions below this confidence are not asserted (default 0.05). */
+    readonly minConf?: number;
+    /** Fixpoint guard — maximum evaluation passes (default 20). */
+    readonly maxPasses?: number;
+};
+export declare const defaultMinConf = 0.05;
+export declare const defaultMaxPasses = 20;
+export type RuleOutcome = {
+    /** Declaration subject, conventionally `rule/<digest>`. */
+    readonly subject: string;
+    readonly digest: string;
+    readonly text: string;
+    readonly label?: string;
+    /** `false` when every pass skipped the rule — watermark said nothing new. */
+    fired: boolean;
+    evaluations: number;
+    /** Solutions of the rule's final evaluation. */
+    solutions: number;
+    /** Conclusions asserted for the first time (or re-asserted after retraction). */
+    appended: number;
+    /** Conclusions whose confidence or value changed — belief updates. */
+    updated: number;
+    /** Idempotent skips — conclusion equals current belief (§24.4). */
+    unchanged: number;
+    /** Previously-derived claims retracted — premises no longer hold (§24.5). */
+    retracted: number;
+    readonly problems: string[];
+};
+export type RuleProblem = {
+    readonly subject: string;
+    readonly problems: readonly string[];
+};
+export type DeriveReport = {
+    readonly rules: readonly RuleOutcome[];
+    /** Stored rule declarations that failed to parse — reported, skipped. */
+    readonly problems: readonly RuleProblem[];
+    /** Whether evaluation and destructive support reconciliation reached a fixpoint. */
+    readonly complete: boolean;
+    readonly passes: number;
+    readonly appended: number;
+    readonly updated: number;
+    readonly unchanged: number;
+    readonly retracted: number;
+    readonly notes: readonly string[];
+};
+/**
+ * Specializes a pattern under partial bindings: bound variables become
+ * terms, so each join step runs an ordinary CAVE-Q query. Shared with
+ * `@cavelang/cli/act`, whose premise evaluation is the same left-to-right
+ * join with parameters pre-bound (spec §25.2).
+ * @returns `undefined` when a verb variable is bound to a non-verb —
+ * no row can match.
+ */
+export declare const specialize: (pattern: Pattern.t, bindings: Readonly<Record<string, string>>) => undefined | Pattern.t;
+/** Evaluates a `?var op value` constraint against the variable's binding. */
+export declare const satisfies: (bound: undefined | string, op: Rule.ConstraintOp, literal: Value.t) => boolean;
+/**
+ * A bound value substituted into a conclusion term slot. Stored bindings
+ * are formatted (`"…"`/`` `…` `` literals keep their delimiters); bare
+ * text that would not re-tokenize as one term is wrapped as a text
+ * literal — except number/date values in payload position, which the
+ * pipeline classifies as metrics.
+ */
+export declare const boundTerm: (bound: string, position: "subject" | "payload") => Claim.Term;
+/**
+ * Fires the store's rules to fixpoint (§24.2). See the module doc for the
+ * semantics; `dryRun` computes the same report inside a rolled-back
+ * transaction.
+ */
+export declare const derive: (store: Store, options?: DeriveOptions) => DeriveReport;
+//# sourceMappingURL=engine.d.ts.map

package/dist/internal/rules/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/engine.ts"],"names":[],"mappings":"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"}