@cavelang/cli 0.27.14 → 0.29.0

package/Authors.md

@@ -0,0 +1,5 @@
+# Authors
+
+By adding their name to this file, all listed authors confirm they have copyright over their contributions to this project and are waiving these rights, placing their work in the public domain in accordance with the CC0 1.0 Universal Public Domain Dedication.
+
+- Mirek Rusin (Switzerland)

package/License.md

@@ -0,0 +1,6 @@
+# CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
+
+To the extent possible under law, the authors listed in [Authors.md](./Authors.md) have waived all copyright and related or neighboring rights to this software and associated documentation files (the "Software").
+
+For more information, please see:
+https://creativecommons.org/publicdomain/zero/1.0/

package/README.md

@@ -1,7 +1,7 @@
 # @cavelang/cli
 
 The `cave` command — the whole stack behind one binary. Runs directly from
-TypeScript sources via Node's type stripping; no build step.
+TypeScript sources in the workspace; npm releases contain emitted JavaScript.
 
 ```
 $ echo 'auth USES jwt @ 90%' | pnpm exec cave parse
@@ -15,60 +15,158 @@ $ pnpm exec cave query --db knowledge.db '?x USES jwt'
 ?x = api/gateway
 
 $ pnpm exec cave query --db knowledge.db '?cause CAUSE app/crash' 'WHERE conf >= 0.7'
-$ pnpm exec cave export --db knowledge.db --current
+$ pnpm exec cave export --db knowledge.db --current --max-sensitivity internal
 $ pnpm exec cave demo
 ```
 
+## Programmatic feature subpaths
+
+The package manifest is the entry-point registry. Every published entry point
+is documented here and follows the CLI package's semantic-versioning promise:
+
+| Entry point | Contract |
+|---|---|
+| `@cavelang/cli` | Buffered command functions plus the shared dispatcher and command registry. |
+| `@cavelang/cli/main` | Executable process entry point; prefer the `cave` binary from package scripts. |
+| `@cavelang/cli/act` | Action declarations and governed execution. |
+| `@cavelang/cli/automate` | Event-driven automation declarations and settling. |
+| `@cavelang/cli/connect` | Deterministic structured-source ingestion. |
+| `@cavelang/cli/eval` | Golden-fixture extraction and reconstruction evaluation. |
+| `@cavelang/cli/ingest` | LLM-driven document ingestion. |
+| `@cavelang/cli/loop` | Active memory reconstruction. |
+| `@cavelang/cli/mcp` | MCP tools, scopes, and stdio server. |
+| `@cavelang/cli/rules` | Rule declarations and forward chaining. |
+| `@cavelang/cli/shape` | Expectations, health checks, and typed-client generation. |
+| `@cavelang/cli/sync` | Store synchronization and annotated interchange. |
+| `@cavelang/cli/view` | Read-only view models, HTTP serving, and cited reports. |
+
+For example:
+
+```ts
+import { declareRules, derive } from '@cavelang/cli/rules'
+import { createServer } from '@cavelang/cli/mcp'
+```
+
+The source modules remain separate private workspace packages for focused
+ownership and tests. See [the package migration table](../../PACKAGE_SURFACES.md)
+when updating an import from a former standalone package name.
+
 ## Commands
 
+### JSON compatibility
+
+JSON that contains claims is storage-independent and versioned. `cave query
+--json` emits a `cave.query-page/v1` object whose `matches` are
+`cave.query-match/v1` objects and whose `claim` and `support` members are
+`cave.claim/v1`; its optional `next` value is an opaque continuation. Resolve,
+rule, action, and health JSON
+replace any nested database rows with the same claim record and never expose
+`claim_key`, `raw_line`, or `value_text` columns. New optional fields may be
+added within a version; incompatible shape changes require a new version.
+
+`cave parse --json` is the parser AST/debug surface, not a persisted claim
+record. `cave export` remains canonical CAVE text (with optional `;@` identity
+annotations), which is the language interchange contract rather than JSON.
+
 Every command answers `--help` with its options and examples (also
 `cave help <command>`). `--db` is optional everywhere: it defaults to
 `$CAVE_DB`, or `cave.db` in the current directory.
 
+All commands—synchronous, asynchronous, and long-running—enter through one
+promise-based dispatcher. It owns argument-exception formatting, stdout and
+stderr routing, exit codes, and SIGINT/SIGTERM propagation. Servers, watchers,
+timers, protocol readers, and stores finish their cleanup before a signal exit
+is reported. Unexpected errors are one-line and stack-free by default; set
+`CAVE_DEBUG=1` to include the diagnostic stack.
+
 | Command | Flags | Behavior |
 |---|---|---|
 | `parse [file…]` | `--json` | Lint (stdin by default). Exit 1 when diagnostics exist; `--json` dumps the AST document. |
 | `highlight [file…]` | | ANSI syntax colors from the tree-sitter grammar's own highlight query (see [`@cavelang/highlight`](../highlight)); `cave export` colors the same way on a terminal. |
 | `add [--db p] [file…]` | `--strict`, `--check`, `--no-prelude`, `--no-src` | Ingest. Lenient by default (problems on stderr, valid lines land); `--strict` rolls back on any problem; `--check` is the shape gate (spec §20.3) — the append rolls back if it introduces new expectation violations; `--no-prelude` starts from an empty registry instead of the standard §5.5 pairs. Claims without a `@src:` context are stamped `@src:cli` (spec §9.5); `--no-src` opts out. |
 | `import [--db p] [file…]` | `--strict`, `--no-prelude` | Restore/merge a database from CAVE text — `add` minus provenance stamping, because canonical text *is* the interchange format and replayed claims must keep their exported claim keys (spec §9.5). |
