@cavelang/cli 0.27.3 → 0.29.0

package/dist/internal/act/declare.js

@@ -0,0 +1,270 @@
+/**
+ * Action lifecycle (spec §25.1) — declaring actions from a CAVE document,
+ * resolving and listing what a store currently believes its actions are,
+ * and retracting a declaration.
+ *
+ * An action file is an ordinary CAVE document: top-level
+ * `action/<name> HAS action: `…`` claims are the declarations; everything
+ * else — parameter docs (`action/<name>/<param> IS param`), hook
+ * references (`HAS hook:`), verb declarations, comments — is prelude,
+ * ingested first. Declaring is idempotent: an unchanged declaration (or
+ * prelude) appends nothing.
+ *
+ * Unlike rules, an action's identity is its *name*: the declaration
+ * evolves as one belief series per subject, and because a declaration may
+ * also be appended by other surfaces (`cave add`, an agent's `cave_add`),
+ * whose §9.5 stamps fork the series per actor, resolution takes the
+ * newest current row across every series of the subject — latest belief
+ * wins, whoever appended it.
+ */
+import { Claim, Key, Value } from '@cavelang/core';
+import { parseDocument } from '@cavelang/parser';
+import { Rule } from '@cavelang/cli/rules';
+import { Row } from '@cavelang/store';
+import * as Action from "./action.js";
+/** Source context stamped on declarations and bookkeeping (spec §9.5). */
+export const provenanceContext = 'src:cave-act';
+/** Subject of the prelude digest bookkeeping claim. */
+const preludeSubject = 'act/prelude';
+const preludeDigestAttribute = 'act-digest';
+const declarationKey = (subject, attribute) => Key.of(Claim.of({
+    subject: Claim.entity(subject),
+    verb: 'HAS',
+    payload: Claim.attribute(attribute, Value.parse('x')),
+    contexts: [provenanceContext]
+}));
+/**
+ * The newest current row of `attribute` on `subject`, across every
+ * belief series (§9.5 stamps make one series per appending actor).
+ * @returns the winner even when it is retracted or negated — callers
+ * decide whether a disabled declaration matters.
+ */
+export const currentAttribute = (store, subject, attribute) => {
+    let winner;
+    for (const row of store.currentBeliefs()) {
+        if (row.subject === subject && row.verb === 'HAS' && row.attribute === attribute &&
+            (winner === undefined || winner.tx < row.tx)) {
+            winner = row;
+        }
+    }
+    return winner;
+};
+const enabled = (row) => row !== undefined && row.conf > 0 && row.negated === 0 && row.value_text !== null;
+/** Current positive action declaration rows, newest series winner per subject. */
+const currentActionRows = (store) => {
+    const bySubject = new Map();
+    for (const row of store.currentBeliefs()) {
+        if (row.verb !== 'HAS' || row.attribute !== Action.actionAttribute ||
+            Action.actionName(row.subject) === undefined) {
+            continue;
+        }
+        const seen = bySubject.get(row.subject);
+        if (seen === undefined || seen.tx < row.tx) {
+            bySubject.set(row.subject, row);
+        }
+    }
+    return [...bySubject.values()].filter(enabled);
+};
+/**
+ * Resolves one action by name (or full subject) to its current
+ * declaration. @returns `undefined` when unknown, retracted, or negated;
+ * problems when the stored body does not parse.
+ */
+export const loadAction = (store, name) => {
+    const subject = Action.actionSubject(name);
+    const row = currentAttribute(store, subject, Action.actionAttribute);
+    if (!enabled(row)) {
+        return undefined;
+    }
+    const parsed = Action.parse(subject, Row.parseValue(row.value_text).raw);
+    if (!parsed.ok) {
+        return { problems: parsed.problems };
+    }
+    return {
+        loaded: {
+            action: parsed.action,
+            row,
+            ...row.comment === null ? {} : { description: row.comment }
+        },
+        problems: []
+    };
+};
+/** The hook name the action currently references, if any (§25.4). */
+export const currentHook = (store, subject) => {
+    const row = currentAttribute(store, subject, Action.hookAttribute);
+    return enabled(row) ? Row.parseValue(row.value_text).raw : undefined;
+};
+/** Parameter doc — the comment of `action/<name>/<param> IS param` (§25.1). */
+const paramDoc = (store, subject, param) => {
+    let winner;
+    for (const row of store.currentBeliefs()) {
+        if (row.subject === `${subject}/${param}` && row.verb === 'IS' && row.object === 'param' &&
+            row.negated === 0 && row.conf > 0 && (winner === undefined || winner.tx < row.tx)) {
+            winner = row;
+        }
+    }
+    return winner?.comment ?? undefined;
+};
+/** Current positive actions of a store, in declaration order. */
+export const listActions = (store) => currentActionRows(store).map(row => {
+    const text = Row.parseValue(row.value_text).raw;
+    const parsed = Action.parse(row.subject, text);
+    const params = parsed.ok ?
+        parsed.action.params.map(name => {
+            const doc = paramDoc(store, row.subject, name);
+            return { name, ...doc === undefined ? {} : { doc } };
+        }) :
+        [];
+    const hook = currentHook(store, row.subject);
+    return {
+        subject: row.subject,
+        name: Action.actionName(row.subject),
+        text,
+        ...row.comment === null ? {} : { description: row.comment },
+        params,
+        ...hook === undefined ? {} : { hook },
+        ok: parsed.ok,
+        problems: parsed.ok ? [] : parsed.problems
+    };
+});
+const indentOf = (line) => line.length - line.trimStart().length;
+const isStructural = (line) => {
+    const body = line.trim();
+    return body !== '' && !body.startsWith(';');
+};
+/**
+ * Reads one top-level line as an action declaration claim —
+ * `action/<name> HAS action: `…``. @returns `undefined` when the line is
+ * anything else (prelude).
+ */
+const asDeclaration = (line) => {
+    const document = parseDocument(line);
+    if (document.diagnostics.length > 0) {
+        return undefined;
+    }
+    const entry = document.lines.find(candidate => candidate.kind === 'claim');
+    if (entry === undefined || entry.kind !== 'claim') {
+        return undefined;
+    }
+    const claim = entry.claim;
+    if (claim.verb !== 'HAS' || claim.negated || claim.payload.kind !== 'attribute' ||
+        claim.payload.attribute !== Action.actionAttribute ||
+        claim.subject.kind !== 'entity' || Action.actionName(claim.subject.text) === undefined) {
+        return undefined;
+    }
+    return {
+        subject: claim.subject.text,
+        body: claim.payload.value.raw,
+        ...claim.meta.comment === undefined ? {} : { comment: claim.meta.comment }
+    };
+};
+/**
+ * Declares the actions of a CAVE document into the store — prelude
+ * first, then one normalized `action/<name> HAS action: …` claim per
+ * declaration (§25.1), each skipped when already current. Declarations
+ * re-emit in the normalized form; metadata beyond the description
+ * comment is not preserved — append exotic declarations with `cave add`.
+ */
+export const declareActions = (store, text) => {
+    const problems = [];
+    const actions = [];
+    const preludeLines = [];
+    const declarations = [];
+    // Top-level blocks: a structural unindented line plus what follows it.
+    // A declaration's structural children would silently re-attach to the
+    // preceding prelude line if the declaration were extracted alone, so a
+    // declaration block with children is rejected whole.
+    const blocks = [];
+    text.split(/\r?\n/).forEach((line, index) => {
+        if (isStructural(line) && indentOf(line) === 0) {
+            blocks.push({ lines: [line], at: index + 1 });
+        }
+        else if (blocks.length === 0) {
+            preludeLines.push(line);
+        }
+        else {
+            blocks[blocks.length - 1].lines.push(line);
+        }
+    });
+    for (const block of blocks) {
+        const declaration = asDeclaration(block.lines[0]);
+        if (declaration === undefined) {
+            preludeLines.push(...block.lines);
+            continue;
+        }
+        if (block.lines.slice(1).some(isStructural)) {
+            problems.push({ line: block.at, message: 'action declarations take no qualifier children (spec §25.1)' });
+            continue;
+        }
+        declarations.push({ declaration, at: block.at });
+        preludeLines.push(...block.lines.slice(1));
+    }
+    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-act' });
+                problems.push(...result.problems);
+                prelude = result.ids.length;
+                store.ingest(`${preludeSubject} HAS ${preludeDigestAttribute}: ${digest} @${provenanceContext}`);
+            }
+        }
+        let declared = 0;
+        let unchanged = 0;
+        for (const { declaration, at } of declarations) {
+            const parsed = Action.parse(declaration.subject, declaration.body);
+            if (!parsed.ok) {
+                problems.push(...parsed.problems.map(message => ({ line: at, message })));
+                continue;
+            }
+            const action = parsed.action;
+            actions.push(action);
+            const literal = !action.text.includes('`') ? `\`${action.text}\`` :
+                !action.text.includes('"') ? `"${action.text}"` :
+                    undefined;
+            if (literal === undefined) {
+                problems.push({ line: at, message: 'action body contains both " and ` — cannot be stored as a literal' });
+                continue;
+            }
+            const known = currentAttribute(store, action.subject, Action.actionAttribute);
+            if (enabled(known) && known.value_text === literal &&
+                (known.comment ?? undefined) === declaration.comment) {
+                unchanged += 1;
+                continue;
+            }
+            const description = declaration.comment === undefined ? '' : ` ; ${declaration.comment}`;
+            store.ingest(`${action.subject} HAS ${Action.actionAttribute}: ${literal} @${provenanceContext}${description}`);
+            declared += 1;
+        }
+        return { declared, unchanged, prelude, actions, problems };
+    });
+};
+/**
+ * Retracts an action's declaration — by name or subject — disabling it.
+ * Every current positive series of the declaration is retracted (§9.5
+ * stamps fork one per appending actor). Effects of past executions are
+ * recorded knowledge and stay untouched (spec §25.1; contrast §24.5).
+ */
+export const retractAction = (store, ref) => {
+    const subject = Action.actionSubject(ref);
+    const rows = store.currentBeliefs().filter(row => row.subject === subject && row.verb === 'HAS' && row.attribute === Action.actionAttribute &&
+        row.negated === 0 && row.conf > 0);
+    if (rows.length === 0) {
+        return { ok: false, error: `no current action matches ${JSON.stringify(ref)}` };
+    }
+    return store.transaction(() => {
+        for (const row of rows) {
+            store.insertResult({
+                claims: [{ claim: { ...store.toClaim(row), conf: 0, raw: '', comment: 'retracted: cave act --retract' }, line: 0 }],
+                edges: [],
+                registry: store.registry(),
+                problems: []
+            });
+        }
+        return { ok: true, subject, retracted: rows.length };
+    });
+};
+//# sourceMappingURL=declare.js.map

