@metaobjectsdev/metadata 0.15.0 → 0.15.1

package/src/core/identity/meta-identity.ts

@@ -10,7 +10,6 @@ import {
   IDENTITY_SUBTYPE_REFERENCE,
   IDENTITY_ATTR_FIELDS,
   IDENTITY_ATTR_GENERATION,
-  IDENTITY_ATTR_UNIQUE,
   IDENTITY_REFERENCE_ATTR_REFERENCES,
   IDENTITY_REFERENCE_ATTR_ENFORCE,
   IDENTITY_REFERENCE_ATTR_ON_DELETE,
@@ -28,15 +27,6 @@ export class MetaIdentity extends MetaData {
     return Array.isArray(f) ? (f as string[]) : [];
   }
 
-  /**
-   * Whether the identity enforces uniqueness.
-   * Defaults to true; explicit `@unique: false` makes it a non-unique index.
-   * ADR-0039: resolving.
-   */
-  get unique(): boolean {
-    return this.attr(IDENTITY_ATTR_UNIQUE) !== false;
-  }
-
   isPrimary(): boolean {
     return this.subType === IDENTITY_SUBTYPE_PRIMARY;
   }
@@ -67,7 +57,8 @@ export class MetaPrimaryIdentity extends MetaIdentity {
 }
 
 /**
- * Secondary identity — a unique or non-unique index on one or more fields.
+ * Secondary identity — always a unique index on one or more fields.
+ * Uniqueness is in the type; use `index.lookup` for non-unique indexes.
  * `@generation` does not apply here.
  */
 export class MetaSecondaryIdentity extends MetaIdentity {}

package/src/core/index/index-constants.ts

@@ -0,0 +1,31 @@
+// Index concern constants — type name, subtypes, and attr keys.
+
+// ---------------------------------------------------------------------------
+// Index type name (re-exported from shared/base-types.ts as TYPE_INDEX)
+// ---------------------------------------------------------------------------
+
+/**
+ * Index type name as the brief-specified interface name.
+ * Downstream tasks import `INDEX` from here; `TYPE_INDEX` comes from base-types.
+ */
+export const INDEX = "index";
+
+// ---------------------------------------------------------------------------
+// Index subtypes (1: lookup)
+// ---------------------------------------------------------------------------
+
+export const INDEX_SUBTYPE_LOOKUP = "lookup";
+
+export const INDEX_SUBTYPES = [INDEX_SUBTYPE_LOOKUP] as const;
+export type IndexSubType = (typeof INDEX_SUBTYPES)[number];
+
+// ---------------------------------------------------------------------------
+// Index attrs (logical — core)
+// ---------------------------------------------------------------------------
+
+/** The field name(s) composing this index. */
+export const INDEX_ATTR_FIELDS = "fields";
+
+// NOTE: physical RDB-only index attrs (@using / @expr / @where / @orders) are
+// NOT core — they are contributed by the db provider, reusing the existing
+// IDENTITY_ATTR_* constants in persistence/db/db-constants.ts.

package/src/core/index/index-definition.embedded.ts

@@ -0,0 +1,25 @@
+// Embedded definition for the index type (core vocab — physical attrs come from db provider).
+import type { ProviderDefinition } from "../../provider-data.js";
+
+export const INDEX_DEFINITION: ProviderDefinition = {
+  "provider": "metaobjects-core-types",
+  "types": [
+    {
+      "type": "index",
+      "subType": "lookup",
+      "description": "A non-unique lookup index on one or more fields. Use for query-performance indexes that do NOT enforce uniqueness — declare identity.secondary for unique constraints instead.",
+      "whenToUse": "You need a DB index for query performance (fast lookups/sorts) but NOT uniqueness enforcement. @fields names the indexed columns; the db provider adds @orders / @expr / @where / @using for physical tuning.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "fields",
+          "isArray": true,
+          "min": 1,
+          "max": 1,
+          "description": "The field name(s) this index covers (at least one). When @expr is present, it is the key expression derived from these fields."
+        }
+      ]
+    }
+  ]
+};

package/src/core/index/meta-index.ts

@@ -0,0 +1,22 @@
+// MetaIndex — concrete node class for type=index nodes.
+// MetaLookupIndex is the single concrete subtype class.
+//
+// Extends MetaData directly: no model wrapper, no metaOf() indirection.
+
+import { MetaData } from "../../shared/meta-data.js";
+import {
+  INDEX_SUBTYPE_LOOKUP,
+  INDEX_ATTR_FIELDS,
+} from "./index-constants.js";
+
+export class MetaIndex extends MetaData {
+  /** ADR-0039: resolving — @fields may be inherited via extends. */
+  fields(): string[] {
+    const f = this.attr(INDEX_ATTR_FIELDS);
+    return Array.isArray(f) ? (f as string[]) : [];
+  }
+
+  isLookup(): boolean {
+    return this.subType === INDEX_SUBTYPE_LOOKUP;
+  }
+}