-| `query [--db p] <pattern…>` | `--json`, `--all`, `--aliases`, `--as-of <t>`, `--resolve`, `--no-prelude` | CAVE-Q. Extra positionals join as lines, so `WHERE` filters ride as separate arguments. Bindings print as `?x = value`; fully bound patterns print the matched raw line (or the pattern itself for transitive matches, which carry no row). `--aliases` widens matching through the §13.6 closure; `--as-of <t>` reconstructs belief at a past date/timestamp/tx (spec §12.3); `--resolve` matches only the winners the §26 resolution policy picks among contested facts (incompatible with `--all`). `--no-prelude` aligns the read-time registry with a store written via `add --no-prelude`. |
+| `query [--db p] <pattern…>` | `--json`, `--limit <n>`, `--cursor <t>`, `--all`, `--aliases`, `--as-of <t>`, `--at <t>`, `--resolve`, `--no-prelude` | Bounded CAVE-Q page (100 matches by default, maximum 1,000). Extra positionals join as lines, so `WHERE` filters ride as separate arguments. Bindings print as `?x = value`; fully bound patterns print the matched raw line (or the pattern itself for transitive matches, which carry no row). Human output ends with `next: <token>` when another page exists; pass it to `--cursor` to continue the first page's frozen transaction snapshot. `--aliases` widens matching through the §13.6 closure; `--as-of <t>` reconstructs belief at a past date/timestamp/tx (spec §12.3); `--at <t>` selects valid-time claims and interpolates trajectories (spec §32.4); `--resolve` matches only the winners the §26 resolution policy picks among contested facts (incompatible with `--all`). `--no-prelude` aligns the read-time registry with a store written via `add --no-prelude`. |
 | `resolve [--db p]` | `--aliases`, `--policy`, `--json`, `--no-prelude` | Contested facts under the §26 resolution policy: every fact more than one belief series speaks about, candidates ranked (precedence class, reliability-weighted confidence, tx) with the winner first — what `query --resolve` would match. `--policy` prints the effective policy instead: the built-in precedence ladder merged with in-band `source/<name> HAS precedence:` / `HAS reliability:` declarations. |
 | `derive [--db p] [rules.cave…]` | `--dry-run`, `--full`, `--aliases`, `--min-conf <p>`, `--max-passes <n>`, `--list`, `--retract <r>`, `--json`, `--no-prelude` | Declare and fire rules (spec §24, see [`@cavelang/rules`](../rules)): `premises => conclusion` forward chaining over current beliefs, `BECAUSE`/`VIA` lineage, watermark-incremental and idempotent; retracts conclusions whose premises no longer hold. |
 | `act [--db p] <name> [p=v…]` | `--declare`, `--list`, `--retract <n>`, `--dry-run`, `--no-check`, `--aliases`, `--hooks <file>`, `--json`, `--no-prelude` | Execute an action template (spec §25, see [`@cavelang/act`](../act)): validate parameters, check CAVE-Q preconditions against current belief, append effects atomically with lineage inside the §20.3 shape gate; out-of-band hooks fire after commit. |
-| `automate [--db p]` | see `cave automate --help` | The event-driven loop (spec §29, see [`@cavelang/automate`](../automate)): in-band `automation/<name>` trigger patterns over new claims fire rules, actions, out-of-band hooks and agent prompts; `--once` for cron, `--declare`/`--list`/`--retract` for the lifecycle; the daemon polls `MAX(tx)` and settles on change. |
+| `automate [--db p]` | `--once`, `--declare`, `--list`, `--retract <n>`, `--hooks <file>`, `--agent <template>`, `--json`, `--no-prelude` | The event-driven loop (spec §29, see [`@cavelang/automate`](../automate)): in-band `automation/<name>` trigger patterns over new claims fire rules, actions, out-of-band hooks and agent prompts; `--once` for cron, `--declare`/`--list`/`--retract` for the lifecycle; the daemon polls `MAX(tx)` and settles on change. |
 | `check [--db p]` | `--stale <days>`, `--json`, `--no-prelude` | Knowledge health report (spec §20, see [`@cavelang/shape`](../shape)): shape violations against in-band `EXPECTS` declarations, stale current beliefs (default horizon 90 days), review candidates (conf 0.3–0.7), alias disagreements, coverage stats. Exit 1 on violations; everything else is advisory. |
