@coradb/coradb-sqlsyntaxchecker-wasm 0.3.3

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## 0.3.3 (2026-11-04)
+
+- Documentation only: the README, the changelog and a code comment no longer refer to other projects or to a local setup. The module, the code and the API are the same as in 0.3.2.
+
+## 0.3.2 (2026-11-04)
+
+- **Renamed to `@coradb/coradb-sqlsyntaxchecker-wasm`** and published on npm as a public package of the `coradb` organization (`npm install @coradb/coradb-sqlsyntaxchecker-wasm`). Imports change accordingly; the module and API do not.
+- **`checkSql()` and `validateSql()` use a fresh checker for each call**, made from the module compiled once, as the README recommends. `createSqlChecker()` also takes a compiled `WebAssembly.Module` (a new checker then costs about a millisecond).
+- **Fixed: `describeError()` said "unexpected the end of the statement"**; it now says "Syntax error: unexpected end of the statement."
+- **Fixed: a `[quoted name]` left open** was marked at the end of the text with nothing to mark; it is now marked from its bracket.
+- Docs: README rewritten around using the package (it now includes what was in `Install-CoraDB-SQLSyntaxChecker-Wasm.md`, which is gone); `CLAUDE.md` added for working on the package.
+- `build/generate.mjs`: a `//` comment inside a grammar action can no longer upset the brace count (the generated sources, and the module, are unchanged).
+- **Fixed: names were not checked in longer texts, without a word.** The module kept at most 16,384 events (where the tables, columns and functions are); past that, `validate()` skipped every name check and returned `[]`. About 2,000 short statements, or an INSERT of about 16,000 rows, were enough. The buffer now grows with the text; if memory runs out, `validate()` throws instead of answering.
+- **Fixed: a setting given as `undefined` or `null` was taken as `false`.** `{ noBackslashEscapes: undefined }` turned backslash escapes on. Such a setting now keeps the default.
+- **Fixed: with backslash escapes on** (`noBackslashEscapes: false`), an escaped quote (`'it\'s'`) ended a string when counting an INSERT row's values or a call's arguments, which gave false "wrong number of values" reports; and an open string was marked from the wrong quote.
+- **Fixed: a long token took time in proportion to the square of its length.** A 20 MB string literal did not finish in minutes; it now takes well under a second. (The lexer read the text 8 KB at a time and moved a long token back at every read; it now reads as much as its buffer holds.)
+- **Fixed: a NUL character (U+0000) ended the text.** Whatever came before it was checked and the rest ignored, so `select 1` + NUL + anything was valid. It is now reported as an error at the NUL.
+- **Fixed: a schema document with a synonym that leads back to itself** made `validate()` throw (stack overflow); columns, synonyms, serials or procedures without a `name` made it throw a TypeError. They are now let through or left out.
+- `validate(sql, null)` no longer throws; `validate()` on long scripts is much faster (each statement's events are found once, not searched for).
+- The module's WASI stand-ins: output, which the module never writes, is now reported as written in full (the C library retries a write that wrote nothing, which would have looped for ever), and a module that ends itself (`proc_exit`) has its instance replaced like one that traps. `builtin()` checks for memory too.
+- `tools/coradbSchema.ts`: ENUM values and the element types of SET/MULTISET/LIST columns are read with the table's owner, so two owners' tables of the same name no longer get each other's.
+- `build-info.json` now records the WASI SDK version (`wasiSdk`; 0.2.1's notes said it did, but it did not), and `source` is written the same way (`tesseractdb-develop\src\parser`) on every system. The build checks that `WASI_SDK_PATH` has a clang and that `CHECK_STACK_SIZE` is a sensible number.
+- `schema-check.js`: `EV`, `nameParts` and `countItems`, which no one outside could reach, are no longer exported.
+- Docs: README "Install" (releases, a clone); the synonyms exception to "missing means not known" in README and `index.d.ts`; comments in `check.c` and `generate.mjs`.
+- The module was rebuilt from the same engine grammar and lexer (same SHA-256 as 0.3.1). Its exports are unchanged.
+
+## 0.3.1 (2026-10-30)
+
+- **This package is now the single home of the checker.** Its build (`build/generate.mjs`, `check.c`, `shim.h`, `build.mjs`) is the maintained copy.
+- No change to the module, its exports or the JavaScript API: `coradb-sqlsyntaxchecker.wasm` is the same as in 0.3.0.
+- **License: MIT throughout.** `package.json`, `README.md`, `NOTICE` and the install guide said Apache-2.0; they now agree with `LICENSE` (MIT).
+
+## 0.3.0 (2026-10-30)
+
+- **Fixed: a stray word after an expression was accepted**, e.g. `ORDER BY total DESCx` or `GROUP BY a foo`.
+  - The engine's grammar has a rule that matches an expression followed by a word only to refuse it: its action raises "invalid relational operator". The checker drops the engine's actions, so that refusal was lost.
+  - The build now finds rules whose action does nothing but raise a syntax error and makes the checker report it, at the stray word, with the engine's message. Today that is this one rule; any the engine adds are picked up the same way.
+  - `describeError` words it as `Syntax error: unexpected "DESCx" (invalid relational operator).`
+
+## 0.2.1 (2026-10-20)
+
+- **Fixed: memory damage that carried over between checks.**
+  - The module's C stack was the WASI SDK's default 64 KB. The engine's GLR parser overran it on some graph queries and wrote over the module's static data and heap.
+  - Later checks on the same checker then crashed with "memory access out of bounds" or returned wrong results (an error with a garbage message for valid SQL).
+  - The fix: the stack is now 4 MB and placed first in memory (`-Wl,--stack-first`), so running past it traps immediately instead of overwriting data.
+- **Fixed: "memory exhausted" on long statements the engine parses**, e.g. a MATCH of 40 patterns. The checker now uses the engine's YYMAXDEPTH (1000000) instead of bison's default (10000).
+- **A statement nested too deeply now throws an Error.** This covers both the module's stack and the JavaScript engine's. The checker replaces its WebAssembly instance and goes on working.
+- **Name checks:**
+  - names created by `CREATE VERTEX TABLE` / `CREATE EDGE TABLE` in the same script are known;
+  - `DROP … IF EXISTS` is not reported when the object is missing;
+  - variables of `list_comp(x IN …)` / `reduce(acc = …, x IN …)` are not taken for columns.
+- **README:** creating a fresh checker for every check is now the recommended way, with the reasons why.
+- **build-info.json** records the stack size and the WASI SDK version.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ApsiswareDB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,14 @@
+CoraDB-SQLSyntaxChecker-Wasm
+
+This product includes software developed as part of the CoraDB engine:
+  Copyright 2008 Search Solution Corporation
+  Copyright 2016 CoraDB Corporation
+CoraDB is a registered trademark of CoraDB Corporation.
+
+coradb-sqlsyntaxchecker.wasm is compiled from the engine's SQL grammar (src/parser/
+corasql_grammar.y) and lexer (src/parser/corasql_lexer.l), licensed under
+the MIT License. They were modified for this package: the
+grammar's C actions were replaced by hooks that only report where a
+statement's names are, nothing being built from it; the built-in function
+table and its argument checks were turned into a lookup table; and the lexer
+was given a stand-in for the parser context it uses. See build/generate.mjs.

package/README-schema.md

@@ -0,0 +1,362 @@
+# The CoraDB schema document
+
+A JSON document that describes what a CoraDB database defines: its tables,
+views, node and edge classes, their columns, keys, indexes and comments, its
+stored procedures and functions, serials and synonyms.
+
+It is read from the database's catalog only. It never holds data from the
+tables: no rows, no counts, no sample values.
+
+It has two uses:
+
+- **Checking SQL.** `validate(sql, { schema })` in this package looks up the
+  names a statement uses in it.
+- **Describing the database** to a person or to an AI, for example as context
+  for writing queries. The comments and keys are there for that.
+
+The rules of the format are also in machine-readable form: `schema.json` (JSON
+Schema, draft 2020-12) to validate a document, and the `CoraDbSchema` types in
+`index.d.ts` for TypeScript.
+
+## Contents
+
+- [Rules that apply everywhere](#rules-that-apply-everywhere)
+- [The document](#the-document)
+- [Objects](#objects)
+- [Columns](#columns)
+- [Keys and indexes](#keys-and-indexes)
+- [Procedures and functions](#procedures-and-functions)
+- [Serials](#serials)
+- [Synonyms](#synonyms)
+- [A complete example](#a-complete-example)
+- [Making a document](#making-a-document)
+- [How the checker uses each part](#how-the-checker-uses-each-part)
+- [Versions](#versions)
+
+## Rules that apply everywhere
+
+- **Missing means "not known".** Every part except `format`, `version` and
+  `objects` is optional. A list or field that is left out means the producer
+  did not know it, never that there are none. An empty list (`[]`) means
+  "there are none". The checker never reports anything against a part that is
+  missing — with one exception: without `synonyms`, a table name is looked up
+  among the objects only.
+- **Names are matched without regard to case**, as the engine does: `Orders`,
+  `orders` and `"ORDERS"` are the same object. Names are written as the
+  catalog spells them, without quotes.
+- **Owners.** In CoraDB every object belongs to a user. Where an object or a
+  reference to one has an owner, it is given in `owner`, or as `owner.name` in
+  fields that point to another object (`under`, `references`, `target`). A
+  name without an owner matches that name under any owner.
+- **Comments** are `null` when the catalog has none, and left out when the
+  producer could not read them.
+- **Types** are written as CoraDB names them, in upper case: `INTEGER`,
+  `BIGINT`, `SMALLINT`, `NUMERIC`, `FLOAT`, `DOUBLE`, `VARCHAR`, `CHAR`,
+  `NCHAR`, `BIT`, `VARBIT`, `DATE`, `TIME`, `DATETIME`, `TIMESTAMP`, `ENUM`,
+  `SET`, `MULTISET`, `LIST`, `JSON`, `BLOB`, `CLOB`, `OBJECT`… A size is never
+  part of the type: it is in `length`, `precision` and `scale`.
+- **Unknown fields** are allowed, so that a producer can add its own; readers
+  ignore what they do not know.
+
+## The document
+
+```json
+{
+  "format": "coradb-schema",
+  "version": 1,
+  "database": "shop",
+  "objects": [],
+  "procedures": [],
+  "serials": [],
+  "synonyms": []
+}
+```
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `format` | `"coradb-schema"` | yes | Says what the document is. |
+| `version` | `1` | yes | The version of this format. |
+| `database` | string | no | The database's name, for display. |
+| `objects` | array of [objects](#objects) | yes | Tables, views, node classes and edge classes. |
+| `procedures` | array of [procedures](#procedures-and-functions) | no | Stored procedures and functions. |
+| `serials` | array of [serials](#serials) | no | Serials (sequences), not counting the ones behind AUTO_INCREMENT columns. |
+| `synonyms` | array of [synonyms](#synonyms) | no | Synonyms. |
+
+## Objects
+
+```json
+{
+  "name": "orders",
+  "owner": "dba",
+  "kind": "table",
+  "comment": "One row per customer order",
+  "under": [],
+  "columns": [ … ],
+  "primaryKey": ["id"],
+  "unique": [ … ],
+  "foreignKeys": [ … ],
+  "indexes": [ … ]
+}
+```
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `name` | string | yes | The object's name. |
+| `owner` | string | no | The user that owns it. |
+| `kind` | `"table"`, `"view"`, `"node"`, `"edge"` | yes | What it is: a table, a view, a graph node class (vertex) or a graph edge class. |
+| `comment` | string or null | no | The object's comment. |
+| `under` | array of strings | no | The classes it inherits from (`CREATE … UNDER`), as `owner.name` or `name`. It has their columns as well as its own. |
+| `columns` | array of [columns](#columns) | no | Its columns, in table order. Left out when they could not be read: then any column name is accepted. |
+| `primaryKey` | array of strings | no | The columns of the primary key, in key order; `[]` when there is none. |
+| `unique` | array | no | Unique keys: `{ "name": …, "columns": [ … ] }` each. |
+| `foreignKeys` | array of [foreign keys](#keys-and-indexes) | no | Its foreign keys. |
+| `indexes` | array of [indexes](#keys-and-indexes) | no | Its secondary indexes, the unique ones included; not the primary key or the foreign keys' own indexes. |
+| `definition` | string | no | Views only: the SELECT the view is defined by. |
+
+The partitions of a partitioned table are not listed as objects: they are the
+table.
+
+## Columns
+
+```json
+{ "name": "total", "type": "NUMERIC", "precision": 12, "scale": 2,
+  "nullable": false, "default": "0", "comment": "Including VAT, in EUR" }
+```
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `name` | string | yes | The column's name. |
+| `type` | string | yes | Its type, without sizes (see [Rules](#rules-that-apply-everywhere)). |
+| `length` | integer | no | Character and bit types: the declared length. Left out when there is no limit (a VARCHAR declared without one). |
+| `precision` | integer | no | NUMERIC: total digits. |
+| `scale` | integer | no | NUMERIC: digits after the point. |
+| `values` | array of strings | no | ENUM: the values it allows, in order. |
+| `elementType` | string | no | SET, MULTISET and LIST: the type of their elements. |
+| `nullable` | boolean | no | Whether it takes NULL. |
+| `default` | string or null | no | The default as SQL text: `'RO'` (a string, quotes included), `0`, `SYS_DATETIME`. `null` when there is none. |
+| `autoIncrement` | boolean | no | `true` for an AUTO_INCREMENT column. |
+| `comment` | string or null | no | The column's comment. |
+
+Examples of types:
+
+| Declared as | Written as |
+|---|---|
+| `INT` | `{ "type": "INTEGER" }` |
+| `VARCHAR(100)` | `{ "type": "VARCHAR", "length": 100 }` |
+| `VARCHAR` / `STRING` | `{ "type": "VARCHAR" }` |
+| `CHAR(2)` | `{ "type": "CHAR", "length": 2 }` |
+| `NUMERIC(12,2)` | `{ "type": "NUMERIC", "precision": 12, "scale": 2 }` |
+| `ENUM('new','paid')` | `{ "type": "ENUM", "values": ["new", "paid"] }` |
+| `SET OF VARCHAR(20)` | `{ "type": "SET", "elementType": "VARCHAR" }` |
+
+## Keys and indexes
+
+A foreign key:
+
+```json
+{ "name": "fk_orders_customer", "columns": ["customer_id"],
+  "references": "dba.customers", "refColumns": ["id"],
+  "onDelete": "CASCADE", "onUpdate": "RESTRICT" }
+```
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `name` | string | yes | The constraint's name. |
+| `columns` | array of strings | yes | Its columns in this object, in order. |
+| `references` | string | yes | The object it points to, as `owner.name`, or `name` when the owner is not known. Empty when the target could not be read. |
+| `refColumns` | array of strings | yes | The columns it points to, in the same order as `columns`. |
+| `onDelete`, `onUpdate` | string | no | `CASCADE`, `RESTRICT`, `NO ACTION` or `SET NULL`. Left out when not known. |
+
+An index:
+
+```json
+{ "name": "idx_orders_status", "columns": ["status"], "unique": false, "comment": null }
+```
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `name` | string | yes | The index's name. |
+| `columns` | array of strings | yes | Its columns, in key order. An index on an expression has none listed for that part. |
+| `unique` | boolean | yes | Whether it is unique. |
+| `comment` | string or null | no | The index's comment. |
+
+## Procedures and functions
+
+```json
+{ "name": "calc_tax", "owner": "dba", "kind": "function", "returns": "NUMERIC",
+  "comment": "VAT for an amount, by country",
+  "params": [
+    { "name": "amount", "type": "NUMERIC", "mode": "IN" },
+    { "name": "country", "type": "CHAR", "mode": "IN", "comment": "ISO 3166 code" }
+  ] }
+```
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `name` | string | yes | Its name. |
+| `owner` | string | no | The user that owns it. |
+| `kind` | `"procedure"`, `"function"` | yes | A function returns a value and is used in expressions; a procedure is run with `CALL`. |
+| `returns` | string | no | Functions only: the type it returns. |
+| `comment` | string or null | no | Its comment. |
+| `params` | array | no | Its parameters, in order. Left out when not known. |
+
+Each parameter:
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `name` | string | yes | The parameter's name. |
+| `type` | string | yes | Its type. |
+| `mode` | `"IN"`, `"OUT"`, `"INOUT"` | yes | Which way the value goes. |
+| `comment` | string or null | no | Its comment. |
+
+## Serials
+
+```json
+{ "name": "order_no", "owner": "dba", "comment": "Printed order numbers" }
+```
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `name` | string | yes | Its name, as used in `order_no.NEXT_VALUE`. |
+| `owner` | string | no | The user that owns it. |
+| `comment` | string or null | no | Its comment. |
+
+The serials the engine makes for AUTO_INCREMENT columns are not listed: the
+columns are marked `"autoIncrement": true` instead.
+
+## Synonyms
+
+```json
+{ "name": "o", "owner": "dba", "target": "dba.orders", "comment": null }
+```
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `name` | string | yes | The synonym. |
+| `owner` | string | no | The user that owns it. |
+| `target` | string | yes | What it stands for, as `owner.name`. |
+| `comment` | string or null | no | Its comment. |
+
+## A complete example
+
+```json
+{
+  "format": "coradb-schema",
+  "version": 1,
+  "database": "shop",
+  "objects": [
+    {
+      "name": "customers", "owner": "dba", "kind": "table",
+      "comment": "People and companies that place orders",
+      "columns": [
+        { "name": "id", "type": "INTEGER", "nullable": false, "default": null, "autoIncrement": true, "comment": null },
+        { "name": "name", "type": "VARCHAR", "length": 100, "nullable": false, "default": null, "comment": "Full name" },
+        { "name": "country", "type": "CHAR", "length": 2, "nullable": true, "default": "'RO'", "comment": "ISO 3166 code" },
+        { "name": "kind", "type": "ENUM", "values": ["person", "company"], "nullable": false, "default": null, "comment": null }
+      ],
+      "primaryKey": ["id"],
+      "unique": [ { "name": "u_customers_name", "columns": ["name"] } ],
+      "foreignKeys": [],
+      "indexes": [ { "name": "u_customers_name", "columns": ["name"], "unique": true, "comment": null } ]
+    },
+    {
+      "name": "orders", "owner": "dba", "kind": "table",
+      "comment": "One row per customer order",
+      "columns": [
+        { "name": "id", "type": "INTEGER", "nullable": false, "default": null, "autoIncrement": true, "comment": null },
+        { "name": "customer_id", "type": "INTEGER", "nullable": false, "default": null, "comment": null },
+        { "name": "total", "type": "NUMERIC", "precision": 12, "scale": 2, "nullable": false, "default": "0", "comment": "Including VAT, in EUR" },
+        { "name": "created", "type": "DATETIME", "nullable": false, "default": "SYS_DATETIME", "comment": null }
+      ],
+      "primaryKey": ["id"],
+      "unique": [],
+      "foreignKeys": [
+        { "name": "fk_orders_customer", "columns": ["customer_id"], "references": "dba.customers", "refColumns": ["id"], "onDelete": "RESTRICT", "onUpdate": "RESTRICT" }
+      ],
+      "indexes": [ { "name": "idx_orders_created", "columns": ["created"], "unique": false, "comment": null } ]
+    },
+    {
+      "name": "big_orders", "owner": "dba", "kind": "view", "comment": "Orders over 1000 EUR",
+      "definition": "SELECT id, customer_id, total FROM orders WHERE total > 1000",
+      "columns": [
+        { "name": "id", "type": "INTEGER", "nullable": true, "default": null, "comment": null },
+        { "name": "customer_id", "type": "INTEGER", "nullable": true, "default": null, "comment": null },
+        { "name": "total", "type": "NUMERIC", "precision": 12, "scale": 2, "nullable": true, "default": null, "comment": null }
+      ]
+    },
+    {
+      "name": "viewer", "owner": "dba", "kind": "node", "comment": "A registered viewer",
+      "columns": [ { "name": "id", "type": "INTEGER", "nullable": false }, { "name": "name", "type": "VARCHAR", "length": 100 } ],
+      "primaryKey": ["id"]
+    },
+    {
+      "name": "rated", "owner": "dba", "kind": "edge", "comment": "A viewer rated a movie",
+      "columns": [ { "name": "stars", "type": "SMALLINT", "nullable": true } ]
+    }
+  ],
+  "procedures": [
+    { "name": "calc_tax", "owner": "dba", "kind": "function", "returns": "NUMERIC", "comment": "VAT for an amount, by country",
+      "params": [ { "name": "amount", "type": "NUMERIC", "mode": "IN", "comment": null },
+                  { "name": "country", "type": "CHAR", "mode": "IN", "comment": null } ] },
+    { "name": "close_month", "owner": "dba", "kind": "procedure", "comment": null,
+      "params": [ { "name": "month", "type": "DATE", "mode": "IN", "comment": null } ] }
+  ],
+  "serials": [ { "name": "order_no", "owner": "dba", "comment": "Printed order numbers" } ],
+  "synonyms": [ { "name": "o", "owner": "dba", "target": "dba.orders", "comment": null } ]
+}
+```
+
+## Making a document
+
+`tools/coradbSchema.ts` reads it from a live database. It is one
+self-contained file, meant to be copied into an app's server. It works with
+any driver: give it a function that runs a query and returns the rows as
+objects keyed by lower-cased column name.
+
+```ts
+import { readCoraDbSchema } from './coradbSchema';
+
+const schema = await readCoraDbSchema(async (sql) => {
+  const r = await conn.query(sql);
+  return r.rows.map((row) => Object.fromEntries(r.columns.map((c, i) => [c.toLowerCase(), row[i]])));
+});
+```
+
+It reads the catalog views — `db_class`, `db_attribute`,
+`db_attr_setdomain_elm`, `db_direct_super_class`, `db_index`,
+`db_index_key`, `db_partition`, `db_vclass`, `db_serial`,
+`db_stored_procedure`, `db_stored_procedure_args`, `db_synonym` — plus
+`SHOW CREATE TABLE` for tables with foreign keys (where they point is only in
+the DDL) and `SHOW COLUMNS` for tables with ENUM columns (for their values).
+Engine builds differ in which catalog columns they have, so each read tries
+the fullest form first and falls back to plainer ones; a part that cannot be
+read at all is left out of the document.
+
+It lists what the connection's user can see. System classes (the engine's own
+catalog) are left out.
+
+A document can also be written by hand, or by another program: only `format`,
+`version` and `objects` with each object's `name` and `kind` are required.
+
+## How the checker uses each part
+
+| Part | What it lets `validate()` check | Without it |
+|---|---|---|
+| `objects` | That tables, views, node and edge classes exist; that a MATCH node label is a node class and an edge label an edge class. | — (required) |
+| `columns` | That columns exist; ambiguous column names; INSERT column lists; how many values an INSERT row needs. | Any column of that object is accepted. |
+| `under` | Inherited columns. | — |
+| `procedures` | That called functions and procedures exist; how many arguments they take; a procedure used where a value is needed. | Function names that are not built-in are not checked. |
+| `serials` | That `name.NEXT_VALUE` and `name.CURRENT_VALUE` name a serial. | Serials are not checked. |
+| `synonyms` | That a synonym used as a table name stands for an existing object. | A name only a synonym would explain is reported as unknown. |
+| comments, keys, indexes, `definition`, types | Nothing: they are there to describe the database. | — |
+
+The built-in functions, the system catalog classes (`db_*`) and the
+pseudo-columns (`ROWNUM`, `LEVEL`, …) belong to the engine, not to a database,
+so they are not in the document: the checker knows them itself.
+
+## Versions
+
+`version` is raised only when a change would make an older reader
+misunderstand a document: a field changing its meaning, or a new required
+field. Adding an optional field does not change the version; readers ignore
+fields they do not know.