@jarenjs/db 0.73.0 → 0.83.2

package/schemas/jaren-model.authoring.schema.json

@@ -0,0 +1,360 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jarenjs.dev/schemas/jaren-model/authoring",
+  "title": "Jaren model document (authoring profile)",
+  "description": "Authoring profile of the canonical grammar: the document SHAPE only, with  left open. Constrains decoding on small models, where the full grammar does not decode at all. It is deliberately WEAKER than the canonical schema - a document valid here may be nonsense - so the engine compiler is the gate that makes it safe, and generated documents must be compiled before use.",
+  "type": "object",
+  "properties": {
+    "$model": {
+      "description": "The model format version.",
+      "const": "0.1"
+    },
+    "collections": {
+      "description": "Collection name (an identifier) to collection declaration. (LLM profile: a member-name constraint is relaxed here; the canonical schema enforces it)",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "$ref": "#/$defs/collection"
+      }
+    },
+    "entities": {
+      "description": "Entity name (an identifier) to entity declaration. The x-entity vocabulary lives INSIDE each entity schema's property subschemas and is documented in MODEL-FORMAT.md §9; stripping it leaves a plain JSON Schema. (LLM profile: a member-name constraint is relaxed here; the canonical schema enforces it)",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "$ref": "#/$defs/entity"
+      }
+    }
+  },
+  "required": [
+    "$model"
+  ],
+  "additionalProperties": false,
+  "anyOf": [
+    {
+      "required": [
+        "collections"
+      ]
+    },
+    {
+      "required": [
+        "entities"
+      ]
+    }
+  ],
+  "$defs": {
+    "collection": {
+      "description": "One collection: a document schema, the key declaration, and the declared indexes. A collection without a key pointer MUST declare how keys are allocated; allocation is declared, never guessed.",
+      "type": "object",
+      "properties": {
+        "schema": {
+          "description": "The JSON Schema every stored document validates against (through the injected hook). Also the type source for indexed paths.",
+          "type": "object"
+        },
+        "key": {
+          "description": "Where the caller-supplied key lives in the document, as an RFC 6901 pointer selecting at least one member — or null when the store allocates.",
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^/"
+        },
+        "identity": {
+          "description": "How keys come to be: 'caller' (the default when a key pointer is declared), or — only with \"key\": null — 'uuid' (crypto.randomUUID) or 'integer' (database-allocated).",
+          "enum": [
+            "caller",
+            "uuid",
+            "integer"
+          ]
+        },
+        "indexes": {
+          "description": "Declared indexes; each singular path becomes a generated column plus an index.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/index"
+          }
+        },
+        "x-rename": {
+          "description": "Migration hint: this collection was previously named the given identifier. Read by the migration planner (a rename cannot be inferred from a diff); ignored by the store.",
+          "type": "string",
+          "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+        }
+      },
+      "required": [
+        "schema"
+      ],
+      "additionalProperties": false
+    },
+    "index": {
+      "description": "One index over a singular JSONPath expression (or a composite over several). A non-singular path is rejected at open (JD0004). A derived index computes indexable scalars from the selected member instead of indexing it directly. An index may instead declare an expression: a closed computation over members, scalars and host-declared deterministic functions.",
+      "type": "object",
+      "properties": {
+        "name": {
+          "description": "The index name, unique within its collection.",
+          "type": "string",
+          "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+        },
+        "path": {
+          "description": "A singular JSONPath expression into the stored document ($.email), or a non-empty array of them for a composite index.",
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              },
+              "minItems": 1
+            }
+          ]
+        },
+        "expression": {
+          "description": "Index a computed value rather than a member: a closed expression over declared members, JSON scalars and functions the host declared deterministic. Mutually exclusive with path and derive (JD0004) — an expression names the members it reads itself.",
+          "allOf": [
+            {
+              "$ref": "#/$defs/expression"
+            }
+          ]
+        },
+        "unique": {
+          "description": "Whether the index enforces uniqueness. Defaults to false.",
+          "type": "boolean"
+        },
+        "derive": {
+          "description": "Derive columns from the selected member instead of indexing it: 'geohash' (one TEXT cell column, precision required), 'bbox' (four REAL columns — west, south, east, north), or 'vector' (one packed BLOB column holding the l2-normalized Float32 form of an array of numbers, dims required; stored on every driver, with no B-tree over it — a fetch-and-rank plan reads it whole). A derived index is never unique.",
+          "enum": [
+            "geohash",
+            "bbox",
+            "vector"
+          ]
+        },
+        "precision": {
+          "description": "Geohash cell length in characters, 1-12. Required beside derive: 'geohash' and refused anywhere else — there is no safe default, because the right cell size depends on the query radius, which the model cannot know.",
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 12
+        },
+        "dims": {
+          "description": "The width of a derive: 'vector' column in components, 1-8192. Required beside derive: 'vector' and refused anywhere else: the width is the column's identity — two widths over one path are two columns — and a member that is not an array of exactly this many finite numbers stores NULL in the column (the document itself still stores). Constrain the member with minItems/maxItems equal to dims in the collection's schema so a wrong-width vector is refused at the write instead.",
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8192
+        },
+        "physical": {
+          "description": "The shape a derive: 'bbox' index takes on disk: 'columns' (the default) is four generated columns under one B-tree; 'rtree' keeps the same four columns and adds a SQLite R*Tree virtual table beside the collection, kept in sync by declared triggers, with no B-tree over the columns. The logical meaning of derive: 'bbox' is identical either way. Refused on any other index kind, and on a driver without the module it falls back to 'columns' and says so through explain().prefilters[].via.",
+          "enum": [
+            "columns",
+            "rtree"
+          ]
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "additionalProperties": false
+    },
+    "entity": {
+      "description": "One entity: an object schema whose top-level properties map to columns per the hybrid rule (scalars become typed columns, nested shapes stay JSONB); keys, indexes, defaults and relations are declared with x-entity inside the schema.",
+      "type": "object",
+      "properties": {
+        "schema": {
+          "type": "object"
+        },
+        "x-rename": {
+          "type": "string",
+          "description": "Declares this entity as the rename of the named from-model entity (MIGRATION-FORMAT §9): a rename is declared, never inferred."
+        },
+        "physical": {
+          "type": "object",
+          "required": [
+            "table",
+            "columns"
+          ],
+          "properties": {
+            "table": {
+              "type": "string",
+              "minLength": 1
+            },
+            "kind": {
+              "enum": [
+                "table",
+                "view"
+              ]
+            },
+            "keys": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "minItems": 1,
+              "uniqueItems": true
+            },
+            "columns": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "object",
+                "required": [
+                  "name",
+                  "codec",
+                  "null"
+                ],
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "codec": {
+                    "enum": [
+                      "text",
+                      "integer",
+                      "number",
+                      "boolean",
+                      "json",
+                      "date",
+                      "datetime",
+                      "epoch-ms",
+                      "bigint",
+                      "decimal",
+                      "blob-hex"
+                    ]
+                  },
+                  "null": {
+                    "enum": [
+                      "null",
+                      "absent",
+                      "reject"
+                    ]
+                  },
+                  "default": {
+                    "const": "database"
+                  },
+                  "generated": {
+                    "type": "boolean"
+                  }
+                },
+                "additionalProperties": false
+              }
+            }
+          },
+          "additionalProperties": false
+        },
+        "invariants": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "on",
+              "assert",
+              "enforcement"
+            ],
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+              },
+              "on": {
+                "type": "array",
+                "minItems": 1,
+                "uniqueItems": true,
+                "items": {
+                  "enum": [
+                    "insert",
+                    "update",
+                    "delete"
+                  ]
+                }
+              },
+              "assert": {},
+              "enforcement": {
+                "enum": [
+                  "database",
+                  "store"
+                ]
+              },
+              "audit": {
+                "type": "object",
+                "required": [
+                  "entity",
+                  "values"
+                ],
+                "properties": {
+                  "entity": {
+                    "type": "string"
+                  },
+                  "values": {
+                    "type": "object"
+                  }
+                },
+                "additionalProperties": false
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": [
+        "schema"
+      ],
+      "additionalProperties": false
+    },
+    "expression": {
+      "description": "One node of an index expression: a member path, a JSON scalar, or a call to a function the host declared. Exactly one of the three, and nothing else — an index expression is never SQL text, and the function it names is resolved for arity and determinism at open (JD0004).",
+      "type": "object",
+      "anyOf": [
+        {
+          "required": [
+            "member"
+          ],
+          "properties": {
+            "member": {
+              "description": "A singular JSONPath expression into the stored document ($.email).",
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "additionalProperties": false
+        },
+        {
+          "required": [
+            "value"
+          ],
+          "properties": {
+            "value": {
+              "description": "A JSON scalar. A null or a compound has no place in an index expression.",
+              "type": [
+                "string",
+                "number",
+                "boolean"
+              ]
+            }
+          },
+          "additionalProperties": false
+        },
+        {
+          "required": [
+            "call"
+          ],
+          "properties": {
+            "call": {
+              "description": "The name of a function the host declared through openStore({ expressions }). The store refuses a name it was not given, a wrong arity, and one not declared deterministic — before any DDL.",
+              "type": "string",
+              "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+            },
+            "args": {
+              "description": "The arguments, in order. Order is significant: sub(a, b) and sub(b, a) are different expressions and different columns.",
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/expression"
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    }
+  }
+}

package/schemas/jaren-model.draft-07.schema.json

@@ -160,6 +160,134 @@
         "x-rename": {
           "type": "string",
           "description": "Declares this entity as the rename of the named from-model entity (MIGRATION-FORMAT \u00a79): a rename is declared, never inferred."
+        },
+        "physical": {
+          "type": "object",
+          "required": [
+            "table",
+            "columns"
+          ],
+          "properties": {
+            "table": {
+              "type": "string",
+              "minLength": 1
+            },
+            "kind": {
+              "enum": [
+                "table",
+                "view"
+              ]
+            },
+            "keys": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "minItems": 1,
+              "uniqueItems": true
+            },
+            "columns": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "object",
+                "required": [
+                  "name",
+                  "codec",
+                  "null"
+                ],
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "codec": {
+                    "enum": [
+                      "text",
+                      "integer",
+                      "number",
+                      "boolean",
+                      "json",
+                      "date",
+                      "datetime",
+                      "epoch-ms",
+                      "bigint",
+                      "decimal",
+                      "blob-hex"
+                    ]
+                  },
+                  "null": {
+                    "enum": [
+                      "null",
+                      "absent",
+                      "reject"
+                    ]
+                  },
+                  "default": {
+                    "const": "database"
+                  },
+                  "generated": {
+                    "type": "boolean"
+                  }
+                },
+                "additionalProperties": false
+              }
+            }
+          },
+          "additionalProperties": false
+        },
+        "invariants": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "on",
+              "assert",
+              "enforcement"
+            ],
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+              },
+              "on": {
+                "type": "array",
+                "minItems": 1,
+                "uniqueItems": true,
+                "items": {
+                  "enum": [
+                    "insert",
+                    "update",
+                    "delete"
+                  ]
+                }
+              },
+              "assert": {},
+              "enforcement": {
+                "enum": [
+                  "database",
+                  "store"
+                ]
+              },
+              "audit": {
+                "type": "object",
+                "required": [
+                  "entity",
+                  "values"
+                ],
+                "properties": {
+                  "entity": {
+                    "type": "string"
+                  },
+                  "values": {
+                    "type": "object"
+                  }
+                },
+                "additionalProperties": false
+              }
+            },
+            "additionalProperties": false
+          }
         }
       },
       "required": [

package/schemas/jaren-model.schema.json

@@ -160,6 +160,134 @@
         "x-rename": {
           "type": "string",
           "description": "Declares this entity as the rename of the named from-model entity (MIGRATION-FORMAT \u00a79): a rename is declared, never inferred."
+        },
+        "physical": {
+          "type": "object",
+          "required": [
+            "table",
+            "columns"
+          ],
+          "properties": {
+            "table": {
+              "type": "string",
+              "minLength": 1
+            },
+            "kind": {
+              "enum": [
+                "table",
+                "view"
+              ]
+            },
+            "keys": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "minItems": 1,
+              "uniqueItems": true
+            },
+            "columns": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "object",
+                "required": [
+                  "name",
+                  "codec",
+                  "null"
+                ],
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "codec": {
+                    "enum": [
+                      "text",
+                      "integer",
+                      "number",
+                      "boolean",
+                      "json",
+                      "date",
+                      "datetime",
+                      "epoch-ms",
+                      "bigint",
+                      "decimal",
+                      "blob-hex"
+                    ]
+                  },
+                  "null": {
+                    "enum": [
+                      "null",
+                      "absent",
+                      "reject"
+                    ]
+                  },
+                  "default": {
+                    "const": "database"
+                  },
+                  "generated": {
+                    "type": "boolean"
+                  }
+                },
+                "additionalProperties": false
+              }
+            }
+          },
+          "additionalProperties": false
+        },
+        "invariants": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "on",
+              "assert",
+              "enforcement"
+            ],
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+              },
+              "on": {
+                "type": "array",
+                "minItems": 1,
+                "uniqueItems": true,
+                "items": {
+                  "enum": [
+                    "insert",
+                    "update",
+                    "delete"
+                  ]
+                }
+              },
+              "assert": {},
+              "enforcement": {
+                "enum": [
+                  "database",
+                  "store"
+                ]
+              },
+              "audit": {
+                "type": "object",
+                "required": [
+                  "entity",
+                  "values"
+                ],
+                "properties": {
+                  "entity": {
+                    "type": "string"
+                  },
+                  "values": {
+                    "type": "object"
+                  }
+                },
+                "additionalProperties": false
+              }
+            },
+            "additionalProperties": false
+          }
         }
       },
       "required": [

package/src/algebra.js

@@ -50,13 +50,17 @@ export const PLAN_VERSION = 2;
  *   { p: 'not', item: PlanPredicate } |
  *   { p: 'cmp', op: 'eq' | 'ne' | 'lt' | 'le' | 'gt' | 'ge',
  *     ref: PlanRef, operand: PlanOperand } |
+ *   { p: 'refCmp', op: 'eq' | 'ne' | 'lt' | 'le' | 'gt' | 'ge',
+ *     left: PlanRef, right: PlanRef } |
  *   { p: 'typeIs', ref: PlanRef, types: string[], positive: boolean } |
  *   { p: 'strop', kind: 'starts' | 'ends' | 'contains',
  *     ref: PlanRef, operand: PlanOperand } |
  *   { p: 'const', value: boolean } |
  *   { p: 'udf', name: string, key: string } |
  *   { p: 'bboxOverlap', columns: { w: string, s: string, e: string,
- *     n: string }, probe: { box: number[] } | { ext: string } } |
+ *     n: string }, probe: { box: number[] } | { ext: string } |
+ *     { circle: { centre: { external: string } | { literal: unknown },
+ *       radius: { external: string } | { literal: unknown } } } } |
  *   { p: 'cellIn', column: string, cells: string[], keepEmpty?: boolean } |
  *   { p: 'cellPrefix', column: string, prefix: string } |
  *   { p: 'interval', columns: { start: string, end: string },
@@ -123,7 +127,8 @@ export const PLAN_VERSION = 2;
  *   aggregates: { as: string, fn: 'rows' | 'sum' | 'avg' | 'min' | 'max',
  *     ref: PlanRef | null, empty: 'zero' | 'omit' | 'null' }[],
  *   tree: PlanProjectionNode,
- *   order: 'first-seen' | { index: number, desc: boolean, nullsFirst: boolean }[]
+ *   order: 'first-seen' | { index?: number, aggregate?: number,
+ *     desc: boolean, nullsFirst: boolean }[]
  * }} PlanGroup
  *   The GENERAL `GROUP BY`: one key per declared grouping name, the
  *   closed aggregate set over the group's rows, and the projection tree