+| `backup [--db p] --out <file>` | `--force`; `--verify <file>`, `--sha256 <hex>` | Create an online, exact SQLite snapshot with `VACUUM INTO`, verify it, and publish atomically; or verify a prior snapshot (spec §13.2.2). |
+| `restore <snapshot> --db <path>` | `--force`, `--sha256 <hex>` | Verify and atomically restore exact snapshot bytes; refuses active/stale WAL, SHM, and rollback-journal sidecars (spec §13.2.2). |
+| `generate [--db p]` | `--out <file>`, `--version <n>`, `--no-prelude` | Deterministic versioned TypeScript interfaces and store-backed readers from current `EXPECTS` claims (spec §20.4, see [`@cavelang/shape`](../shape)); embeds normalized schema and SHA-256, fails on ambiguous/unsupported expectations before writing. |
 | `suggest-alias [--db p]` | `--min <s>`, `--limit <n>`, `--agent <template>`, `--timeout <s>`, `--write`, `--json`, `--no-prelude` | Alias discovery (spec §27, see [`@cavelang/shape`](../shape)): same-entity candidates from string/graph similarity as suggested `ALIAS` claims at review-band confidence (0.3–0.5). Prints pipeable CAVE text; `--write` appends stamped `@src:suggest/alias`; `--agent` runs an LLM judge over the candidates (the ingest/eval shell contract). Pairs with any recorded `ALIAS` history are never re-suggested. |
 | `sync [--db p] <source>` | `--as <label>`, `--into <label>`, `--dry-run`, `--no-record`, `--json`, `--no-prelude` | Store merge (spec §28, see [`@cavelang/sync`](../sync)): another CAVE store file — or `;@`-annotated canonical text, `-` for stdin — merges by row identity; present rows skip, re-runs merge nothing, effective merges append a `SYNCED-INTO` record (`--no-record` for checkouts, spec §28.6). |