package/src/core/object/meta-object.ts

@@ -7,6 +7,7 @@ import { MetaData } from "../../shared/meta-data.js";
 import {
   TYPE_FIELD,
   TYPE_IDENTITY,
+  TYPE_INDEX,
   TYPE_RELATIONSHIP,
   TYPE_VALIDATOR,
   TYPE_LAYOUT,
@@ -32,6 +33,7 @@ import {
 } from "../identity/identity-constants.js";
 import type { MetaField } from "../field/meta-field.js";
 import type { MetaIdentity, MetaReferenceIdentity } from "../identity/meta-identity.js";
+import type { MetaIndex } from "../index/meta-index.js";
 import type { MetaLayout } from "../../presentation/layout/meta-layout.js";
 import type { MetaRelationship } from "../relationship/meta-relationship.js";
 import type { MetaValidator } from "../validator/meta-validator.js";
@@ -129,6 +131,13 @@ export class MetaObject extends MetaData {
     );
   }
 
+  /** All effective lookup indexes (own + inherited via extends). ADR-0039: resolving. */
+  lookupIndexes(): MetaIndex[] {
+    return this.cached("lookupIndexes", () =>
+      this.children().filter((c): c is MetaIndex => c.type === TYPE_INDEX),
+    );
+  }
+
   /** All effective validators (own + inherited via extends). */
   validators(): MetaValidator[] {
     return this.cached("validators", () =>

package/src/core/object/object-definition.embedded.ts

@@ -48,6 +48,13 @@ export const OBJECT_DEFINITION: ProviderDefinition = {
           "name": "*",
           "min": 0,
           "max": null
+        },
+        {
+          "type": "index",
+          "subType": "*",
+          "name": "*",
+          "min": 0,
+          "max": null
         }
       ]
     },

package/src/core-types.ts

@@ -51,6 +51,9 @@ import { LAYOUT_DEFINITION } from "./presentation/layout/layout-definition.embed
 import { MetaTemplate } from "./template/meta-template.js";
 import { TEMPLATE_DEFINITION } from "./template/template-definition.embedded.js";
 import { TEMPLATE_SUBTYPES } from "./template/template-constants.js";
