@cavelang/tree-sitter-cave 0.34.0 → 0.36.0

package/README.md

@@ -14,6 +14,11 @@ Entity and attribute names accept Unicode letters, combining marks and
 numbers, with `/`, `-`, `_`, and `.` as structural characters. Numeric
 values include negative scalars and negative trajectory endpoints.
 
+Explicit full claims use a leading `@claim` marker (§8.6), including inside
+qualifier payloads. The marker is highlighted as a keyword and reserved or
+numeric-looking subjects (such as `42` and `2026-01-01`) as entities; a trailing `@claim` is still a context. Prefix expansion remains the
+semantic parser's responsibility.
+
 ## Contents
 
 - `grammar.js` — the grammar (spec §16, §3–§8)
@@ -31,7 +36,39 @@ values include negative scalars and negative trajectory endpoints.
 tree-sitter CLI and WASI SDK archives listed in
 `scripts/grammar-toolchain.json`, verifies their SHA-256 digests, and caches
 them under `~/.cache/cave/grammar-toolchain`. Package installation itself
-does not run a binary downloader.
+does not run a binary downloader. After compilation, the Wasm module is
+normalized to file mode `0644`: it is loaded as data, not executed by the OS.
+Keeping both the generated output and tracked artifact non-executable also
+allows the Changesets version-PR action to commit it through the GitHub API.
+
+The package test command also regenerates the native sources and WASM before
+running the grammar corpus. Run workspace test matrices one Node version at a
+time in a shared checkout: these commands write the same generated files and
+use Tree-sitter's native parser cache. The workspace's package-concurrency
+setting does not serialize two separate `pnpm test` processes.
+
+Each missing archive download has a five-minute deadline covering connection
+setup and the response body. Set `CAVE_GRAMMAR_DOWNLOAD_TIMEOUT_SECONDS` to a
+positive number (up to 2147483.647) for slower links or shorter automation limits.
+Invalid settings fail before cache creation. Failed transfers remove partial
+files, and setup waits for both parallel preparations to settle before reporting
+failure. Verified cached archives continue to support offline builds.
+A local-server regression verifies timeout cleanup, corrected retry with
+checksum-verified fixture archives, and an offline reuse pass with no requests.
+A partial-failure case also verifies that a delayed successful archive remains
+verified and installed when its peer returns HTTP 503; retry fetches only the
+missing archive.
+SDK setup validates the exact first line of `VERSION` before replacing an
+existing installation; subsequent build metadata lines remain supported. A
+missing or mismatched version leaves the prior installation intact and removes
+the rejected staging directory. Cached installations with a version mismatch
+are re-extracted from the verified archive, including in offline mode.
+The same repair applies when installed version or source-marker metadata is a
+directory instead of a file.
+Staging cleanup also runs when reading version metadata or writing the source
+marker fails, so malformed extracted files do not leave temporary SDK trees.
+The fixtures test setup and cache behavior; the separate corpus run exercises
+the real pinned tools.
 
 For an offline or pre-provisioned build, copy the two archives for the host
 platform into `$CAVE_GRAMMAR_CACHE/downloads` (the variable defaults to the

package/grammar.js

@@ -41,11 +41,19 @@ module.exports = grammar({
 
     comment_line: $ => $.comment,
 
-    claim_line: $ => seq(
-      field('subject', choice($._term, alias($.verb, $.entity))),
-      $._body
+    claim_line: $ => choice(
+      seq(field('subject', choice($._term, alias($.verb, $.entity))), $._body),
+      $._explicit_claim
     ),
 
+    _explicit_claim: $ => prec.right(1, seq(
+      $.claim_marker,
+      field('subject', choice($._term, alias($.verb, $.entity), alias($.qualifier_verb, $.entity), alias($.negation, $.entity), alias($.number, $.entity))),
+      $._body
+    )),
+
+    claim_marker: () => '@claim',
+
     // Bare relational verb; the subject is inherited from the parent (§8.3).
     continuation_line: $ => prec.dynamic(-1, $._body),
 
@@ -53,8 +61,9 @@ module.exports = grammar({
     // Indentation and prefix expansion remain consumer responsibilities;
     // this permissive fallback keeps every fragment highlightable while the
     // complete line rules above retain precedence.
-    shorthand_line: $ => prec.dynamic(-2, seq(
-      repeat1(choice(
+    shorthand_line: $ => prec.dynamic(-2, choice(
+      prec(2, seq($.claim_marker, optional($.comment))),
+      seq(repeat1(choice(
         $.verb,
         $.attribute,
         $._term,
@@ -63,7 +72,7 @@ module.exports = grammar({
         $._meta,
         '->'
       )),
-      optional($.comment)
+      optional($.comment))
     )),
 
     _body: $ => choice(
@@ -120,6 +129,7 @@ module.exports = grammar({
 
     // Qualifier payload (§8.2): comparison, nested claim, or bare condition.
     _qualifier_payload: $ => choice(
+      $._explicit_claim,
       $.comparison,
       seq(field('subject', $._term), $._body),
       $._term
@@ -137,6 +147,7 @@ module.exports = grammar({
 
     _meta: $ => choice(
       $.context,
+      alias($.claim_marker, $.context),
       $.confidence,
       $.tag,
       $.uncertainty,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavelang/tree-sitter-cave",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "Tree-sitter grammar for CAVE — the canonical grammar artifact behind editor and terminal highlighting.",
   "keywords": [
     "cave",
@@ -20,7 +20,7 @@
     "directory": "packages/tree-sitter-cave"
   },
   "engines": {
-    "node": "^22.18.0 || ^24.0.0 || ^26.0.0"
+    "node": "^24.16.0 || ^26.1.0"
   },
   "exports": {
     "./wasm": "./tree-sitter-cave.wasm",

package/queries/highlights.scm

@@ -30,3 +30,6 @@
 (tag ":" @punctuation.delimiter)
 (tag_key) @tag
 (tag_value) @constant
+
+; Explicit full-claim disambiguation; trailing @claim remains context.
+(claim_marker) @keyword

package/src/grammar.json

@@ -73,95 +73,204 @@
       "name": "comment"
     },
     "claim_line": {
-      "type": "SEQ",
+      "type": "CHOICE",
       "members": [
         {
-          "type": "FIELD",
-          "name": "subject",
-          "content": {
-            "type": "CHOICE",
-            "members": [
-              {
-                "type": "SYMBOL",
-                "name": "_term"
-              },
-              {
-                "type": "ALIAS",
-                "content": {
-                  "type": "SYMBOL",
-                  "name": "verb"
-                },
-                "named": true,
-                "value": "entity"
+          "type": "SEQ",
+          "members": [
+            {
+              "type": "FIELD",
+              "name": "subject",
+              "content": {
+                "type": "CHOICE",
+                "members": [
+                  {
+                    "type": "SYMBOL",
+                    "name": "_term"
+                  },
+                  {
+                    "type": "ALIAS",
+                    "content": {
+                      "type": "SYMBOL",
+                      "name": "verb"
+                    },
+                    "named": true,
+                    "value": "entity"
+                  }
+                ]
               }
-            ]
-          }
+            },
+            {
+              "type": "SYMBOL",
+              "name": "_body"
+            }
+          ]
         },
         {
           "type": "SYMBOL",
-          "name": "_body"
+          "name": "_explicit_claim"
         }
       ]
     },
-    "continuation_line": {
-      "type": "PREC_DYNAMIC",
-      "value": -1,
-      "content": {
-        "type": "SYMBOL",
-        "name": "_body"
-      }
-    },
-    "shorthand_line": {
-      "type": "PREC_DYNAMIC",
-      "value": -2,
+    "_explicit_claim": {
+      "type": "PREC_RIGHT",
+      "value": 1,
       "content": {
         "type": "SEQ",
         "members": [
           {
-            "type": "REPEAT1",
+            "type": "SYMBOL",
+            "name": "claim_marker"
+          },
+          {
+            "type": "FIELD",
+            "name": "subject",
             "content": {
               "type": "CHOICE",
               "members": [
                 {
                   "type": "SYMBOL",
-                  "name": "verb"
+                  "name": "_term"
                 },
                 {
-                  "type": "SYMBOL",
-                  "name": "attribute"
+                  "type": "ALIAS",
+                  "content": {
+                    "type": "SYMBOL",
+                    "name": "verb"
+                  },
+                  "named": true,
+                  "value": "entity"
                 },
                 {
-                  "type": "SYMBOL",
-                  "name": "_term"
+                  "type": "ALIAS",
+                  "content": {
+                    "type": "SYMBOL",
+                    "name": "qualifier_verb"
+                  },
+                  "named": true,
+                  "value": "entity"
                 },
                 {
-                  "type": "SYMBOL",
-                  "name": "number"
+                  "type": "ALIAS",
+                  "content": {
+                    "type": "SYMBOL",
+                    "name": "negation"
+                  },
+                  "named": true,
+                  "value": "entity"
                 },
                 {
-                  "type": "SYMBOL",
-                  "name": "negation"
-                },
+                  "type": "ALIAS",
+                  "content": {
+                    "type": "SYMBOL",
+                    "name": "number"
+                  },
+                  "named": true,
+                  "value": "entity"
+                }
+              ]
+            }
+          },
+          {
+            "type": "SYMBOL",
+            "name": "_body"
+          }
+        ]
+      }
+    },
+    "claim_marker": {
+      "type": "STRING",
+      "value": "@claim"
+    },
+    "continuation_line": {
+      "type": "PREC_DYNAMIC",
+      "value": -1,
+      "content": {
+        "type": "SYMBOL",
+        "name": "_body"
+      }
+    },
+    "shorthand_line": {
+      "type": "PREC_DYNAMIC",
+      "value": -2,
+      "content": {
+        "type": "CHOICE",
+        "members": [
+          {
+            "type": "PREC",
+            "value": 2,
+            "content": {
+              "type": "SEQ",
+              "members": [
                 {
                   "type": "SYMBOL",
-                  "name": "_meta"
+                  "name": "claim_marker"
                 },
                 {
-                  "type": "STRING",
-                  "value": "->"
+                  "type": "CHOICE",
+                  "members": [
+                    {
+                      "type": "SYMBOL",
+                      "name": "comment"
+                    },
+                    {
+                      "type": "BLANK"
+                    }
+                  ]
                 }
               ]
             }
           },
           {
-            "type": "CHOICE",
+            "type": "SEQ",
             "members": [
               {
-                "type": "SYMBOL",
-                "name": "comment"
+                "type": "REPEAT1",
+                "content": {
+                  "type": "CHOICE",
+                  "members": [
+                    {
+                      "type": "SYMBOL",
+                      "name": "verb"
+                    },
+                    {
+                      "type": "SYMBOL",
+                      "name": "attribute"
+                    },
+                    {
+                      "type": "SYMBOL",
+                      "name": "_term"
+                    },
+                    {
+                      "type": "SYMBOL",
+                      "name": "number"
+                    },
+                    {
+                      "type": "SYMBOL",
+                      "name": "negation"
+                    },
+                    {
+                      "type": "SYMBOL",
+                      "name": "_meta"
+                    },
+                    {
+                      "type": "STRING",
+                      "value": "->"
+                    }
+                  ]
+                }
               },
               {
-                "type": "BLANK"
+                "type": "CHOICE",
+                "members": [
+                  {
+                    "type": "SYMBOL",
+                    "name": "comment"
+                  },
+                  {
+                    "type": "BLANK"
+                  }
+                ]
               }
             ]
           }
@@ -529,6 +638,10 @@
     "_qualifier_payload": {
       "type": "CHOICE",
       "members": [
+        {
+          "type": "SYMBOL",
+          "name": "_explicit_claim"
+        },
         {
           "type": "SYMBOL",
           "name": "comparison"
@@ -647,6 +760,15 @@
           "type": "SYMBOL",
           "name": "context"
         },
+        {
+          "type": "ALIAS",
+          "content": {
+            "type": "SYMBOL",
+            "name": "claim_marker"
+          },
+          "named": true,
+          "value": "context"
+        },
         {
           "type": "SYMBOL",
           "name": "confidence"

package/src/node-types.json

@@ -79,7 +79,7 @@
       },
       "verb": {
         "multiple": false,
-        "required": true,
+        "required": false,
         "types": [
           {
             "type": "verb",
@@ -92,6 +92,10 @@
       "multiple": true,
       "required": false,
       "types": [
+        {
+          "type": "claim_marker",
+          "named": true
+        },
         {
           "type": "comment",
           "named": true
@@ -307,6 +311,11 @@
       ]
     }
   },
+  {
+    "type": "entity",
+    "named": true,
+    "fields": {}
+  },
   {
     "type": "object",
     "named": true,
@@ -342,6 +351,10 @@
             "type": "attr_value",
             "named": true
           },
+          {
+            "type": "claim_marker",
+            "named": true
+          },
           {
             "type": "code",
             "named": true
@@ -493,6 +506,10 @@
           "type": "attribute",
           "named": true
         },
+        {
+          "type": "claim_marker",
+          "named": true
+        },
         {
           "type": "code",
           "named": true
@@ -668,6 +685,10 @@
     "type": "attribute",
     "named": true
   },
+  {
+    "type": "claim_marker",
+    "named": true
+  },
   {
     "type": "code",
     "named": true
@@ -684,10 +705,6 @@
     "type": "context",
     "named": true
   },
-  {
-    "type": "entity",
-    "named": true
-  },
   {
     "type": "importance",
     "named": true