@@ -133,7 +138,8 @@ export const PLAN_VERSION = 2;
  *   an `agg` node reads one aggregate under its `empty` rule. `order` is
  *   `'first-seen'`, the engine's own order of first appearance, or the
  *   group-key ordering an `$orderby` declared. A plan carrying a group
- *   carries no `bucket`, no `aggregate` and no `rank`.
+ *   carries no `bucket` or `rank`. A `count` aggregate may wrap a
+ * singleton group constructor, counting groups through a subquery.
  *
  * @typedef {{ ref: PlanRef, every: number, origin: number, as: string,
  *   order: 'asc' | 'desc' | 'first-seen',
@@ -329,7 +335,23 @@ export function planOrder(plan) {
   if (plan === null || plan === undefined) return null;
   if (plan.alg === 'entity-select' || plan.alg === 'entity-join') {
     if (plan.aggregate !== null) return null;
-    return effectiveOrder(plan.order, { bindings: plan.bindings.map((b) => b.name) });
+    const bindings = plan.bindings;
+    const ties = bindings.flatMap((binding) => binding.keys === undefined
+      ? [identityTerm(binding.name)] : binding.keys.map((column) => ({
+        source: 'column', binding: binding.name, column, path: null,
+        desc: false, nullsFirst: true, tieBreaker: true,
+      })));
+    if (plan.group) {
+      const group = plan.group;
+      const terms = group.order === 'first-seen' ? [] : group.order.map((term) => ({
+        source: 'group', binding: bindings[0].name,
+        column: term.aggregate === undefined ? group.keys[term.index].as : `a${term.aggregate}`,
+        path: null, desc: term.desc, nullsFirst: term.nullsFirst, tieBreaker: false,
+      }));
+      return [...terms, ...ties.map((term) => ({ ...term, source: 'group',
+        column: term.column, tieBreaker: group.order !== 'first-seen' }))];
+    }
+    return [...(plan.order ?? []).map((term) => declaredTerm(term, term.binding)), ...ties];
   }
   if (plan.aggregate !== null || plan.rank !== null) return null;
   if (plan.bucket !== null) {