+import { MetaIndex } from "./core/index/meta-index.js";
+import { INDEX_DEFINITION } from "./core/index/index-definition.embedded.js";
+import { INDEX_SUBTYPES } from "./core/index/index-constants.js";
 import {
   TYPE_METADATA,
   TYPE_OBJECT,
@@ -64,6 +67,7 @@ import {
   TYPE_SOURCE,
   TYPE_ORIGIN,
   TYPE_TEMPLATE,
+  TYPE_INDEX,
   SUBTYPE_ROOT,
 } from "./shared/base-types.js";
 import { CHILD_RULE_WILDCARD } from "./shared/structural.js";
@@ -463,6 +467,20 @@ function registerCoreTypeDefs(registry: TypeRegistry): void {
     registry.register(relationshipDef);
   }
 
+  // index — 1 subtype (lookup). Non-unique lookup indexes for query-performance.
+  // Distinct from identity.secondary (which enforces uniqueness). A single
+  // MetaIndex class backs the lookup subtype; physical attrs (@orders/@expr/
+  // @where/@using) are contributed by the db provider via registry.extend.
+  const INDEX_FACTORIES: FactoryMap = Object.fromEntries(
+    INDEX_SUBTYPES.map((subType) => [
+      `${TYPE_INDEX}.${subType}`,
+      (typeId: TypeId, name: string) => new MetaIndex(typeId, name),
+    ]),
+  );
+  for (const indexDef of defineProviderFromData(INDEX_DEFINITION, INDEX_FACTORIES)) {
+    registry.register(indexDef);
+  }
+
   // Declare the core cross-references ON their TypeDefinitions, so the loader's
   // registry-derived validation resolves them generically (a dangling target fails the
   // load). Set on the concrete subtypes the parser produces. (Production moves these into

package/src/errors.ts

@@ -155,6 +155,9 @@ export const ERROR_CODES = [
   // clash / required-child cycle / conflicting attr redefinition. The detail names
   // which of the six checks fired and the offending type(s).
   "ERR_INVALID_METAMODEL_CONSTRAINT",
+  // index.lookup field-resolution: @fields is empty or names a field that does
+  // not exist on the owning entity's effective (resolved via extends) field set.
+  "ERR_INVALID_INDEX",
   "ERR_UNKNOWN",
 ] as const;
 

package/src/index.ts

@@ -13,6 +13,7 @@ import type { MetaRoot } from "./shared/meta-root.js";
 import type { MetaObject } from "./core/object/meta-object.js";
 import type { MetaField } from "./core/field/meta-field.js";
 import type { MetaIdentity } from "./core/identity/meta-identity.js";
+import type { MetaIndex } from "./core/index/meta-index.js";
 import type { MetaRelationship } from "./core/relationship/meta-relationship.js";
 import type { MetaValidator } from "./core/validator/meta-validator.js";
 import type { MetaView } from "./presentation/view/meta-view.js";
@@ -30,6 +31,7 @@ export * from "./core/attr/attr-constants.js";
 export * from "./core/documentation/doc-constants.js";
 export * from "./core/validator/validator-constants.js";
 export * from "./core/identity/identity-constants.js";
+export * from "./core/index/index-constants.js";
 export * from "./core/relationship/relationship-constants.js";
 export * from "./core/query/query-constants.js";
 export * from "./persistence/source/source-constants.js";
@@ -67,6 +69,8 @@ export {
   MetaSecondaryIdentity,
   MetaReferenceIdentity,
 } from "./core/identity/meta-identity.js";
+// Index
+export { MetaIndex } from "./core/index/meta-index.js";
 export type { IdentityGeneration } from "./core/identity/meta-identity.js";
 // FR-024 — projection identity pass-through derivation (computed local key;
 // pure tree read, codegen-facing).
@@ -122,6 +126,7 @@ export type AnyMeta =
   | MetaObject
   | MetaField
   | MetaIdentity
+  | MetaIndex
   | MetaRelationship
   | MetaValidator
   | MetaView

package/src/loader/meta-data-loader.ts

@@ -17,7 +17,7 @@ import { ParseError } from "../errors.js";
 import type { LoaderWarning } from "../source.js";
 import { codeSource, resolvedSource } from "../source.js";
 import { parseJson } from "../parser-json.js";
-import { validateDataGridSortFields, validateFilterableHasIndex, validateFilterableHasSupportedOps, validateOriginPaths, validateDerivedFieldProvidability, validateDataGridFilterValues, validateFieldObjectStorage, validateFieldMap, validateTemplatePayloadRefs, validateFieldDefaults, validateRelationships } from "./validation-passes.js";
+import { validateDataGridSortFields, validateFilterableHasIndex, validateFilterableHasSupportedOps, validateOriginPaths, validateDerivedFieldProvidability, validateDataGridFilterValues, validateFieldObjectStorage, validateFieldMap, validateTemplatePayloadRefs, validateFieldDefaults, validateRelationships, validateIndexLookupFields } from "./validation-passes.js";
 import { runRegisteredValidation } from "./validation-registry.js";
 import { validateSourceRoles } from "../persistence/source/validate-source-roles.js";
 import { validateSourcePhysicalNames } from "../persistence/source/validate-source-physical-names.js";
@@ -495,6 +495,11 @@ export class MetaDataLoader {
       // are invalid on a 1:N relationship.
       errors.push(...validateRelationships(root));
 
+      // index.lookup @fields resolution — each index.lookup must name ≥1 field,
+      // and every field must exist in the entity's effective (resolved) field set
+      // (ADR-0039: resolving accessor, so inherited fields via extends are visible).
+      errors.push(...validateIndexLookupFields(root));
+
       // Phase 2 — validation DERIVED FROM THE TYPE REGISTRY: each node's TypeDefinition
       // carries its reference descriptors + imperative validator, run as one recursive walk
       // over a built-once symbol table. A downstream provider's custom type validates itself

package/src/loader/validation-passes.ts

@@ -25,7 +25,13 @@ import {
   TYPE_RELATIONSHIP,
   TYPE_SOURCE,
   TYPE_TEMPLATE,
+  TYPE_INDEX,
 } from "../shared/base-types.js";
+import {
+  INDEX_SUBTYPE_LOOKUP,
+  INDEX_ATTR_FIELDS,
+} from "../core/index/index-constants.js";
+import { MetaIndex } from "../core/index/meta-index.js";
 import {
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_RESPONSE_REF,
@@ -1428,6 +1434,60 @@ export function validateRelationships(root: MetaData): ParseError[] {
 // NOTE: identity.reference @references resolution moved to the validation registry
 // (defaultValidationRegistry → a declarative reference descriptor with dottedFieldPath).
 
+// ---------------------------------------------------------------------------
+// index.lookup @fields resolution (Task 3)
+//
+// Every index.lookup on an entity must name at least one field, and every
+// named field must exist in the entity's EFFECTIVE (resolved) field set.
+// ADR-0039: use children() / MetaIndex.fields() — never own* — so that a
+// field inherited via extends still resolves correctly.
+// ---------------------------------------------------------------------------
+
+export function validateIndexLookupFields(root: MetaData): ParseError[] {
+  const errors: ParseError[] = [];
+  // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+  for (const obj of root.children().filter((c) => c.type === TYPE_OBJECT)) {
+    // Effective (resolved) field names — includes inherited fields via extends.
+    const effectiveFieldNames = new Set(
+      obj.children().filter((c) => c.type === TYPE_FIELD).map((f) => f.name),
+    );
+    for (const node of obj.children().filter(
+      (c) => c.type === TYPE_INDEX && c.subType === INDEX_SUBTYPE_LOOKUP,
+    )) {
+      // MetaIndex.fields() uses the resolving attr() accessor per ADR-0039.
+      const idx = node as MetaIndex;
+      const fields = idx.fields();
+
+      // Rule 1: must have at least one field.
+      if (fields.length === 0) {
+        errors.push(
+          new ParseError(
+            `index.lookup "${idx.name}" on "${obj.name}" has no @${INDEX_ATTR_FIELDS}; ` +
+              `at least one field is required`,
+            { code: "ERR_INVALID_INDEX", source: idx.source },
+          ),
+        );
+        continue;
+      }
+
+      // Rule 2: every named field must resolve against the entity's effective field set.
+      for (const fieldName of fields) {
+        if (!effectiveFieldNames.has(fieldName)) {
+          errors.push(
+            new ParseError(
+              `index.lookup "${idx.name}" on "${obj.name}" references field "${fieldName}" ` +
+                `which does not exist on "${obj.name}". ` +
+                `Available fields: ${[...effectiveFieldNames].join(", ") || "(none)"}`,
+              { code: "ERR_INVALID_INDEX", source: idx.source },
+            ),
+          );
+        }
+      }
+    }
+  }
+  return errors;
+}
+
 function checkFilterClauses(
   filter: Record<string, unknown>,
   allow: Map<string, readonly string[]>,

package/src/persistence/db/db-definition.embedded.ts

@@ -247,6 +247,49 @@ export const DB_DEFINITION: ProviderDefinition = {
           "description": "Physical foreign-key constraint name override. Absent → the backend's auto-derived default (e.g. `<table>_<firstFkColumn>_fk`). Lets a model adopt an existing database whose FK constraints follow a different naming convention without a destructive rename. RDB-physical — contributed by the db provider."
         }
       ]
+    },
+    {
+      "type": "index",
+      "subType": "lookup",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "orders",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "asc",
+            "desc"
+          ],
+          "description": "Physical index-key sort direction, positional to @fields ('asc' | 'desc'). Omit for all-ascending (the default); a shorter array leaves trailing keys ascending. Drives DESC-ordered index keys (e.g. a recency index on a timestamp). RDB-physical — contributed by the db provider."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "where",
+          "min": 0,
+          "max": 1,
+          "description": "Partial-index predicate (raw SQL, e.g. \"delivered_at IS NULL\"). When set, the index covers only rows matching the predicate — smaller and cheaper for queries that always filter on it. Absent = a full index over every row. RDB-physical — contributed by the db provider."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "expr",
+          "min": 0,
+          "max": 1,
+          "description": "Raw key EXPRESSION for a functional/expression index (e.g. \"lower(email)\"). Used INSTEAD of @fields — the index key is the expression rather than plain columns. RDB-physical — contributed by the db provider."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "using",
+          "min": 0,
+          "max": 1,
+          "description": "Index access method (e.g. \"gin\", \"gist\", \"hash\"); default \"btree\" (not rendered). Pair with @expr for e.g. a GIN index over an array/jsonb expression. RDB-physical — contributed by the db provider."
+        }
+      ]
     }
   ]
 };

package/src/shared/base-types.ts

@@ -17,6 +17,8 @@ export const TYPE_LAYOUT = "layout";
 export const TYPE_SOURCE = "source";
 export const TYPE_ORIGIN = "origin";
 export const TYPE_TEMPLATE = "template";
+/** Non-unique lookup indexes — `index.lookup` is the only registered subtype. */
+export const TYPE_INDEX = "index";
 
 export const BASE_TYPES = [
   TYPE_METADATA,
@@ -31,6 +33,7 @@ export const BASE_TYPES = [
   TYPE_SOURCE,
   TYPE_ORIGIN,
   TYPE_TEMPLATE,
+  TYPE_INDEX,
 ] as const;
 export type BaseType = (typeof BASE_TYPES)[number];