@metaobjectsdev/metadata 0.23.1 → 0.23.2

package/src/attr-schema-validate.ts

@@ -52,6 +52,7 @@ import {
   FIELD_ATTR_VALUES,
   FIELD_ATTR_COERCE_DEFAULT,
   FIELD_ATTR_DEFAULT,
+  FIELD_ATTR_INT_VALUE_MAP,
   ENUM_MEMBER_PATTERN,
 } from "./core/field/field-constants.js";
 import {
@@ -309,6 +310,19 @@ function validateNode(
   // only own @values need checking here (mirrors the own-attrs-only policy of
   // Checks 2+3 above — inherited attrs were validated on the declaring node).
   if (node.type === TYPE_FIELD && node.subType === FIELD_SUBTYPE_ENUM) {
+    // #246: the shared-enum super, if any — a root-level abstract field.enum (one
+    // whose parent is the metadata root, not an object). FR-019 materializes such a
+    // declaration ONCE per port as a single named type, so anything a consuming
+    // field re-declares that is part of the shared TYPE's contract is a conflict.
+    // Immediate-super-only, matching codegen's resolveSharedEnumDecl (enum-shared.ts)
+    // so the validator and the collapse agree on what "shared" means.
+    const sharedSuper =
+      node.superData !== undefined &&
+      node.superData.isAbstract &&
+      node.superData.parent?.type === TYPE_METADATA
+        ? node.superData
+        : undefined;
+
     // ADR-0039: own — validates the @values DECLARED on this node; a concrete enum
     // extending an abstract one inherits already-validated @values (own-attrs-only).
     const rawValues = node.ownAttrs().get(FIELD_ATTR_VALUES);
@@ -347,18 +361,16 @@ function validateNode(
         }
       }
 
-      // #246: a field.enum extending a shared package-level abstract enum
-      // (a root-level abstract field — one whose parent is the metadata root,
-      // not an object) that ALSO declares its own @values is a conflict: one
-      // shared enum type has one member set, so codegen's shared-enum collapse
-      // would silently drop this field's own @values in favor of the shared
-      // type's. Own-attrs-only (matches the rest of Check 4): only fires when
-      // THIS node declares @values itself, not when it merely inherits.
-      const sup = node.superData;
-      if (sup !== undefined && sup.isAbstract && sup.parent?.type === TYPE_METADATA) {
+      // #246: a field.enum extending a shared package-level abstract enum that
+      // ALSO declares its own @values is a conflict: one shared enum type has one
+      // member set, so codegen's shared-enum collapse would silently drop this
+      // field's own @values in favor of the shared type's. Own-attrs-only
+      // (matches the rest of Check 4): only fires when THIS node declares
+      // @values itself, not when it merely inherits.
+      if (sharedSuper !== undefined) {
         errors.push(
           new ParseError(
-            `${nodeLabel(node)} extends shared abstract enum '${nodeLabel(sup)}' AND declares its own ` +
+            `${nodeLabel(node)} extends shared abstract enum '${nodeLabel(sharedSuper)}' AND declares its own ` +
               `'@${FIELD_ATTR_VALUES}' — a shared enum's member set is owned by the shared declaration; ` +
               `remove the own '@${FIELD_ATTR_VALUES}' to inherit it, or extend a non-shared enum instead.`,
             { code: "ERR_ENUM_EXTENDS_VALUES_CONFLICT", source: node.source },
@@ -399,6 +411,97 @@ function validateNode(
         }
       }
     }
+
+    // --- Check 5a: @intValueMap is scalar-only (design D7) ---
+    //
+    // Int-backing is a persistence-layer CODEC, and no port implements it
+    // element-wise over an array column: OMDB's EnumCodec and Kotlin's
+    // customEnumeration are scalar by construction, Python would bind the symbol
+    // list straight into an integer[], and TS's sqlite branch serializes an array
+    // as JSON text before the enum case is ever reached. Two ports that DO compose
+    // (TS/Postgres via .array(), C# via PrimitiveCollection) are not a feature —
+    // shipping a claim four ports silently get wrong is the field.byte/short/class
+    // mistake. Rejected at LOAD so it fails identically everywhere.
+    //
+    // BOTH reads are RESOLVING, unlike Check 5b below: the illegal thing is the
+    // EFFECTIVE combination. Post-#246 the map must live on the shared abstract
+    // declaration, so the field that inherits it is exactly where isArray gets
+    // declared — an own-only read would see the two halves on different nodes and
+    // never fire.
+    if (node.attrs().get(FIELD_ATTR_INT_VALUE_MAP) !== undefined && node.resolvedIsArray()) {
+      errors.push(
+        new ParseError(
+          `${nodeLabel(node)} declares '@${FIELD_ATTR_INT_VALUE_MAP}' with isArray=true; ` +
+            `int-backing is scalar-only — an array-of-enum persists its member symbols. ` +
+            `Remove '@${FIELD_ATTR_INT_VALUE_MAP}', or make the field scalar.`,
+          { code: "ERR_ENUM_INT_VALUE_MAP_ARRAY", source: node.source },
+        ),
+      );
+    }
+
+    // --- Check 5b: field.enum @intValueMap content rules ---
+    //
+    // Optional. Own-only (mirrors Checks 4/5's own-attrs-only policy) — an
+    // inherited @intValueMap is validated on its declaring node. The generic
+    // "is this an object of integers" shape check already ran via IntMapAttr
+    // (attr subtype `intMap`); this validates the field.enum-SPECIFIC
+    // semantics: key-set-equals-@values, and no two members share a value.
+    const rawIntValueMap = node.ownAttrs().get(FIELD_ATTR_INT_VALUE_MAP);
+    if (rawIntValueMap !== undefined && typeof rawIntValueMap === "object" && rawIntValueMap !== null) {
+      // #246 (int-backed twin): the symbol→int mapping is a property of the enum
+      // VOCABULARY, not of one column that uses it — it is @values' numeric half.
+      // A shared enum is materialized once as a single type, so a per-field map
+      // would give one logical type N storage encodings (and, where a port emits
+      // per-TYPE codec artifacts, two same-named declarations). Same remedy as the
+      // @values half: declare it on the shared declaration and inherit it.
+      if (sharedSuper !== undefined) {
+        errors.push(
+          new ParseError(
+            `${nodeLabel(node)} extends shared abstract enum '${nodeLabel(sharedSuper)}' AND declares its own ` +
+              `'@${FIELD_ATTR_INT_VALUE_MAP}' — a shared enum's integer backing is owned by the shared ` +
+              `declaration; move '@${FIELD_ATTR_INT_VALUE_MAP}' onto '${nodeLabel(sharedSuper)}' to inherit it, ` +
+              `or extend a non-shared enum instead.`,
+            { code: "ERR_ENUM_EXTENDS_VALUES_CONFLICT", source: node.source },
+          ),
+        );
+      }
+      const map = rawIntValueMap as Record<string, number>;
+      const effectiveValues = node.attrs().get(FIELD_ATTR_VALUES);
+      const declaredMembers: string[] = Array.isArray(effectiveValues) ? effectiveValues : [];
+      const memberSet = new Set(declaredMembers);
+      const mapKeys = Object.keys(map);
+      const keySet = new Set(mapKeys);
+
+      const missing = declaredMembers.filter((m) => !keySet.has(m));
+      const extra = mapKeys.filter((k) => !memberSet.has(k));
+      if (missing.length > 0 || extra.length > 0) {
+        errors.push(
+          new ParseError(
+            `${nodeLabel(node)} attribute '@${FIELD_ATTR_INT_VALUE_MAP}' keys must exactly match '@${FIELD_ATTR_VALUES}' members` +
+              (missing.length > 0 ? ` (missing: ${missing.join(", ")})` : "") +
+              (extra.length > 0 ? ` (unknown: ${extra.join(", ")})` : "") + ".",
+            { code: "ERR_BAD_ATTR_VALUE", source: node.source },
+          ),
+        );
+      }
+
+      const seenValues = new Map<number, string>();
+      for (const [member, value] of Object.entries(map)) {
+        if (typeof value !== "number" || !Number.isInteger(value)) continue; // IntMapAttr already reported this
+        const owner = seenValues.get(value);
+        if (owner !== undefined) {
+          errors.push(
+            new ParseError(
+              `${nodeLabel(node)} attribute '@${FIELD_ATTR_INT_VALUE_MAP}' members '${owner}' and '${member}' ` +
+                `share the same value ${value}; every member must have a unique int.`,
+              { code: "ERR_BAD_ATTR_VALUE", source: node.source },
+            ),
+          );
+        } else {
+          seenValues.set(value, member);
+        }
+      }
+    }
   }
 
   // --- Check 6 (R6 Plan 2b): @dbColumnType (logical subtype × value) pairing ---

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

@@ -17,6 +17,11 @@ export const ATTR_SUBTYPE_FILTER = "filter";
 // #195 — a structured expression tree over a base entity's own fields (backs
 // origin.computed). Object-shaped; a closed node grammar (see meta-attr-expression.ts).
 export const ATTR_SUBTYPE_EXPRESSION = "expression";
+// An object-shaped attr whose values are all integers (e.g. field.enum's
+// @intValueMap: {memberSymbol: int}). Generic shape check only — semantic
+// rules specific to a consumer (key-set membership, uniqueness) are that
+// consumer's own content-rule validation, not this attr's.
+export const ATTR_SUBTYPE_INT_MAP = "intMap";
 
 /**
  * The retired `stringarray` array attr subtype. It is NO LONGER a registered
@@ -41,6 +46,7 @@ export const ATTR_SUBTYPES = [
   ATTR_SUBTYPE_PROPERTIES,
   ATTR_SUBTYPE_FILTER,
   ATTR_SUBTYPE_EXPRESSION,
+  ATTR_SUBTYPE_INT_MAP,
 ] as const;
 export type AttrSubType =
   | (typeof ATTR_SUBTYPES)[number]

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

@@ -27,6 +27,12 @@ export const ATTR_DEFINITION: ProviderDefinition = {
       "dataType": "int",
       "description": "A 32-bit-integer-valued metadata attribute. Coerces to and validates as a number."
     },
+    {
+      "type": "attr",
+      "subType": "intMap",
+      "dataType": "object",
+      "description": "An object-shaped attribute whose values are all integers (e.g. field.enum's @intValueMap: {memberSymbol: int}). Generic shape check only; a consumer field type layers its own semantic rules (key-set membership, uniqueness) in its own content-rule validation."
+    },
     {
       "type": "attr",
       "subType": "long",

package/src/core/attr/meta-attr-int-map.ts

@@ -0,0 +1,54 @@
+// IntMapAttr — attr subtype `intMap`. Object-shaped value whose members must
+// all be integers (e.g. field.enum's @intValueMap). No desugar; validates
+// shape (object, not array) and every value's type (integer). A consumer's
+// own semantic rules (key-set membership, uniqueness) are validated by that
+// consumer, not here — mirrors how StringArrayAttr validates shape while
+// field.enum's own content-rule pass validates its @values semantics.
+
+import { MetaAttr, type ValueError, runtimeTypeName } from "./meta-attr.js";
+import { type AttrValue } from "../../shared/meta-data.js";
+import { DATA_TYPE_OBJECT, type DataType } from "../../data-type.js";
+import { registerAttrClass } from "../../attr-class-map.js";
+import { ATTR_SUBTYPE_INT_MAP } from "./attr-constants.js";
+
+// 32-bit signed integer bounds (inclusive) — the eventual DB column for an
+// int-backed enum is a 32-bit Postgres/SQLite `integer` (design doc D5).
+const INT32_MIN = -2147483648;
+const INT32_MAX = 2147483647;
+
+export class IntMapAttr extends MetaAttr {
+  override get dataType(): DataType {
+    return DATA_TYPE_OBJECT;
+  }
+
+  override coerce(raw: unknown): AttrValue {
+    return raw as AttrValue;
+  }
+
+  override validateValue(value: AttrValue): ValueError[] {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      return [{ message: `attribute '@${this.name}' must be of type 'intMap' but got ${runtimeTypeName(value)}` }];
+    }
+    const errors: ValueError[] = [];
+    for (const [key, member] of Object.entries(value as Record<string, unknown>)) {
+      if (typeof member !== "number" || !Number.isInteger(member)) {
+        errors.push({
+          message: `attribute '@${this.name}' member '${key}' has value '${String(member)}' which is not an integer`,
+        });
+      } else if (member < INT32_MIN || member > INT32_MAX) {
+        // The eventual DB column for an int-backed enum is a 32-bit Postgres/
+        // SQLite `integer` (design doc D5; matches field.int's existing
+        // 32-bit mapping in expected-schema.ts) — mirrors Java's
+        // IntMapAttribute#setValueAsString bound check exactly (inclusive at
+        // both ends) so a value that could never be persisted fails at load
+        // time, not silently, on every port.
+        errors.push({
+          message: `attribute '@${this.name}' member '${key}' has value '${member}' which is outside the 32-bit signed integer range`,
+        });
+      }
+    }
+    return errors;
+  }
+}
+
+registerAttrClass(ATTR_SUBTYPE_INT_MAP, IntMapAttr);

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

@@ -166,6 +166,16 @@ export const FIELD_ATTR_CURRENCY_DEFAULT = "USD";
 /** Member symbols of an enum-subtype field. Required, string array. */
 export const FIELD_ATTR_VALUES = "values";
 
+/**
+ * Optional per-member explicit integer value ({memberSymbol: int}) switching
+ * this enum field's DB persistence from string+CHECK to integer+CHECK. Keys
+ * must exactly match @values; values must be unique integers. The generated
+ * native type and wire format are UNCHANGED in every language — this is a
+ * persistence-layer-only concern (docs/superpowers/specs/2026-07-23-int-backed-
+ * enum-values-design.md).
+ */
+export const FIELD_ATTR_INT_VALUE_MAP = "intValueMap";
+
 /**
  * Pattern every enum member must satisfy: a legal identifier in all target
  * languages (TS union member, Java/C#/Python enum member). Ensures symbol ==

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

@@ -279,6 +279,14 @@ export const FIELD_DEFINITION: ProviderDefinition = {
           "min": 0,
           "max": 1,
           "description": "FR-019: marks an abstract package-level field.enum as externally provided — codegen references the type (resolved via per-port codegen config) instead of materializing it. Default false. Not a field attr — it lives on the type declaration."
+        },
+        {
+          "type": "attr",
+          "subType": "intMap",
+          "name": "intValueMap",
+          "min": 0,
+          "max": 1,
+          "description": "Optional per-member int values ({member: int}) switching this enum field's DB persistence from string+CHECK to integer+CHECK. Keys must exactly match @values; values must be unique integers. The generated native type and wire format are unchanged in every language."
         }
       ]
     },

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

@@ -1,4 +1,4 @@
-import { FIELD_SUBTYPE_UUID, FIELD_SUBTYPE_CURRENCY, FIELD_SUBTYPE_ENUM, FIELD_SUBTYPE_URI, FIELD_SUBTYPE_INET } from "../field/field-constants.js";
+import { FIELD_SUBTYPE_UUID, FIELD_SUBTYPE_CURRENCY, FIELD_SUBTYPE_ENUM, FIELD_SUBTYPE_URI, FIELD_SUBTYPE_INET, FIELD_ATTR_INT_VALUE_MAP } from "../field/field-constants.js";
 
 // Query concern constants — filter operators, sort order values.
 //
@@ -67,6 +67,52 @@ export function opsForSubType(subType: string): readonly FilterOp[] {
   return OPS_BY_SUBTYPE[subType] ?? [];
 }
 
+/** The int-backed-enum band: the enum band minus `like`. Hoisted so the narrowing
+ *  is one named constant rather than a filter re-derived at every call. */
+const OPS_ENUM_INT_BACKED: readonly FilterOp[] = [
+  FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_IN, FILTER_OP_IS_NULL,
+];
+
+/**
+ * The structural shape `opsForField` needs. Declared here rather than importing
+ * `MetaField`: `query-constants` is foundational and `core/field` imports it, so a
+ * type import back the other way would close a cycle.
+ */
+export interface FilterOpBandField {
+  readonly subType: string;
+  attr(name: string): unknown;
+}
+
+/**
+ * The filter-operator band for a FIELD — the entry point every consumer that has a
+ * field in hand must use (loader validation, generated allowlists, generated client
+ * filter types, the cross-port `field.filter-ops` capability).
+ *
+ * Identical to {@link opsForSubType} except for ONE case: an int-backed `field.enum`
+ * (one declaring `@intValueMap`, design D5) persists as an INTEGER column, so `like`
+ * — a substring match — is dropped. `eq`/`ne`/`in` survive because the member symbol
+ * encodes to its integer before it reaches SQL; `like` has no such encoding, and an
+ * unencoded `LIKE 'DRAFT'` against an integer column is a request-time type error.
+ *
+ * `opsForSubType` cannot express this: it only ever sees the subtype `"enum"`. It is
+ * deliberately left unchanged for the one caller that genuinely has no field — the
+ * expression grammar's declared operand type.
+ *
+ * ADR-0039: the `@intValueMap` read is RESOLVING. Post-#246 the map lives on a shared
+ * root-level abstract declaration and consuming fields INHERIT it, so an own-only read
+ * would see `undefined` on exactly the shape adopters are steered toward and wrongly
+ * keep `like` in the band.
+ */
+export function opsForField(field: FilterOpBandField): readonly FilterOp[] {
+  if (field.subType === FIELD_SUBTYPE_ENUM && isIntBacked(field)) return OPS_ENUM_INT_BACKED;
+  return opsForSubType(field.subType);
+}
+
+function isIntBacked(field: FilterOpBandField): boolean {
+  const raw = field.attr(FIELD_ATTR_INT_VALUE_MAP);
+  return raw !== undefined && raw !== null && typeof raw === "object";
+}
+
 // ---------------------------------------------------------------------------
 // Sort order values (used by @sortableDefaultOrder on fields and
 // @defaultSortOrder on dataGrid layouts)

package/src/core-types.ts

@@ -20,6 +20,7 @@ import "./core/attr/meta-attr-stringarray.js";
 import "./core/attr/meta-attr-filter.js";
 import "./core/attr/meta-attr-properties.js";
 import "./core/attr/meta-attr-expression.js";
+import "./core/attr/meta-attr-int-map.js";
 import {
   MetaValidator,
   MetaRequiredValidator,

package/src/errors.ts

@@ -202,6 +202,12 @@ export const ERROR_CODES = [
   // own @values would be silently dropped in codegen. Remove the own @values
   // to inherit the shared set, or extend a concrete (non-shared) enum instead.
   "ERR_ENUM_EXTENDS_VALUES_CONFLICT",
+  // A field.enum carries @intValueMap together with isArray=true. Int-backing is
+  // a persistence-layer codec and no port implements it element-wise over an
+  // array column, so the combination would silently persist member SYMBOLS into
+  // an integer array. An array-of-enum stays string-backed: drop @intValueMap,
+  // or make the field scalar.
+  "ERR_ENUM_INT_VALUE_MAP_ARRAY",
   "ERR_UNKNOWN",
 ] as const;
 

package/src/loader/validation-passes.ts

@@ -130,6 +130,7 @@ import {
   FILTER_COMPOSE_OR,
   FILTER_COMPOSE_AND,
   opsForSubType,
+  opsForField,
 } from "../core/query/query-constants.js";
 
 // ---------------------------------------------------------------------------
@@ -1684,7 +1685,9 @@ export function validateDataGridFilterValues(root: MetaData): ParseError[] {
     for (const f of effective.filter((c) => c.type === TYPE_FIELD)) {
       // ADR-0039: resolving — a concrete field may inherit @filterable via extends.
       if (f.attr(FIELD_ATTR_FILTERABLE) === true) {
-        allow.set(f.name, opsForSubType(f.subType));
+        // opsForField, not opsForSubType — an int-backed field.enum (@intValueMap)
+        // stores as an integer, so `like` is not in its band.
+        allow.set(f.name, opsForField(f));
       }
     }
     for (const layout of effective.filter(
@@ -2034,7 +2037,9 @@ export function validateProjectionFilter(root: MetaData): ParseError[] {
         origin !== undefined &&
         origin.subType !== ORIGIN_SUBTYPE_PASSTHROUGH &&
         origin.subType !== ORIGIN_SUBTYPE_COMPUTED;
-      fields.set(f.name, { derived, ops: opsForSubType(f.subType) });
+      // opsForField, not opsForSubType — an int-backed field.enum (@intValueMap)
+      // stores as an integer, so `like` is not in its band.
+      fields.set(f.name, { derived, ops: opsForField(f) });
     }
     checkProjectionFilterRefs(filter as Record<string, unknown>, fields, obj.name, obj.source, errors);
   }