-| `export [--db p]` | `--out <file>`, `--current`, `--tx`, `--no-prelude` | Canonical CAVE text — all rows in tx order, or current beliefs only. `--tx` precedes every claim line with its `;@` transaction annotation (spec §28.4), so the text carries row identity: the committed, reviewable store text of the §28.6 branching convention. Stdout by default; `--out` writes a file and reports the claim count. |
-| `serve [--db p]` | `--port <n>`, `--host <a>`, `--no-prelude` | The human read surface (spec §30, see [`@cavelang/view`](../view)): one static, self-contained page over the store — §20.2 coverage/frontier dashboard, entity 360, topic browse, belief-history timelines, `BECAUSE`/`VIA` lineage trees, FTS search. Strictly read-only (GET only), localhost by default, every request reads the live store. |
-| `mcp [--db p]` | `--read-only`, `--tools <list>`, `--no-prelude`, `--src <ctx>`, `--no-src` | Serve the engine as an MCP server on stdio (see [`@cavelang/mcp`](../mcp)) — tools for add/query/fuse/search/about/neighbors/reconstruct/derive/export/lint, with the §22 spec card as server instructions. `--read-only` / `--tools <list>` narrow the served tool surface (the agent permission boundary), composing by intersection. Appends are stamped `@src:agent/<client-name>` (spec §9.5); `--src` replaces the stamp, `--no-src` disables it. |
-| `ingest [--db p] <globs/urls…>` | see `cave ingest --help` | LLM-driven ingestion of files and web pages (fetched and readability-extracted) through any headless agent (see [`@cavelang/ingest`](../ingest)): batching, instructions markdown, hybrid knowledge context, MCP or stdout agents, incremental digests, `--plan` NDJSON for SDK drivers. |
-| `eval <suite…>` | see `cave eval --help` | Golden-fixture extraction/query evals (ROADMAP item 9, see [`@cavelang/eval`](../eval)): N fresh-store runs against any agent, claim-key + value scoring with §9.5 actor-stamp normalization, CAVE-Q expectations, optional LLM judge, `--min` CI gate. |
-| `connect <source>` | see `cave connect --help` | Deterministic structured ingestion (spec §23, see [`@cavelang/connect`](../connect)): CSV/TSV/JSON/JSONL/SQLite/URL records through `?field` mapping templates, per-record digests, `--watch`, `--prune`, query-time `--query` overlay. |
-| `reconstruct [--db p] <seed…>` | `--query <text>`, `--agent <template>`, `--steps <n>`, `--claims <n>`, `--timeout <s>`, `--trace`, `--no-prelude` | Active memory reconstruction from seed cues (spec §18, see [`@cavelang/loop`](../loop)): best-first traversal collecting related claims as canonical CAVE text; the heuristic policy by default, an LLM select/stop policy with `--agent` (ROADMAP item 10). |
+| `export [--db p]` | `--out <file>`, `--current`, `--tx`, `--max-sensitivity <level>`, `--no-prelude` | Sensitivity-scoped canonical CAVE text (spec §9.7) — default maximum `internal`; select `restricted` for complete portable history or a replica. `--current` compacts but never sanitizes permanent history (§9.6). `--tx` precedes every claim line with its `;@` transaction annotation (spec §28.4). Stdout by default; `--out` writes a file and reports the claim count. |
+| `report [--db p] [template…]` | `--out <file>`, `--aliases`, `--resolve`, `--as-of <t>`, `--at <t>`, `--max-sensitivity <level>`, `--no-prelude` | Render sensitivity-scoped cited Markdown from fenced and inline CAVE-Q templates (spec §9.7, §31, see [`@cavelang/view`](../view)). Every query uses the same audience, alias, resolution, transaction-time, and valid-time snapshot options. |
+| `serve [--db p]` | `--port <n>`, `--host <a>`, `--max-sensitivity <level>`, `--no-prelude` | The sensitivity-scoped human read surface (spec §9.7, §30, see [`@cavelang/view`](../view)): one static page whose counts, aliases, history, lineage, and search are computed only from visible rows. Strictly read-only (GET only), localhost by default. |
+| `mcp [--db p]` | `--read-only`, `--permissions <list>`, `--tools <list>`, `--hooks <file>`, `--no-prelude`, `--src <ctx>`, `--no-src` | Serve the engine as an MCP server on stdio (see [`@cavelang/mcp`](../mcp)) — static tools for add/query/fuse/search/about/neighbors/reconstruct/derive/export/lint plus one generated `act_<name>` tool per current action. Permission classes separate `read`, ephemeral `evaluate`, durable `record`, and effect-capable `action`; `--read-only` keeps only read/evaluate. Permission, tool, and read-only scopes intersect. `--hooks` supplies reviewed out-of-band commands for action tools. Appends are stamped `@src:agent/<client-name>` (spec §9.5); `--src` replaces the stamp, `--no-src` disables it. |
+| `ingest [--db p] <globs/urls…>` | `--agent <template>`, `--stdout`, `--lenient`, `--plan`, `--dry-run`, `--json`, `--no-prelude` | LLM-driven ingestion of files and web pages (fetched and readability-extracted) through any headless agent (see [`@cavelang/ingest`](../ingest)): strict atomic staging by default; explicit lenient partial progress with a complete per-source manifest; isolated URL outcomes classified as retryable network/HTTP or permanent HTTP failures; batching, hybrid context, MCP or stdout agents, incremental retry digests, and `--plan` NDJSON for SDK drivers. |
+| `eval <suite…>` | `--agent <template>`, `--judge <template>`, `--runs <n>`, `--stdout`, `--min <p>`, `--json`, `--no-prelude` | Golden-fixture extraction/query evals (see [`@cavelang/eval`](../eval)): N fresh-store runs against any agent, claim-key + value scoring with §9.5 actor-stamp normalization, CAVE-Q expectations, optional LLM judge, `--min` CI gate. |
+| `connect <source>` | `--map <file>`, `--key <field>`, `--watch`, `--prune`, `--query <pattern>`, `--dry-run`, `--no-prelude` | Deterministic structured ingestion (spec §9.8, §23, see [`@cavelang/connect`](../connect)): CSV/TSV/JSON/JSONL/SQLite/URL records through `?field` templates, physical source identity and CSV/TSV/JSONL line spans, per-record digests, `--watch`, `--prune`, query-time overlay. |
+| `reconstruct [--db p] <seed…>` | `--query <text>`, `--agent <template>`, `--steps <n>`, `--claims <n>`, `--timeout <s>`, `--trace`, `--no-prelude` | Active memory reconstruction from seed cues (spec §18, see [`@cavelang/loop`](../loop)): best-first traversal collecting related claims as canonical CAVE text; the heuristic policy by default, an LLM select/stop policy with `--agent`. |
+| `doctor [--db p]` | `--hooks <file>`, `--json` | Read-only runtime, package-layout, configuration, and store-health diagnostics. Missing optional configuration is advisory; unsupported runtimes, broken assets, malformed configured hooks, and unreadable or corrupt stores fail. Reports identify configuration sources but never expose paths, hook content, URLs, or environment values, so both human and `cave.doctor/v1` JSON output are safe to share. |
 | `demo` | | The cave-loop multi-hop recovery demo (§18). |
 | `version` | | Print the cave version. |
 | `help [command]` | | The overview, or one command's options and examples. |
 
-## Text backup / interchange
+All query-time arguments share one UTC parser. For example,
+`--at 2026-07-02T12:00:00` and `--at 2026-07-02T12:00:00Z` select the same
+instant on every host; explicit numeric offsets such as `+02:00` are honored.
+The same rule applies to `--as-of` and CAVE-Q `WHERE tx` timestamps.
+
+Shape declarations may add `#cardinality:one` or an attribute
+`#unit:<unit>` tag. `cave check` reports the observed count and normalized
+units when those constraints fail; declarations without either tag keep the
+compatible one-or-more presence check.
+
+## Exact backup and portable interchange
 
