Initial vibecoded proof of concept

specs/002-notex-is-a/contracts/query-api.md

@@ -0,0 +1,172 @@
+# Query API Contract
+
+## Query Syntax
+
+### Basic Query Structure
+```
+```notex-query
+FROM <property_filters>
+[WHERE <conditions>]
+[ORDER BY <property> [ASC|DESC]]
+[GROUP BY <property>]
+[LIMIT <number>]
+```
+```
+
+### Property Filters
+```yaml
+# Filter by property existence
+status:          # Returns documents with 'status' property
+
+# Filter by property value
+status: "draft"  # Returns documents where status = "draft"
+
+# Multiple property filters
+status: "draft"
+priority: "high"
+tags: ["research", "urgent"]
+```
+
+### Conditions
+```yaml
+# Comparison operators
+WHERE priority > 5
+WHERE created_at >= "2024-01-01"
+WHERE status != "archived"
+
+# Logical operators
+WHERE status = "active" AND priority > 3
+WHERE status = "urgent" OR priority > 5
+WHERE NOT status = "archived"
+
+# String matching
+WHERE title CONTAINS "important"
+WHERE tags STARTS_WITH "project"
+WHERE author ENDS_WITH "@company.com"
+
+# Array operations
+WHERE tags INCLUDES "urgent"
+WHERE tags SIZE > 3
+
+# Date operations
+WHERE created_at BEFORE "2024-06-01"
+WHERE updated_at AFTER "2024-01-01"
+WHERE due_date WITHIN 7d
+```
+
+## Query Execution API
+
+### Parse Query
+**Input**: Raw query string
+**Output**: Parsed query object
+```lua
+{
+  filters = {
+    status = "draft",
+    priority = "high"
+  },
+  conditions = {
+    type = "AND",
+    clauses = {
+      { type = "comparison", field = "priority", operator = ">", value = 3 }
+    }
+  },
+  order_by = { field = "created_at", direction = "DESC" },
+  group_by = "status",
+  limit = 50
+}
+```
+
+### Execute Query
+**Input**: Parsed query object
+**Output**: Query results
+```lua
+{
+  documents = {
+    {
+      id = "doc123",
+      file_path = "/path/to/document.md",
+      properties = {
+        status = "draft",
+        priority = "high",
+        created_at = "2024-03-15T10:30:00Z"
+      }
+    }
+  },
+  total_count = 1,
+  execution_time_ms = 45,
+  query_hash = "abc123def"
+}
+```
+
+## Virtual Buffer API
+
+### Create Query View
+**Input**: Query results
+**Output**: Virtual buffer configuration
+```lua
+{
+  buffer_id = 5,
+  window_id = 1002,
+  lines = {
+    "Results for: status=draft, priority=high",
+    "",
+    "| Title        | Status | Priority | Created     |",
+    "|--------------|--------|----------|-------------|",
+    "| Research Doc | draft  | high     | 2024-03-15  |"
+  },
+  mappings = {
+    ["<CR>"] = "open_document",
+    ["e"] = "edit_document",
+    ["q"] = "close_query_view"
+  },
+  syntax = "notex_query_results"
+}
+```
+
+### Update Document Property
+**Input**: Document ID, property name, new value
+**Output**: Update result
+```lua
+{
+  success = true,
+  document_id = "doc123",
+  property = "status",
+  old_value = "draft",
+  new_value = "review",
+  updated_file = true
+}
+```
+
+## Error Handling
+
+### Query Parse Errors
+```lua
+{
+  error_type = "parse_error",
+  message = "Invalid syntax at line 3: column 5",
+  line = 3,
+  column = 5,
+  context = "WHERE priority >"
+}
+```
+
+### Query Execution Errors
+```lua
+{
+  error_type = "execution_error",
+  message = "Property 'nonexistent' not found in any document",
+  property_name = "nonexistent",
+  suggested_properties = {"status", "priority", "type"}
+}
+```
+
+### Document Update Errors
+```lua
+{
+  error_type = "update_error",
+  message = "File not found or not writable",
+  document_id = "doc123",
+  file_path = "/path/to/missing.md"
+}
+```