@xdbml/parse 0.3.2 → 0.5.0

package/dist/ast.d.ts

@@ -38,7 +38,7 @@ export interface ExperimentalDeclaration {
     features: string[];
     span: Span;
 }
-export type TopLevelStatement = ProjectDeclaration | ContainerDeclaration | EntityDeclaration | TypeDeclaration | EdgeDeclaration | ViewDeclaration | EnumDeclaration | RefDeclaration | TablePartialDeclaration | TableGroupDeclaration | NoteDeclaration | TopLevelRecordsDeclaration | ModuleImportDirective;
+export type TopLevelStatement = ProjectDeclaration | ContainerDeclaration | EntityDeclaration | TypeDeclaration | EdgeDeclaration | ViewDeclaration | EnumDeclaration | RefDeclaration | TablePartialDeclaration | TableGroupDeclaration | SupertypeGroupDeclaration | NoteDeclaration | TopLevelRecordsDeclaration | ModuleImportDirective;
 export interface ProjectDeclaration {
     kind: 'ProjectDeclaration';
     name: string;
@@ -182,7 +182,7 @@ export interface TypeDeclaration {
     kind: 'TypeDeclaration';
     name: string;
     /**
-     * v0.2 scalar form (spec §14.7): when present, this Type is an alias
+     * v0.2 scalar form (spec §15.7): when present, this Type is an alias
      * for the given type expression rather than an object-shaped record.
      * Examples:
      *
@@ -339,6 +339,21 @@ export interface TableGroupDeclaration {
     members: string[];
     span: Span;
 }
+export interface SupertypeGroupDeclaration {
+    kind: 'SupertypeGroupDeclaration';
+    name: string;
+    settings: Setting[];
+    members: SupertypeGroupMember[];
+    span: Span;
+}
+export interface SupertypeGroupMember {
+    kind: 'SupertypeGroupMember';
+    /** Entity path as written: `Person` or `crm.Person`. */
+    name: string;
+    /** Member settings; `strategy` is the only recognized one (spec §12.7.4). */
+    settings: Setting[];
+    span: Span;
+}
 export interface PartialInjection {
     kind: 'PartialInjection';
     /** Identifier after the `~`. */
@@ -385,7 +400,7 @@ export interface ModuleImportDirective {
     /**
      * Directive mode:
      *   - `'reuse'`: transitive (visible to files that further import this file).
-     *     The recommended default per spec §26.4.
+     *     The recommended default per spec §27.4.
      *   - `'use'`: non-transitive (private to this file).
      */
     mode: 'use' | 'reuse';
@@ -424,9 +439,10 @@ export type ImportSpec = {
  *     type Email as PII_Email
  *     field core.dim_customer.email
  *
- * The element type is one of the keywords from §26.3 (table, entity,
+ * The element type is one of the keywords from §27.3 (table, entity,
  * collection, record, enum, tablepartial, note, schema, container,
- * tablegroup, type, edge, view, diagramview, field). Stored lowercased.
+ * tablegroup, type, edge, view, diagramview, field, and from v0.5
+ * supertypegroup). Stored lowercased.
  *
  * The source path follows xDBML's standard dotted form. Container.Entity
  * for an entity inside a Container; Container.Entity.Field for a field.
@@ -447,7 +463,7 @@ export interface ImportItem {
  * an entity, type, container, etc. clone). Field imports are not supported
  * in P4 -- when they land, this type may grow to a wider union.
  *
- * Per spec §26.6, the clone contains exactly the imported declaration(s),
+ * Per spec §27.6, the clone contains exactly the imported declaration(s),
  * without surrounding wrappers from the source file. For an entity clone
  * the content is the EntityDeclaration alone (no container wrapper); for a
  * container clone the content is the ContainerDeclaration including its
@@ -459,7 +475,7 @@ export interface CloneBlock {
      * Statements that the importing file pulls in from the source. Most are
      * top-level shapes (Entity, Type, Enum, Container, etc.). The one
      * exception is `FieldDeclaration`: when the parent directive imports
-     * one or more fields via `field <path>` items (spec §26.8), each field
+     * one or more fields via `field <path>` items (spec §27.8), each field
      * appears here as a bare FieldDeclaration with no entity wrapper.
      * The `flatten()` pass lifts each bare field into a synthetic
      * TypeDeclaration at file scope so downstream consumers see a normal
@@ -545,7 +561,7 @@ export interface ParseOptions {
      * Because this reader is synchronous, a host that supports remote sources
      * must return the fetched text from a cache it populated beforehand. The
      * network fetch, and its SSRF / redirect / size / timeout obligations
-     * (spec §26.14.5), live in the host's resolver, not in the parser.
+     * (spec §27.14.5), live in the host's resolver, not in the parser.
      *
      * If absent, reference-only directives fall back to the P4 rejection
      * with a clear "no resolver available" message. Clone-block-bearing

package/dist/index.d.ts

@@ -27,11 +27,15 @@
 export * from './ast.ts';
 export { tokenize, TokenKind, LexError } from './lexer.ts';
 export type { Token } from './lexer.ts';
-export { parse, Parser, ParseError } from './parser.ts';
+export { parse, Parser, ParseError, SUPPORTED_XDBML_VERSION, compareVersions } from './parser.ts';
 export { flatten } from './module-resolver.ts';
 export { classifyModuleSource, isUrlKey, ModuleSourceError, } from './module-resolver.ts';
 export type { ModuleSource } from './module-resolver.ts';
 export { resolveNames, SymbolTable } from './name-resolver.ts';
+export { FOREIGN_MASTER_FLAG, checkRelationships, hasForeignMasterFlag, isForeignMaster, pathToString, refChildEndpoint, refParentEndpoint, relationshipType, versionAtLeast, CONSTRAINT_TYPES, V04_RELATIONSHIP_SETTINGS, constraintType, entityNames, isEntityLevelEndpoint, isUndirected, } from './relationships.ts';
+export type { RelationshipType, ConstraintType } from './relationships.ts';
+export { SUPERTYPE_GROUP_VALUES, canonicalSupertypeGroupValue, checkSupertypeGroups, resolveSupertypeGroups, subtypeStrategy, supertypeChains, supertypeGroupSettings, } from './supertypes.ts';
+export type { Completeness, Exclusivity, MaterializationStrategy, MergeOption, ResolvedSupertypeGroup, SupertypeGroupSettings, SupertypeGroupValueSetting, } from './supertypes.ts';
 export type { Diagnostic, DiagnosticCode, ResolutionResult, SymbolEntry, SymbolKind, } from './name-resolver.ts';
 export { xdbmlLanguageConfig, xdbmlMonarchTokensProvider, } from './monarch.ts';
 export type { XDbmlLanguageConfiguration, XDbmlMonarchLanguage, } from './monarch.ts';

package/dist/index.js

@@ -26,8 +26,10 @@
  */
 export * from "./ast.js";
 export { tokenize, TokenKind, LexError } from "./lexer.js";
-export { parse, Parser, ParseError } from "./parser.js";
+export { parse, Parser, ParseError, SUPPORTED_XDBML_VERSION, compareVersions } from "./parser.js";
 export { flatten } from "./module-resolver.js";
 export { classifyModuleSource, isUrlKey, ModuleSourceError, } from "./module-resolver.js";
 export { resolveNames, SymbolTable } from "./name-resolver.js";
+export { FOREIGN_MASTER_FLAG, checkRelationships, hasForeignMasterFlag, isForeignMaster, pathToString, refChildEndpoint, refParentEndpoint, relationshipType, versionAtLeast, CONSTRAINT_TYPES, V04_RELATIONSHIP_SETTINGS, constraintType, entityNames, isEntityLevelEndpoint, isUndirected, } from "./relationships.js";
+export { SUPERTYPE_GROUP_VALUES, canonicalSupertypeGroupValue, checkSupertypeGroups, resolveSupertypeGroups, subtypeStrategy, supertypeChains, supertypeGroupSettings, } from "./supertypes.js";
 export { xdbmlLanguageConfig, xdbmlMonarchTokensProvider, } from "./monarch.js";

package/dist/keywords.d.ts

@@ -33,13 +33,13 @@ export declare const ENTITY_KEYWORDS: readonly ["table", "entity", "collection",
  * The full set of declaration keywords. Includes containers,
  * entities, and other top-level constructs.
  */
-export declare const DECLARATION_KEYWORDS: readonly ["project", "container", "schema", "database", "keyspace", "namespace", "dataset", "bucket", "table", "entity", "collection", "record", "type", "edge", "view", "enum", "ref", "note", "tablepartial", "tablegroup", "diagramview"];
+export declare const DECLARATION_KEYWORDS: readonly ["project", "container", "schema", "database", "keyspace", "namespace", "dataset", "bucket", "table", "entity", "collection", "record", "type", "edge", "view", "enum", "ref", "note", "tablepartial", "tablegroup", "supertypegroup", "diagramview"];
 export declare const STRUCTURAL_TYPE_KEYWORDS: readonly ["object", "struct", "array", "list", "map", "dict", "dictionary", "set", "json", "jsonb", "variant"];
 export declare const POLYMORPHISM_KEYWORDS: readonly ["union", "oneof", "anyof", "allof"];
 export declare const SCALAR_TYPES: readonly ["tinyint", "smallint", "mediumint", "int", "integer", "bigint", "int32", "int64", "float", "double", "decimal", "dec", "numeric", "real", "bit", "bool", "boolean", "char", "varchar", "varchar2", "nvarchar", "nvarchar2", "nchar", "text", "mediumtext", "longtext", "string", "ntext", "binary", "varbinary", "blob", "mediumblob", "longblob", "tinyblob", "tinytext", "json", "jsonb", "variant", "xml", "date", "time", "datetime", "datetime2", "timestamp", "timestamptz", "year", "uuid", "inet6", "money", "smallmoney", "enum"];
 export declare const BSON_TYPES: readonly ["objectid", "decimal128", "bindata", "minkey", "maxkey", "symbol", "regex", "long", "double"];
-export declare const SETTING_FLAGS: readonly ["pk", "primary", "key", "unique", "null", "not", "required", "increment", "inactive"];
-export declare const SETTING_KEYS: readonly ["note", "default", "ref", "name", "color", "headercolor", "as", "check", "type", "target", "targets", "database_type", "source", "source_cardinality", "target_cardinality", "min_source", "max_source", "min_target", "max_target", "undirected", "discriminator", "source_query", "materialized", "refresh_schedule", "refresh_on", "source_database", "storage_options", "pattern", "format", "minlength", "maxlength", "minimum", "maximum", "exclusiveminimum", "exclusivemaximum", "multipleof", "minitems", "maxitems", "uniqueitems", "minproperties", "maxproperties", "synonyms", "business_term", "granularity", "tags", "delete", "update", "indexes", "checks", "replication", "location", "default_charset", "cloned_at"];
+export declare const SETTING_FLAGS: readonly ["pk", "primary", "key", "unique", "null", "not", "required", "increment", "inactive", "foreign_master"];
+export declare const SETTING_KEYS: readonly ["note", "default", "ref", "name", "color", "headercolor", "as", "check", "type", "target", "targets", "database_type", "source", "source_cardinality", "target_cardinality", "min_source", "max_source", "min_target", "max_target", "undirected", "source_role", "target_role", "source_verb", "target_verb", "constraint_type", "discriminator", "supertype", "completeness", "exclusivity", "strategy", "merge", "source_query", "materialized", "refresh_schedule", "refresh_on", "source_database", "storage_options", "pattern", "format", "minlength", "maxlength", "minimum", "maximum", "exclusiveminimum", "exclusivemaximum", "multipleof", "minitems", "maxitems", "uniqueitems", "minproperties", "maxproperties", "synonyms", "business_term", "granularity", "tags", "delete", "update", "indexes", "checks", "replication", "location", "default_charset", "cloned_at"];
 export declare const GRANULARITY_VALUES: readonly ["year", "quarter", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond"];
 export declare const DIRECTIVE_KEYWORDS: readonly ["xdbml", "experimental"];
 export declare const MODULE_KEYWORDS: readonly ["use", "reuse", "from", "as"];

package/dist/keywords.js

@@ -66,6 +66,7 @@ export const DECLARATION_KEYWORDS = [
     'note',
     'tablepartial',
     'tablegroup',
+    'supertypegroup',
     'diagramview',
 ];
 /* -------------------------------------------------------------------------
@@ -164,6 +165,7 @@ export const SETTING_FLAGS = [
     'required',
     'increment',
     'inactive', // v0.2 §11.9: Ref flag for visualization-only deactivation
+    'foreign_master', // v0.4 §11.10: Ref flag for denormalized replication
 ];
 export const SETTING_KEYS = [
     // General
@@ -188,7 +190,19 @@ export const SETTING_KEYS = [
     'min_target',
     'max_target',
     'undirected',
+    // v0.4 relationship documentation (spec 11.14, 11.15)
+    'source_role',
+    'target_role',
+    'source_verb',
+    'target_verb',
+    'constraint_type',
     'discriminator',
+    // v0.5 supertype groups (spec 12.2); `discriminator` is listed above
+    'supertype',
+    'completeness',
+    'exclusivity',
+    'strategy',
+    'merge',
     'source_query',
     'materialized',
     'refresh_schedule',

package/dist/module-resolver.d.ts

@@ -30,13 +30,13 @@ import type { CloneBlock, ModuleImportDirective, ParseOptions, XDbmlDocument } f
  *
  * Inside a Container body, each `ModuleImportDirective` is replaced by its
  * `clone.statements` as `ContainerBodyItem`s. Note that the spec table in
- * §26.6 guarantees that clone-block content for entity/edge/view/enum
+ * §27.6 guarantees that clone-block content for entity/edge/view/enum
  * imports is shape-compatible with `ContainerBodyItem`; other shapes
  * (e.g., a TablePartial clone inside a Container directive) would be
  * semantically invalid per the spec and would surface as a downstream
  * type error rather than being caught here.
  *
- * Field-level imports (spec §26.8) get a special transform: the clone
+ * Field-level imports (spec §27.8) get a special transform: the clone
  * block holds a bare `FieldDeclaration`, which `flatten()` lifts into a
  * synthetic `TypeDeclaration` at file scope. Downstream consumers see
  * a normal Named Type and can use it as a field type without learning
@@ -59,7 +59,7 @@ export type ParseFn = (source: string, options: ParseOptions, resolutionStack: R
  *   - `kind: 'resolved'`  -- the file was opened, parsed, and a clone
  *     block was synthesized
  *   - `kind: 'cycle'`     -- the resolution chain already contains this
- *     file; per spec §26.15 cycles are allowed, so we return an empty
+ *     file; per spec §27.15 cycles are allowed, so we return an empty
  *     clone block and let name resolution (P6+) handle the actual
  *     cross-file linking
  *   - `kind: 'no-resolver'` -- no `readFile` was supplied; caller should

package/dist/module-resolver.js

@@ -30,13 +30,13 @@ import { SCALAR_TYPES, BSON_TYPES } from "./keywords.js";
  *
  * Inside a Container body, each `ModuleImportDirective` is replaced by its
  * `clone.statements` as `ContainerBodyItem`s. Note that the spec table in
- * §26.6 guarantees that clone-block content for entity/edge/view/enum
+ * §27.6 guarantees that clone-block content for entity/edge/view/enum
  * imports is shape-compatible with `ContainerBodyItem`; other shapes
  * (e.g., a TablePartial clone inside a Container directive) would be
  * semantically invalid per the spec and would surface as a downstream
  * type error rather than being caught here.
  *
- * Field-level imports (spec §26.8) get a special transform: the clone
+ * Field-level imports (spec §27.8) get a special transform: the clone
  * block holds a bare `FieldDeclaration`, which `flatten()` lifts into a
  * synthetic `TypeDeclaration` at file scope. Downstream consumers see
  * a normal Named Type and can use it as a field type without learning
@@ -92,11 +92,11 @@ function flattenTopLevel(stmt, out) {
  *
  *   - For SCALAR fields (any TypeExpression that isn't ObjectType): the
  *     Type is in scalar form with `scalarBase = field.type`. Equivalent
- *     to the v0.2 scalar-Named-Type form (spec §14.7).
+ *     to the v0.2 scalar-Named-Type form (spec §15.7).
  *
  *   - For OBJECT-typed fields (`field foo object { ... }`): the Type is
  *     in object form with `body = field.type.fields`. Equivalent to the
- *     v0.1 object-Named-Type form (spec §14).
+ *     v0.1 object-Named-Type form (spec §15).
  *
  * Other type shapes (Array, Map, Set, Tuple, Union, polymorphic types)
  * are valid as `scalarBase` of a Type and pass through unchanged. The
@@ -225,7 +225,7 @@ export function resolveImport(directive, options, resolutionStack, depth, parseF
  * import spec. Applies aliases by renaming the extracted declaration.
  *
  * For `ImportAll`: every TopLevelStatement except ProjectDeclaration
- * (per spec §26.4, Project declarations cannot be imported).
+ * (per spec §27.4, Project declarations cannot be imported).
  *
  * For `ImportList`: each item is matched by element-type + source path.
  * Items not found in the source produce nothing (silent for P5; a
@@ -234,7 +234,7 @@ export function resolveImport(directive, options, resolutionStack, depth, parseF
 function extractImports(spec, sourceDoc) {
     if (spec.kind === 'ImportAll') {
         // ImportAll never matches field imports (the `*` form is for top-level
-        // declarations only per spec §26.2). Return the source's top-level
+        // declarations only per spec §27.2). Return the source's top-level
         // statements minus Project.
         return sourceDoc.statements
             .filter((s) => s.kind !== 'ProjectDeclaration')
@@ -248,7 +248,7 @@ function extractImports(spec, sourceDoc) {
             out.push(applyAlias(found, item));
         }
         // Silent skip on not-found. The spec leaves diagnostics to name
-        // resolution (§26.13). In practice, users notice missing entities
+        // resolution (§27.13). In practice, users notice missing entities
         // because their references downstream become unresolved.
     }
     return out;
@@ -276,6 +276,8 @@ function extractImports(spec, sourceDoc) {
  *       ViewDeclaration with matching name; supports dotted path.
  *   - 'tablegroup':
  *       TableGroupDeclaration with matching name (top-level only).
+ *   - 'supertypegroup':
+ *       SupertypeGroupDeclaration with matching name (top-level only, v0.5).
  *   - 'tablepartial':
  *       TablePartialDeclaration with matching name (top-level only).
  *   - 'note':
@@ -344,6 +346,12 @@ function findImportTarget(item, doc) {
     if (item.elementType === 'tablegroup') {
         return doc.statements.find((s) => s.kind === 'TableGroupDeclaration' && s.name === path);
     }
+    // SupertypeGroup (spec §12, v0.5): top-level only, bare name. The group
+    // comes with its membership; its entities resolve in the importing
+    // document, by import or declaration, like TableGroup members.
+    if (item.elementType === 'supertypegroup') {
+        return doc.statements.find((s) => s.kind === 'SupertypeGroupDeclaration' && s.name === path);
+    }
     if (item.elementType === 'tablepartial') {
         return doc.statements.find((s) => s.kind === 'TablePartialDeclaration' && s.name === path);
     }
@@ -403,7 +411,7 @@ function findImportTarget(item, doc) {
  * object types to find a FieldDeclaration in a referenced source document.
  * Returns undefined when any segment fails to resolve.
  *
- * Path shapes accepted (per spec §26.8):
+ * Path shapes accepted (per spec §27.8):
  *   - `entity.field`                    -- top-level entity
  *   - `container.entity.field`          -- container-qualified entity
  *   - `entity.field.sub`                -- nested via ObjectType
@@ -594,6 +602,8 @@ function applyAlias(stmt, item) {
             return { ...stmt, name: item.alias };
         case 'TableGroupDeclaration':
             return { ...stmt, name: item.alias };
+        case 'SupertypeGroupDeclaration':
+            return { ...stmt, name: item.alias };
         case 'TablePartialDeclaration':
             return { ...stmt, name: item.alias };
         case 'NoteDeclaration':
@@ -605,7 +615,7 @@ function applyAlias(stmt, item) {
     }
 }
 /* -------------------------------------------------------------------------
- * Module source classification (spec §26.14, "Remote module sources")
+ * Module source classification (spec §27.14, "Remote module sources")
  *
  * A `from` source is recognized purely by its scheme. A source beginning
  * with 'https://' is a remote (URL) source; anything else is a relative
@@ -617,7 +627,7 @@ function applyAlias(stmt, item) {
  * This is pure, synchronous classification. The actual network fetch is
  * delegated to ParseOptions.readFile (the host's resolver). The obligations
  * on a fetcher (SSRF defenses, https-only redirects, size and time limits)
- * live with that resolver, not here; see spec §26.14.5.
+ * live with that resolver, not here; see spec §27.14.5.
  * ----------------------------------------------------------------------- */
 /** Raised when a `from` source string is structurally disallowed. */
 export class ModuleSourceError extends Error {
@@ -687,7 +697,7 @@ export function classifyModuleSource(from) {
  *   - A remote (https) source resolves to its normalized href. No '.xdbml'
  *     is appended (a raw-content URL may carry a query string).
  *   - A relative source whose importer is itself a remote module resolves
- *     against the importer's base URL per RFC 3986 (spec §26.14.1). A remote
+ *     against the importer's base URL per RFC 3986 (spec §27.14.1). A remote
  *     module therefore can never reach the local filesystem.
  *   - A relative source with a local importer resolves on the filesystem,
  *     exactly as in v0.2.

package/dist/name-resolver.d.ts

@@ -1,5 +1,5 @@
 /**
- * Name resolution pass (spec §26.10 / §26.15, parser batch P6).
+ * Name resolution pass (spec §27.10 / §27.15, parser batch P6).
  *
  * `resolveNames(doc)` walks an xDBML document (the flattened view; clone
  * blocks have been merged) and produces:
@@ -67,7 +67,7 @@ export interface SymbolEntry {
  * Stable diagnostic code. Tooling can match on these to filter or style
  * messages without parsing the human-readable text.
  */
-export type DiagnosticCode = 'duplicate-declaration' | 'unresolved-type' | 'unresolved-entity' | 'unresolved-field' | 'unresolved-partial' | 'unresolved-tablegroup-member' | 'unresolved-records-entity' | 'unresolved-records-column' | 'empty-import' | 'invalid-nested-path';
+export type DiagnosticCode = 'duplicate-declaration' | 'unresolved-type' | 'unresolved-entity' | 'unresolved-field' | 'unresolved-partial' | 'unresolved-tablegroup-member' | 'unresolved-records-entity' | 'unresolved-records-column' | 'empty-import' | 'invalid-nested-path' | 'foreign-master-composite' | 'foreign-master-duplicate-child' | 'foreign-master-without-ref' | 'construct-requires-version' | 'ambiguous-ref-endpoint' | 'invalid-constraint-type' | 'constraint-type-on-foreign-master' | 'invalid-undirected' | 'entity-level-many-to-many' | 'missing-supertype' | 'unresolved-supertype-group-member' | 'invalid-supertype-group-value' | 'duplicate-subtype' | 'supertype-is-subtype' | 'subtype-in-multiple-groups' | 'supertype-cycle' | 'supertype-attribute-redeclared' | 'discriminator-on-overlapping-group' | 'merge-without-roll-up' | 'empty-supertype-group';
 /**
  * A single resolution diagnostic. Severity is currently always `error`,
  * but the field is included to leave room for future warnings (e.g.,

package/dist/name-resolver.js

@@ -1,5 +1,5 @@
 /**
- * Name resolution pass (spec §26.10 / §26.15, parser batch P6).
+ * Name resolution pass (spec §27.10 / §27.15, parser batch P6).
  *
  * `resolveNames(doc)` walks an xDBML document (the flattened view; clone
  * blocks have been merged) and produces:
@@ -40,6 +40,8 @@
  */
 import { SCALAR_TYPES, BSON_TYPES } from "./keywords.js";
 import { flatten } from "./module-resolver.js";
+import { checkRelationships } from "./relationships.js";
+import { checkSupertypeGroups } from "./supertypes.js";
 /**
  * Read-only handle on the collected symbol table.
  *
@@ -134,6 +136,10 @@ export function resolveNames(doc) {
     const symbols = new SymbolTable(entries);
     // Pass 2: resolve references.
     resolveReferences(flat, symbols, diagnostics);
+    // Pass 3: relationship rules that the grammar cannot express (spec 11.11).
+    diagnostics.push(...checkRelationships(flat));
+    // Pass 4: supertype group rules (spec 12.8).
+    diagnostics.push(...checkSupertypeGroups(flat));
     return { diagnostics, symbols };
 }
 /* -------------------------------------------------------------------------
@@ -507,8 +513,28 @@ function resolveRefSpec(endpoint, symbols, diagnostics) {
     else {
         maxEntityLen = leadingFields.length - 1;
     }
-    if (maxEntityLen < 1)
+    // An entity-level endpoint (spec 11.16) names an entity and stops there:
+    // `Customer`, or `shop.orders` for an entity inside a container. It is
+    // checked as a fallback rather than first, so an endpoint that already
+    // resolved as entity-plus-attribute keeps that reading and every document
+    // that parsed before this means what it meant before.
+    const wholePath = leadingFields.join('.');
+    const entityLevelMatch = (!hasComposite && !hasNonFieldTail)
+        ? resolveEntityRef(wholePath, symbols)
+        : undefined;
+    if (maxEntityLen < 1) {
+        // A single segment cannot be entity-plus-attribute, so it is either an
+        // entity-level endpoint or a reference to something undeclared.
+        if (!entityLevelMatch) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'unresolved-entity',
+                message: `Relationship endpoint references unknown entity '${wholePath}'.`,
+                span: endpoint.span,
+            });
+        }
         return;
+    }
     // PHASE 1 (cont'd): longest-prefix entity match.
     let entity;
     let entityPrefixLen = 0;
@@ -522,15 +548,29 @@ function resolveRefSpec(endpoint, symbols, diagnostics) {
         }
     }
     if (!entity) {
+        if (entityLevelMatch)
+            return; // entity-level endpoint; nothing further to check
         const guess = leadingFields.slice(0, maxEntityLen).join('.');
         diagnostics.push({
             severity: 'error',
             code: 'unresolved-entity',
-            message: `Foreign-key endpoint references unknown entity '${guess}'.`,
+            message: `Relationship endpoint references unknown entity '${guess}'.`,
             span: endpoint.span,
         });
         return;
     }
+    if (entityLevelMatch) {
+        // Both readings exist: `a.b` names an entity, and `a` names an entity
+        // with a field `b`. The attribute reading wins, and the collision is
+        // reported so the author can qualify the path differently.
+        diagnostics.push({
+            severity: 'warning',
+            code: 'ambiguous-ref-endpoint',
+            message: `Endpoint '${wholePath}' names both an entity and a field of entity '${entity.qualifiedName}'. ` +
+                'Reading it as the field; rename one of them or qualify the path to remove the ambiguity.',
+            span: endpoint.span,
+        });
+    }
     if (entity.declaration.kind !== 'EntityDeclaration')
         return;
     // PHASE 2: compute the post-entity portion of endpoint.path.

package/dist/parser.d.ts

@@ -13,8 +13,22 @@ import type { ParseOptions, Position, XDbmlDocument } from './ast.ts';
 import type { Token } from './lexer.ts';
 export declare class ParseError extends Error {
     position: Position;
-    constructor(message: string, position: Position);
+    /**
+     * Optional machine-readable reason. Set for the errors a caller may want
+     * to tell apart from a plain syntax error: `unsupported-version` when a
+     * document declares a newer version than this parser supports (spec 4.1).
+     */
+    code?: string;
+    constructor(message: string, position: Position, code?: string);
 }
+/**
+ * The newest specification version this parser implements. A document
+ * declaring a later version is refused (spec 4.1) rather than parsed with
+ * semantics it does not have.
+ */
+export declare const SUPPORTED_XDBML_VERSION = "0.5";
+/** Compare dotted version strings numerically: -1, 0 or 1. */
+export declare function compareVersions(a: string, b: string): number;
 export declare class Parser {
     private tokens;
     private idx;
@@ -30,7 +44,7 @@ export declare class Parser {
      * The set of file paths currently being parsed in the resolution chain.
      * Used for cycle detection: when resolving a directive whose `from` path
      * is already in this set, the parser produces an empty clone for that
-     * directive rather than recursing (matching spec §26.15: cycles are
+     * directive rather than recursing (matching spec §27.15: cycles are
      * allowed; name resolution handles them). The set is passed by reference
      * across recursive parse() calls so all transitive levels see it.
      *
@@ -83,13 +97,13 @@ export declare class Parser {
     private parseEntityBody;
     private parsePartialInjection;
     /**
-     * Parse a `records { ... }` block inside an entity body (§25.1, implicit
+     * Parse a `records { ... }` block inside an entity body (§26.1, implicit
      * column list). Values are stored as SettingValue cells; row boundaries
      * are determined by source line (see `parseRecordRow`).
      */
     private parseRecordsBlock;
     /**
-     * Top-level records declaration (§25.2, new in v0.2):
+     * Top-level records declaration (§26.2, new in v0.2):
      *
      *     records users (id, name, email) { ... }
      *     records core.users (id, name, email) { ... }
@@ -151,12 +165,12 @@ export declare class Parser {
      * that match the import items by name and element type (matching is
      * downstream-consumer's job; the parser is permissive).
      *
-     * Per spec §26.6, clone content uses the importing file's vocabulary
+     * Per spec §27.6, clone content uses the importing file's vocabulary
      * (aliases already applied) and is parsed under the importing file's
      * xdbml version directive.
      *
      * Most clone-block content uses TopLevelStatement shapes (Entity, Type,
-     * Container, etc.). The exception is field imports (§26.8): when the
+     * Container, etc.). The exception is field imports (§27.8): when the
      * directive imports one or more fields via `field <path>` items, the
      * clone block holds each field as a bare FieldDeclaration with no entity
      * wrapper. The dispatch below checks whether the next token starts a
@@ -278,7 +292,7 @@ export declare class Parser {
     private parseCardinalityOperator;
     private parseRefEndpoint;
     /**
-     * Parse a dotted path with the §18 segment vocabulary:
+     * Parse a dotted path with the §20 segment vocabulary:
      *
      *   IDENTIFIER                  -- a field segment
      *   .IDENTIFIER                 -- field
@@ -297,6 +311,16 @@ export declare class Parser {
     private parsePathSegments;
     private parseTablePartial;
     private parseTableGroup;
+    /**
+     * `SupertypeGroup <name> [supertype: X, ...] { Sub1  Sub2 [strategy: y] }`.
+     * Members are separated like TableGroup members: newline, comma or
+     * semicolon (spec §3.9). A name is required (§12.1); a writer exporting a
+     * group that has none emits `undefinedGroup1`, `undefinedGroup2`, ... so
+     * the parser never supplies one. Values are validated after parsing, by
+     * `checkSupertypeGroups()`, so an unknown value gets a located diagnostic
+     * rather than stopping the parse.
+     */
+    private parseSupertypeGroup;
     private parseIndexes;
     private parseIndexEntry;
     private parseIndexComponent;