+For row identity, transaction time, provenance, lineage, and full history:
+
+```sh
+cave backup --db knowledge.db --out knowledge.snapshot.db
+cave backup --verify knowledge.snapshot.db --sha256 <recorded-hex>
+cave restore knowledge.snapshot.db --db restored.db --sha256 <recorded-hex>
 ```
-$ cave export --db knowledge.db --out backup.cave
+
+Backup is an online, consistent SQLite snapshot safe with WAL and concurrent
+readers/writers. CAVE verifies and atomically publishes it. Stop all users of
+the destination before restore; a WAL/SHM/journal sidecar makes restore refuse rather
+than guess. Failed creation or restore leaves the previous destination intact.
+
+For portable, reviewable CAVE text:
+
+```
+$ cave export --db knowledge.db --max-sensitivity restricted --out backup.cave
 exported 812 claim(s) to backup.cave
 
 $ cave import --db restored.db backup.cave
 added 812 claim(s), 37 edge(s)
 ```
 
-The text round trip preserves every claim with its metadata, the **full
-belief-series order** (rows export in tx order and re-ingest with fresh
-monotonic tx ids, so latest-tx-wins resolution is unchanged),
+With the explicit `restricted` ceiling, the text round trip preserves every
+claim with its metadata and the **belief-series order** (rows export in tx
+order and re-ingest with fresh monotonic tx ids, so latest-tx-wins resolution
+is unchanged),
 qualifier/grouping edges, and in-band registry declarations (`REVERSE`,
-`X IS verb`) — a restored database answers queries identically, inverse
-reads included. Original transaction timestamps are re-minted: canonical
-CAVE text carries no transaction identity. Use `--current` for a compact
-backup of current beliefs only (history intentionally dropped).
-
-Everything is testable without spawning: each command is a pure function
-`(argv) → { code, out, err }` (`@cavelang/cli` exports them), and `main.ts` is
-a four-line dispatcher. Tests cover both layers.
+`RENAMED-TO`, `X IS verb`) — a restored database answers current-belief and
+graph queries equivalently, including inverse and lifecycle spellings. Original
+transaction timestamps are re-minted: canonical CAVE text carries no transaction
+identity, so original as-of boundaries and staleness are not preserved. Use
+`--current` for a compact
+view of current beliefs only (history intentionally omitted from that
+view). Lower ceilings use the order `public < internal < confidential <
+restricted`; unlabeled rows are `internal`, while malformed or unknown labels
+fail closed as `restricted`. Filtering is not a sanitization tool: current
+claim text and every other
+database, export, sync peer, backup, snapshot, or clone may still retain
+sensitive content. CAVE has no claim-level redact command (§9.6); after an
+accidental secret ingest, rotate it, stop sync, rebuild a reviewed safe store,
+then explicitly destroy or expire every affected copy with the relevant
+storage provider's confirmation.
+
+Everything is testable without spawning: individual buffered commands expose
+`(argv) → { code, out, err }`, while `dispatch(argv, runtime)` exercises the
+same awaited path as the binary with injectable streams and an abort signal.
+`main.ts` only hands process arguments to `runCli` and assigns its final exit
+code.