package/dist/internal/act/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/act/engine.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Action execution (spec §25.2–§25.4) — the governed write path.
+ *
+ * `act` resolves the named action's current declaration, validates the
+ * caller's arguments against its parameters, evaluates the premises over
+ * current beliefs with the parameters pre-bound (the §24.2 left-to-right
+ * join — a premise with no solution fails the action), and appends the
+ * instantiated effects atomically:
+ *
+ * - effect confidence is the template's own — an action is the caller's
+ *   assertion; premises are gates, not evidence (no noisy-AND, §25.2);
+ * - appended rows are stamped `@src:action/<name>` (§9.5) and linked
+ *   `BECAUSE` to the premise rows of the justifying solution and `VIA`
+ *   to the declaration row (§24.3's obligations);
+ * - execution is idempotent: an effect equal to its current belief
+ *   appends nothing;
+ * - the §20.3 shape gate runs by default — effects that introduce new
+ *   `EXPECTS` violations roll the whole execution back (§25.3);
+ * - after a commit that changed belief, a named-and-configured hook runs
+ *   as a shell command — placeholders shell-quoted, appended claims on
+ *   stdin, failures reported but never rolled back into the store
+ *   (§25.4).
+ */
+import { type Violation } from '@cavelang/cli/shape';
+import { type Store } from '@cavelang/store';
+export type ActOptions = {
+    /** Validate and report inside a rolled-back transaction; never fires hooks. */
+    readonly dryRun?: boolean;
+    /** Shape gate (spec §25.3) — on by default; `false` skips the `EXPECTS` re-check. */
+    readonly check?: boolean;
+    /** Premises match through the alias closure (spec §13.6). */
+    readonly aliases?: boolean;
+    /** Out-of-band hook command templates by name (spec §25.4). */
+    readonly hooks?: Readonly<Record<string, string>>;
+    /** Working directory for hook commands. */
+    readonly cwd?: string;
+    /** Hook wall-clock budget (default 600 s). */
+    readonly hookTimeoutSeconds?: number;
+};
+export declare const defaultHookTimeoutSeconds = 600;
+export type EffectOutcome = {
+    /** Canonical line of the instantiated effect. */
+    readonly line: string;
+    readonly outcome: 'appended' | 'updated' | 'unchanged';
+};
+export type HookOutcome = {
+    readonly name: string;
+    readonly fired: boolean;
+    /** Why the hook did not fire (`not configured`, `nothing changed`). */
+    readonly note?: string;
+    readonly code?: null | number;
+    /** Trailing stdout+stderr of the hook command. */
+    readonly output?: string;
+    readonly error?: string;
+};
+export type ActFailure = {
+    readonly ok: false;
+    readonly action: string;
+    readonly error: string;
+    /** The first premise that found no match, when that is the failure. */
+    readonly failedPremise?: string;
+    /** New `EXPECTS` violations, when the shape gate rejected (spec §25.3). */
+    readonly violations?: readonly Violation[];
+};
+export type ActSuccess = {
+    readonly ok: true;
+    readonly action: string;
+    readonly subject: string;
+    readonly dryRun: boolean;
+    /** Solutions of the premise join — 1 when there are no premises. */
+    readonly solutions: number;
+    readonly effects: readonly EffectOutcome[];
+    readonly appended: number;
+    readonly updated: number;
+    readonly unchanged: number;
+    readonly hook?: HookOutcome;
+};
+export type ActReport = ActFailure | ActSuccess;
+/**
+ * An untrusted recommendation from a solver or another planning system.
+ * Possessing a proposal grants no authority: `actProposal` resolves the
+ * current declaration and repeats ordinary parameter, premise, shape, and
+ * hook checks at execution time.
+ */
+export type ActionProposal = {
+    readonly action: string;
+    readonly parameters: Readonly<Record<string, unknown>>;
+};
+/** POSIX single-quoting — hook placeholders never splice raw (spec §25.4). */
+export declare const shellQuote: (value: string) => string;
+/**
+ * Substitutes `{action}` and `{<param>}` placeholders in one pass —
+ * substituted values are never re-scanned, unknown placeholders stay.
+ */
+export declare const substitute: (template: string, action: string, args: Readonly<Record<string, unknown>>) => string;
+/**
+ * Executes one action (spec §25.2). See the module doc for semantics;
+ * `dryRun` computes the same report inside a rolled-back transaction.
+ */
+export declare const act: (store: Store, name: string, args?: Readonly<Record<string, unknown>>, options?: ActOptions) => ActReport;
+/** Execute an untrusted proposal through the governed action boundary. */
+export declare const actProposal: (store: Store, proposal: ActionProposal, options?: ActOptions) => ActReport;
+//# sourceMappingURL=engine.d.ts.map

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

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