jspg checkpoint

GEMINI.md

@@ -47,7 +47,22 @@ The core execution engines natively enforce these boundaries:
 *   **Merger**: Strictly bounded to the `Type` Realm. It is philosophically impossible and mathematically illegal to attempt to UPSERT an API endpoint.
 *   **Queryer**: Routes recursively. Safely evaluates API boundary inputs directly from the `Punc` realm, while tracing underlying table targets back through the `Type` realm to physically compile SQL `SELECT` statements.
 
-### Types of Types
+### Basic and Structural Types
+JSPG models data using a simplified subset of standard JSON Schema types, categorized into primitives and structural types:
+
+*   **Primitives**: 
+    *   `string`: Standard string, supporting standard keywords (e.g., `pattern`, `minLength`, `maxLength`) and custom formats (`uuid`, `date-time`, `email`). Empty strings (`""`) are leniently treated as "present but unset".
+    *   `number` & `integer`: Numeric and integer values (e.g., supporting `minimum`, `maximum`).
+    *   `boolean`: Boolean `true` or `false` values.
+    *   `null`: Represents database `NULL` or unset fields.
+*   **Structural Types**:
+    *   `object`: Represents a structured object with a fixed list of static `properties`. Objects are **strict by default** (raising `STRICT_PROPERTY_VIOLATION` for properties not defined in the schema) unless marked with `"extensible": true`.
+    *   `array`: A homogeneous, one-dimensional collection where every element is validated against the `items` schema. Positional/tuple array validation is not supported, and array strictness checks do not apply.
+    *   `dict`: A dynamic key-value map. It utilizes the `keys` keyword to validate key strings (typically via `pattern`) and the `items` keyword to validate the values. It completely replaces the legacy `additionalProperties` and `patternProperties` keywords. Extensibility is implicitly managed via dynamic keys, so strictness checking does not apply.
+
+### Types of Types (Complex & Referential Types)
+Beyond basic primitives and structures, JSPG maps schemas to their storage and database-referential boundaries:
+
 *   **Table-Backed (Entity Types)**: Primarily defined in root `types` schemas. These represent physical Postgres tables.
     *   They are implicitly registered in the Global Registry using their precise key name mapped from the database compilation phase.
     *   The schema conceptually requires a `type` discriminator at runtime so the engine knows what physical variation to interact with.
@@ -162,9 +177,11 @@ It evaluates as an **Independent Declarative Rules Engine**. Every `Case` block
 ```
 
 ### Strict by Default & Extensibility
-*   **Strictness**: By default, any property not explicitly defined in the schema causes a validation error (effectively enforcing `additionalProperties: false` globally). 
-*   **Extensibility (`extensible: true`)**: To allow a free-for-all of undefined properties, schemas must explicitly declare `"extensible": true`. 
-*   **Structured Additional Properties**: If `additionalProperties: {...}` is defined as a schema, arbitrary keys are allowed so long as their values match the defined type constraint.
+*   **Strictness**: Strictness is a first-class feature for object schemas. By default, any property present in the JSON instance that is not explicitly defined in the schema's `properties` (or inherited, etc.) causes a `STRICT_PROPERTY_VIOLATION` validation error.
+*   **Extensibility (`extensible: true`)**: This keyword is valid **only** at the `type: "object"` level. By setting `"extensible": true`, you bypass the strictness checking on the object, allowing arbitrary undefined properties to pass.
+*   **Type: dict and type: array**: These types are dynamic/homogeneous:
+    *   **`dict`**: Defined with `keys` and `items` schemas. Its keys and values are dynamic, so strictness checking does not apply. `"extensible"` is not applicable at the `dict` level.
+    *   **`array`**: Homogeneous collection of items matching the `items` schema. Validation is homogeneous, so strictness checking does not apply. `"extensible"` is not applicable at the `array` level (tuple-like `prefixItems` are removed).
 *   **Inheritance Boundaries**: Strictness resets when crossing non-primitive `type` boundaries. A schema extending a strict parent remains strict unless it explicitly overrides with `"extensible": true`.
 
 ### Format Leniency for Empty Strings
@@ -206,7 +223,7 @@ Traits are reusable, non-generating schema fragments used to share properties an
     }
     ```
 *   **Resolution and Merging**: During `Database::new()`, includes are resolved and merged at the raw JSON level:
-    *   **`properties` / `patternProperties`**: Map keys from the host schema override/shadow included traits.
+    *   **`properties`**: Map keys from the host schema override/shadow included traits.
     *   **`required` / `display`**: Lists are merged and deduped.
     *   **`dependencies`**: Merged by combining and deduping lists.
     *   **Scalars / Arrays / Items**: Host definitions completely override included traits.