package/dist/internal/act/action.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Action parsing (spec §25.1) — the §24.1 rule line put in the caller's
+ * hands:
+ *
+ * ```cave
+ * ?service, ?version, ?service IS service => ?service HAS deployed-version: ?version
+ * ```
+ *
+ * The left side is a comma-separated list of **parameter declarations**
+ * (a segment that is one bare `?name` token), §24.1 **premises** —
+ * CAVE-Q patterns and `?var op value` constraints, verbatim — and may be
+ * empty. The right side is a comma-separated list of one or more
+ * **effect templates**: ordinary claim lines whose subject, object, or
+ * value slots may be variables bound by a parameter or a pattern
+ * premise. A parameter with no other mention is legal — it may
+ * parameterize the action's hook (spec §25.4).
+ *
+ * Unlike a rule, an action is identified by *name*, not content digest:
+ * `action/<name>` is the declaration subject and the body evolves as an
+ * ordinary belief series under one claim key.
+ */
+import { type Ast } from '@cavelang/parser';
+import { Rule } from '@cavelang/cli/rules';
+/** Attribute of action declaration claims: `action/<name> HAS action: …`. */
+export declare const actionAttribute = "action";
+/** Attribute of hook reference claims: `action/<name> HAS hook: <name>` (§25.4). */
+export declare const hookAttribute = "hook";
+/** Subject prefix of action declarations. */
+export declare const subjectPrefix = "action/";
+/** Declaration subject of an action: its name under the `action/` scope. */
+export declare const actionSubject: (name: string) => string;
+/** Action name of a declaration subject, `undefined` when out of scope. */
+export declare const actionName: (subject: string) => undefined | string;
+/**
+ * Parameter names become CLI `param=value` keys, MCP schema properties
+ * and `{param}` hook placeholders, so they are restricted beyond CAVE-Q
+ * variable syntax; `action` is reserved for the hook's `{action}`
+ * placeholder.
+ */
+export declare const paramNameRe: RegExp;
+export type Action = {
+    readonly name: string;
+    /** Declaration subject, `action/<name>`. */
+    readonly subject: string;
+    /** Normalized body text — single-spaced tokens, comment dropped. */
+    readonly text: string;
+    /** Parameter names, in declaration order. */
+    readonly params: readonly string[];
+    readonly premises: readonly Rule.Premise[];
+    /** Effect templates — ordinary claims whose terms may be `?var`s. */
+    readonly effects: readonly Ast.Full[];
+};
+export type t = Action;
+export type Parsed = {
+    readonly ok: true;
+    readonly action: Action;
+} | {
+    readonly ok: false;
+    readonly problems: readonly string[];
+};
+/** Variables an effect template references (subject/object/value slots). */
+export declare const effectVariables: (effect: Ast.Full) => string[];
+/**
+ * Parses one action body. Problems are returned, never thrown — a stored
+ * declaration that fails to parse is reported and skipped, mirroring
+ * rules (§24.1) and the lenient ingest surfaces (spec §1.6).
+ */
+export declare const parse: (subject: string, body: string) => Parsed;
+//# sourceMappingURL=action.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../src/action.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAwB,KAAK,GAAG,EAAE,MAAM,kBAAkB,CAAA;AACjE,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAEtC,6EAA6E;AAC7E,eAAO,MAAM,eAAe,WAAW,CAAA;AAEvC,oFAAoF;AACpF,eAAO,MAAM,aAAa,SAAS,CAAA;AAEnC,6CAA6C;AAC7C,eAAO,MAAM,aAAa,YAAY,CAAA;AAEtC,4EAA4E;AAC5E,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,MACsB,CAAA;AAEnE,2EAA2E;AAC3E,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,KAAG,SAAS,GAAG,MAG5C,CAAA;AAEb;;;;;GAKG;AACH,eAAO,MAAM,WAAW,QAA6B,CAAA;AAErD,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,IAAI,CAAC,OAAO,EAAE,CAAA;IAC1C,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,CAAC,IAAI,EAAE,CAAA;CACtC,CAAA;AAED,MAAM,MAAM,CAAC,GAAG,MAAM,CAAA;AAEtB,MAAM,MAAM,MAAM,GACd;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAA;AAKhE,4EAA4E;AAC5E,eAAO,MAAM,eAAe,GAAI,QAAQ,GAAG,CAAC,IAAI,KAAG,MAAM,EAwBxD,CAAA;AAuDD;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,SAAS,MAAM,EAAE,MAAM,MAAM,KAAG,MA4ErD,CAAA"}

package/dist/internal/act/action.js

@@ -0,0 +1,201 @@
+/**
+ * Action parsing (spec §25.1) — the §24.1 rule line put in the caller's
+ * hands:
+ *
+ * ```cave
+ * ?service, ?version, ?service IS service => ?service HAS deployed-version: ?version
+ * ```
+ *
+ * The left side is a comma-separated list of **parameter declarations**
+ * (a segment that is one bare `?name` token), §24.1 **premises** —
+ * CAVE-Q patterns and `?var op value` constraints, verbatim — and may be
+ * empty. The right side is a comma-separated list of one or more
+ * **effect templates**: ordinary claim lines whose subject, object, or
+ * value slots may be variables bound by a parameter or a pattern
+ * premise. A parameter with no other mention is legal — it may
+ * parameterize the action's hook (spec §25.4).
+ *
+ * Unlike a rule, an action is identified by *name*, not content digest:
+ * `action/<name>` is the declaration subject and the body evolves as an
+ * ordinary belief series under one claim key.
+ */
+import { Claim } from '@cavelang/core';
+import { parseDocument, Token } from '@cavelang/parser';
+import { Rule } from '@cavelang/cli/rules';
+/** Attribute of action declaration claims: `action/<name> HAS action: …`. */
+export const actionAttribute = 'action';
+/** Attribute of hook reference claims: `action/<name> HAS hook: <name>` (§25.4). */
+export const hookAttribute = 'hook';
+/** Subject prefix of action declarations. */
+export const subjectPrefix = 'action/';
+/** Declaration subject of an action: its name under the `action/` scope. */
+export const actionSubject = (name) => name.startsWith(subjectPrefix) ? name : `${subjectPrefix}${name}`;
+/** Action name of a declaration subject, `undefined` when out of scope. */
+export const actionName = (subject) => subject.startsWith(subjectPrefix) && subject.length > subjectPrefix.length ?
+    subject.slice(subjectPrefix.length) :
+    undefined;
+/**
+ * Parameter names become CLI `param=value` keys, MCP schema properties
+ * and `{param}` hook placeholders, so they are restricted beyond CAVE-Q
+ * variable syntax; `action` is reserved for the hook's `{action}`
+ * placeholder.
+ */
+export const paramNameRe = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const isVariableToken = (token) => token.kind === 'word' && token.text.startsWith('?') && token.text.length > 1;
+/** Variables an effect template references (subject/object/value slots). */
+export const effectVariables = (effect) => {
+    const names = [];
+    const term = (candidate) => {
+        if (candidate.kind === 'entity' && candidate.text.startsWith('?') && candidate.text.length > 1) {
+            names.push(candidate.text.slice(1));
+        }
+    };
+    term(effect.subject);
+    switch (effect.payload.kind) {
+        case 'relation':
+            term(effect.payload.object);
+            break;
+        case 'attribute':
+        case 'metric': {
+            const value = effect.payload.value;
+            if (value.kind === 'atom' && value.raw.startsWith('?') && value.raw.length > 1) {
+                names.push(value.raw.slice(1));
+            }
+            break;
+        }
+        default:
+            break;
+    }
+    return names;
+};
+const parseEffect = (segment, bound) => {
+    const problems = [];
+    const text = Rule.normalizeSegment(segment);
+    if (text === '') {
+        return { problems: ['empty effect — remove the extra comma'] };
+    }
+    const tokens = Token.tokenize(segment);
+    if (tokens.some(token => token.kind === 'word' && token.text === '_')) {
+        problems.push('effect slots must be bound — "_" is not allowed on the right side (spec §25.1)');
+    }
+    for (const token of tokens) {
+        if (token.kind === 'word' && /^\?.+:$/.test(token.text)) {
+            problems.push(`variables cannot name attributes (${token.text})`);
+        }
+    }
+    const document = parseDocument(text);
+    const claimLine = document.lines.find(entry => entry.kind === 'claim');
+    if (document.diagnostics.length > 0 || claimLine === undefined || claimLine.kind !== 'claim') {
+        problems.push(`cannot parse effect ${JSON.stringify(text)} as a claim` +
+            document.diagnostics.map(diagnostic => ` — ${diagnostic.message}`).join(''));
+        return { problems };
+    }
+    const effect = claimLine.claim;
+    for (const context of effect.meta.contexts) {
+        if (context.includes('?')) {
+            problems.push(`variables cannot appear in effect contexts (@${context})`);
+        }
+    }
+    for (const tag of effect.meta.tags) {
+        if (tag.key.includes('?') || tag.value?.includes('?') === true) {
+            problems.push(`variables cannot appear in effect tags (#${tag.key}${tag.value === undefined ? '' : `:${tag.value}`})`);
+        }
+    }
+    for (const name of effectVariables(effect)) {
+        if (!bound.has(name)) {
+            problems.push(`effect variable ?${name} is neither a parameter nor bound by a pattern premise (spec §25.1)`);
+        }
+    }
+    return problems.length > 0 ? { problems } : { effect, problems: [] };
+};
+/** Splits `text` at its top-level commas — literal-protected, like §24.1. */
+const splitSegments = (text) => {
+    const segments = [];
+    let cursor = 0;
+    for (const at of Rule.topLevel(text, ',')) {
+        segments.push(text.slice(cursor, at));
+        cursor = at + 1;
+    }
+    segments.push(text.slice(cursor));
+    return segments;
+};
+/**
+ * Parses one action body. Problems are returned, never thrown — a stored
+ * declaration that fails to parse is reported and skipped, mirroring
+ * rules (§24.1) and the lenient ingest surfaces (spec §1.6).
+ */
+export const parse = (subject, body) => {
+    const problems = [];
+    const name = actionName(subject);
+    if (name === undefined) {
+        return { ok: false, problems: [`declaration subject ${JSON.stringify(subject)} is not under ${subjectPrefix} (spec §25.1)`] };
+    }
+    const { head } = Token.splitComment(body);
+    const arrows = Rule.topLevel(head, '=>');
+    if (arrows.length === 0) {
+        return { ok: false, problems: ['not an action — no top-level "=>" (spec §25.1)'] };
+    }
+    if (arrows.length > 1) {
+        return { ok: false, problems: ['an action has exactly one "=>" (spec §25.1)'] };
+    }
+    const leftText = head.slice(0, arrows[0]);
+    const rightText = head.slice(arrows[0] + 2);
+    const params = [];
+    const premises = [];
+    const bound = new Set();
+    if (leftText.trim() !== '') {
+        for (const segment of splitSegments(leftText)) {
+            const tokens = Token.tokenize(segment);
+            if (tokens.length === 1 && isVariableToken(tokens[0])) {
+                const param = tokens[0].text.slice(1);
+                if (!paramNameRe.test(param)) {
+                    problems.push(`parameter ?${param} — names are letters, digits, _ and - and start with a letter (spec §25.1)`);
+                    continue;
+                }
+                if (param === 'action') {
+                    problems.push('parameter ?action — the name is reserved for the {action} hook placeholder (spec §25.4)');
+                    continue;
+                }
+                if (params.includes(param)) {
+                    problems.push(`parameter ?${param} is declared twice`);
+                    continue;
+                }
+                params.push(param);
+                bound.add(param);
+                continue;
+            }
+            const { premise, problem } = Rule.parsePremise(segment, bound);
+            if (problem !== undefined) {
+                problems.push(problem);
+                continue;
+            }
+            premises.push(premise);
+            if (premise.kind === 'pattern') {
+                Rule.patternVariables(premise.pattern).forEach(variable => bound.add(variable));
+            }
+        }
+    }
+    const effects = [];
+    const effectTexts = [];
+    for (const segment of splitSegments(rightText)) {
+        const { effect, problems: effectProblems } = parseEffect(segment, bound);
+        problems.push(...effectProblems);
+        if (effect !== undefined) {
+            effects.push(effect);
+            effectTexts.push(Rule.normalizeSegment(segment));
+        }
+    }
+    if (effects.length === 0 && problems.length === 0) {
+        problems.push('an action needs at least one effect (spec §25.1)');
+    }
+    if (problems.length > 0) {
+        return { ok: false, problems };
+    }
+    const left = [
+        ...params.map(param => `?${param}`),
+        ...premises.map(premise => premise.text)
+    ].join(', ');
+    const text = `${left === '' ? '' : `${left} `}=> ${effectTexts.join(', ')}`;
+    return { ok: true, action: { name, subject, text, params, premises, effects } };
+};
+//# sourceMappingURL=action.js.map

package/dist/internal/act/action.js.map

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

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

@@ -0,0 +1,102 @@
+/**
+ * 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 { Row, type Store } from '@cavelang/store';
+import * as Action from './action.ts';
+/** Source context stamped on declarations and bookkeeping (spec §9.5). */
+export declare const provenanceContext = "src:cave-act";
+/**
+ * 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 declare const currentAttribute: (store: Store, subject: string, attribute: string) => undefined | Row.t;
+export type Loaded = {
+    readonly action: Action.t;
+    /** The declaration row — target of effect rows' `VIA` edges (§25.2). */
+    readonly row: Row.t;
+    /** Declaration comment — the action's description. */
+    readonly description?: string;
+};
+/**
+ * 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 declare const loadAction: (store: Store, name: string) => undefined | {
+    loaded?: Loaded;
+    problems: readonly string[];
+};
+/** The hook name the action currently references, if any (§25.4). */
+export declare const currentHook: (store: Store, subject: string) => undefined | string;
+export type ListedParam = {
+    readonly name: string;
+    readonly doc?: string;
+};
+export type ListedAction = {
+    /** Declaration subject, `action/<name>`. */
+    readonly subject: string;
+    readonly name: string;
+    readonly text: string;
+    readonly description?: string;
+    readonly params: readonly ListedParam[];
+    readonly hook?: string;
+    readonly ok: boolean;
+    readonly problems: readonly string[];
+};
+/** Current positive actions of a store, in declaration order. */
+export declare const listActions: (store: Store) => ListedAction[];
+export type Declaration = {
+    /** Actions newly declared (or re-declared after a change/retraction). */
+    readonly declared: number;
+    /** Actions whose declaration is already current — nothing appended. */
+    readonly unchanged: number;
+    /** Claims appended by the file's prelude (0 when unchanged). */
+    readonly prelude: number;
+    readonly actions: readonly Action.t[];
+    readonly problems: readonly {
+        line: number;
+        message: string;
+    }[];
+};
+/**
+ * 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 declare const declareActions: (store: Store, text: string) => Declaration;
+export type Retraction = {
+    readonly ok: true;
+    readonly subject: string;
+    readonly retracted: number;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * 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 declare const retractAction: (store: Store, ref: string) => Retraction;
+//# sourceMappingURL=declare.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"declare.d.ts","sourceRoot":"","sources":["../../src/declare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,EAAE,GAAG,EAAE,KAAK,KAAK,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,iBAAiB,CAAA;AAe/C;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,KAAK,EAAE,SAAS,MAAM,EAAE,WAAW,MAAM,KAAG,SAAS,GAAG,GAAG,CAAC,CASnG,CAAA;AAqBD,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACzB,wEAAwE;IACxE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;IACnB,sDAAsD;IACtD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,KAAK,EAAE,MAAM,MAAM,KAAG,SAAS,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAkBjH,CAAA;AAED,qEAAqE;AACrE,eAAO,MAAM,WAAW,GAAI,OAAO,KAAK,EAAE,SAAS,MAAM,KAAG,SAAS,GAAG,MAGvE,CAAA;AAcD,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAA;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC,CAAA;AAED,iEAAiE;AACjE,eAAO,MAAM,WAAW,GAAI,OAAO,KAAK,KAAG,YAAY,EAqBnD,CAAA;AAEJ,MAAM,MAAM,WAAW,GAAG;IACxB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,CAAC,CAAC,EAAE,CAAA;IACrC,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAChE,CAAA;AA2CD;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,KAAK,EAAE,MAAM,MAAM,KAAG,WA8E3D,CAAA;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC3E;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAElD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,KAAK,EAAE,KAAK,MAAM,KAAG,UAmBzD,CAAA"}