@metaobjectsdev/metadata 0.5.0-rc.1

package/dist/core/field/meta-field.js

@@ -0,0 +1,121 @@
+// MetaField — concrete node class for type=field nodes.
+//
+// Extends MetaData directly: no model wrapper, no metaOf() indirection.
+// Children are already concrete typed nodes; accessors filter by type constant.
+import { MetaData } from "../../shared/meta-data.js";
+import { DATA_TYPE_STRING, DATA_TYPE_INT, DATA_TYPE_LONG, DATA_TYPE_DOUBLE, DATA_TYPE_BOOLEAN, DATA_TYPE_DATE, DATA_TYPE_OBJECT, } from "../../data-type.js";
+import { convertToDataType } from "../../data-converter.js";
+import { TYPE_VALIDATOR, TYPE_VIEW, SUBTYPE_BASE } from "../../shared/base-types.js";
+import { FIELD_SUBTYPE_STRING, FIELD_SUBTYPE_CLASS, FIELD_SUBTYPE_INT, FIELD_SUBTYPE_SHORT, FIELD_SUBTYPE_BYTE, FIELD_SUBTYPE_LONG, FIELD_SUBTYPE_CURRENCY, FIELD_SUBTYPE_DOUBLE, FIELD_SUBTYPE_FLOAT, FIELD_SUBTYPE_DECIMAL, FIELD_SUBTYPE_BOOLEAN, FIELD_SUBTYPE_DATE, FIELD_SUBTYPE_TIME, FIELD_SUBTYPE_TIMESTAMP, FIELD_SUBTYPE_OBJECT, FIELD_ATTR_REQUIRED, FIELD_ATTR_UNIQUE, FIELD_ATTR_DEFAULT, FIELD_ATTR_MAX_LENGTH, FIELD_ATTR_PRECISION, FIELD_ATTR_SCALE, FIELD_ATTR_OBJECT_REF, } from "./field-constants.js";
+import { FIELD_ATTR_DB_COLUMN } from "../../persistence/db/db-constants.js";
+import { VALIDATOR_SUBTYPE_REQUIRED } from "../validator/validator-constants.js";
+/** Field subtype → DataType. Co-located with the class — a provider adding a
+ *  field subtype supplies its own dataType the same way. */
+const FIELD_DATA_TYPE = {
+    [SUBTYPE_BASE]: DATA_TYPE_STRING,
+    [FIELD_SUBTYPE_STRING]: DATA_TYPE_STRING,
+    [FIELD_SUBTYPE_CLASS]: DATA_TYPE_STRING,
+    [FIELD_SUBTYPE_INT]: DATA_TYPE_INT,
+    [FIELD_SUBTYPE_SHORT]: DATA_TYPE_INT,
+    [FIELD_SUBTYPE_BYTE]: DATA_TYPE_INT,
+    [FIELD_SUBTYPE_LONG]: DATA_TYPE_LONG,
+    [FIELD_SUBTYPE_CURRENCY]: DATA_TYPE_LONG,
+    [FIELD_SUBTYPE_DOUBLE]: DATA_TYPE_DOUBLE,
+    [FIELD_SUBTYPE_FLOAT]: DATA_TYPE_DOUBLE,
+    [FIELD_SUBTYPE_DECIMAL]: DATA_TYPE_DOUBLE,
+    [FIELD_SUBTYPE_BOOLEAN]: DATA_TYPE_BOOLEAN,
+    [FIELD_SUBTYPE_DATE]: DATA_TYPE_DATE,
+    [FIELD_SUBTYPE_TIME]: DATA_TYPE_DATE,
+    [FIELD_SUBTYPE_TIMESTAMP]: DATA_TYPE_DATE,
+    [FIELD_SUBTYPE_OBJECT]: DATA_TYPE_OBJECT,
+};
+export class MetaField extends MetaData {
+    /** The coarse value-type classification for this field's subtype. */
+    get dataType() {
+        return FIELD_DATA_TYPE[this.subType] ?? this._dataType ?? DATA_TYPE_STRING;
+    }
+    /** Coerce a raw value toward this field's DataType (Java DataConverter parity). */
+    coerce(raw) {
+        return convertToDataType(this.dataType, raw);
+    }
+    /** The target object name for an object-typed field (the `@objectRef` attr). */
+    get objectRef() {
+        const v = this.ownAttr(FIELD_ATTR_OBJECT_REF);
+        return typeof v === "string" ? v : undefined;
+    }
+    get dbColumn() {
+        const v = this.ownAttr(FIELD_ATTR_DB_COLUMN);
+        return typeof v === "string" ? v : undefined;
+    }
+    get default() {
+        return this.ownAttr(FIELD_ATTR_DEFAULT);
+    }
+    /**
+     * The default value for this field, converted to the field's own DataType.
+     *
+     * Java parity: MetaField.getDefaultValue() — reads the raw @default attr and
+     * converts it via DataConverter.toTypeSafe(getDataType(), raw). This ensures
+     * that even if the raw value was stored as a string (e.g. "@default": "false"
+     * in YAML or string-keyed JSON), the returned value is the correctly-typed
+     * boolean/number/string for this field's subtype.
+     *
+     * Returns undefined when @default is not set on this field.
+     * Result is cached after freeze (same pattern as validators()/views()).
+     */
+    defaultValue() {
+        return this.cached("defaultValue", () => {
+            const raw = this.ownAttr(FIELD_ATTR_DEFAULT);
+            if (raw === undefined)
+                return undefined;
+            return this.coerce(raw);
+        });
+    }
+    get maxLength() {
+        const v = this.ownAttr(FIELD_ATTR_MAX_LENGTH);
+        return typeof v === "number" ? v : undefined;
+    }
+    get precision() {
+        const v = this.ownAttr(FIELD_ATTR_PRECISION);
+        return typeof v === "number" ? v : undefined;
+    }
+    get scale() {
+        const v = this.ownAttr(FIELD_ATTR_SCALE);
+        return typeof v === "number" ? v : undefined;
+    }
+    /** True if `@unique: true` is set on the field itself (column-level unique). */
+    get unique() {
+        return this.ownAttr(FIELD_ATTR_UNIQUE) === true;
+    }
+    /**
+     * True if the field is required (NOT NULL).
+     *
+     * Checks both `@required: true` attr and `validator.required` children —
+     * matches the codegen-ts isRequired() semantics.
+     */
+    get isRequired() {
+        if (this.ownAttr(FIELD_ATTR_REQUIRED) === true)
+            return true;
+        return this.validators().some((v) => v.subType === VALIDATOR_SUBTYPE_REQUIRED);
+    }
+    /** All effective validators (own + inherited via extends). Java parity: MetaField.getValidators() / getChildren(MetaValidator.class, true). */
+    validators() {
+        return this.cached("validators", () => this.children().filter((c) => c.type === TYPE_VALIDATOR));
+    }
+    /** Own validators only — excludes validators inherited via extends. Java parity: getChildren(Class, false). */
+    ownValidators() {
+        return this.cached("ownValidators", () => this.ownChildren().filter((c) => c.type === TYPE_VALIDATOR));
+    }
+    /** All effective views (own + inherited via extends). Java parity: MetaField.getViews() / getChildren(MetaView.class, true). */
+    views() {
+        return this.cached("views", () => this.children().filter((c) => c.type === TYPE_VIEW));
+    }
+    /** Own views only — excludes views inherited via extends. */
+    ownViews() {
+        return this.cached("ownViews", () => this.ownChildren().filter((c) => c.type === TYPE_VIEW));
+    }
+    /** The typed supertype field if `extends:` resolved, else undefined. */
+    resolveSuper() {
+        return this.superData;
+    }
+}
+//# sourceMappingURL=meta-field.js.map

package/dist/core/field/meta-field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-field.js","sourceRoot":"","sources":["../../../src/core/field/meta-field.ts"],"names":[],"mappings":"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"}

package/dist/core/file-meta-data-loader.d.ts

@@ -0,0 +1,18 @@
+import { MetaDataLoader, type LoadResult } from "../loader/meta-data-loader.js";
+import type { ParseOptions, ParseResult } from "../parser-core.js";
+import type { MetaDataSource } from "../loader/meta-data-source.js";
+export declare class FileMetaDataLoader extends MetaDataLoader {
+    /** Adds YAML parsing on top of the base loader's JSON-only `parseSource`. */
+    protected parseSource(content: string, source: MetaDataSource, parseOpts: ParseOptions): ParseResult;
+    /**
+     * Load every `.json` / `.yaml` / `.yml` file in a directory (non-recursive),
+     * in deterministic ordinal filename order.
+     * @param opts.exclude glob patterns (relative to dir) to skip — `*` / `**`.
+     */
+    loadDirectory(dir: string, opts?: {
+        exclude?: string[];
+    }): Promise<LoadResult>;
+    /** Load an explicit list of file paths, in order. */
+    loadFiles(paths: string[]): Promise<LoadResult>;
+}
+//# sourceMappingURL=file-meta-data-loader.d.ts.map

package/dist/core/file-meta-data-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-meta-data-loader.d.ts","sourceRoot":"","sources":["../../src/core/file-meta-data-loader.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAGhF,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAYpE,qBAAa,kBAAmB,SAAQ,cAAc;IACpD,6EAA6E;cAC1D,WAAW,CAC5B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,YAAY,GACtB,WAAW;IAOd;;;;OAIG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IA2CpF,qDAAqD;IAC/C,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC;CAGtD"}

package/dist/core/file-meta-data-loader.js

@@ -0,0 +1,81 @@
+// FileMetaDataLoader — discovers file-backed MetaDataSources and runs the
+// MetaDataLoader pipeline over them. A UrlMetaDataLoader will slot in the
+// same way later.
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { MetaDataLoader } from "../loader/meta-data-loader.js";
+import { FileSource } from "./file-source.js";
+import { parseYaml } from "./parser-yaml.js";
+/** Minimal glob matcher supporting `*` (any chars except `/`) and `**` (any chars). */
+function matchSimpleGlob(pattern, value) {
+    const regexStr = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "::DOUBLESTAR::")
+        .replace(/\*/g, "[^/]*")
+        .replace(/::DOUBLESTAR::/g, ".*");
+    return new RegExp(`^${regexStr}$`).test(value);
+}
+export class FileMetaDataLoader extends MetaDataLoader {
+    /** Adds YAML parsing on top of the base loader's JSON-only `parseSource`. */
+    parseSource(content, source, parseOpts) {
+        if (source.format === "yaml") {
+            return parseYaml(content, parseOpts);
+        }
+        return super.parseSource(content, source, parseOpts);
+    }
+    /**
+     * Load every `.json` / `.yaml` / `.yml` file in a directory (non-recursive),
+     * in deterministic ordinal filename order.
+     * @param opts.exclude glob patterns (relative to dir) to skip — `*` / `**`.
+     */
+    async loadDirectory(dir, opts) {
+        let entries;
+        try {
+            // Sorted for deterministic multi-file load order: the overlay merge is
+            // order-sensitive (last-writer-wins on attr conflicts), so the scan must
+            // not depend on filesystem readdir order. Ordinal filename sort is
+            // reproducible across the Java/Python/C# ports.
+            entries = (await readdir(dir)).sort();
+        }
+        catch (err) {
+            // Surface the I/O failure as a collected error via the empty-source path.
+            const emptyResult = await this.load([]);
+            return {
+                ...emptyResult,
+                errors: [
+                    new Error(`loadDirectory: cannot read ${dir}: ${err.message}`),
+                    ...emptyResult.errors,
+                ],
+            };
+        }
+        const excludes = opts?.exclude ?? [];
+        const paths = [];
+        for (const entry of entries) {
+            const lower = entry.toLowerCase();
+            if (!lower.endsWith(".json") && !lower.endsWith(".yaml") && !lower.endsWith(".yml")) {
+                continue;
+            }
+            const filePath = join(dir, entry);
+            let statResult;
+            try {
+                statResult = await stat(filePath);
+            }
+            catch {
+                // Entry vanished between readdir and stat (TOCTOU) or is not accessible.
+                // Skip it rather than breaking the no-throw contract of loadDirectory.
+                continue;
+            }
+            if (!statResult.isFile())
+                continue;
+            if (excludes.some((p) => matchSimpleGlob(p, entry)))
+                continue;
+            paths.push(filePath);
+        }
+        return this.loadFiles(paths);
+    }
+    /** Load an explicit list of file paths, in order. */
+    async loadFiles(paths) {
+        return this.load(paths.map((p) => new FileSource(p)));
+    }
+}
+//# sourceMappingURL=file-meta-data-loader.js.map

package/dist/core/file-meta-data-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-meta-data-loader.js","sourceRoot":"","sources":["../../src/core/file-meta-data-loader.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,0EAA0E;AAC1E,kBAAkB;AAGlB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,cAAc,EAAmB,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAI7C,uFAAuF;AACvF,SAAS,eAAe,CAAC,OAAe,EAAE,KAAa;IACrD,MAAM,QAAQ,GAAG,OAAO;SACrB,OAAO,CAAC,mBAAmB,EAAE,MAAM,CAAC;SACpC,OAAO,CAAC,OAAO,EAAE,gBAAgB,CAAC;SAClC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC;SACvB,OAAO,CAAC,iBAAiB,EAAE,IAAI,CAAC,CAAC;IACpC,OAAO,IAAI,MAAM,CAAC,IAAI,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,OAAO,kBAAmB,SAAQ,cAAc;IACpD,6EAA6E;IAC1D,WAAW,CAC5B,OAAe,EACf,MAAsB,EACtB,SAAuB;QAEvB,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC7B,OAAO,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,KAAK,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IACvD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,aAAa,CAAC,GAAW,EAAE,IAA6B;QAC5D,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACH,uEAAuE;YACvE,yEAAyE;YACzE,mEAAmE;YACnE,gDAAgD;YAChD,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACxC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,0EAA0E;YAC1E,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACxC,OAAO;gBACL,GAAG,WAAW;gBACd,MAAM,EAAE;oBACN,IAAI,KAAK,CAAC,8BAA8B,GAAG,KAAM,GAAa,CAAC,OAAO,EAAE,CAAC;oBACzE,GAAG,WAAW,CAAC,MAAM;iBACtB;aACF,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC;QACrC,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;YAClC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBACpF,SAAS;YACX,CAAC;YACD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAClC,IAAI,UAAiB,CAAC;YACtB,IAAI,CAAC;gBACH,UAAU,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;YACpC,CAAC;YAAC,MAAM,CAAC;gBACP,yEAAyE;gBACzE,uEAAuE;gBACvE,SAAS;YACX,CAAC;YACD,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE;gBAAE,SAAS;YACnC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;gBAAE,SAAS;YAC9D,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvB,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,qDAAqD;IACrD,KAAK,CAAC,SAAS,CAAC,KAAe;QAC7B,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,CAAC;CACF"}

package/dist/core/file-source.d.ts

@@ -0,0 +1,12 @@
+import type { MetaDataFormat, MetaDataSource } from "../loader/meta-data-source.js";
+/** A metadata source backed by a file on disk. */
+export declare class FileSource implements MetaDataSource {
+    readonly id: string;
+    readonly format: MetaDataFormat;
+    private readonly _path;
+    constructor(path: string);
+    /** The absolute/relative path this source reads from. */
+    get path(): string;
+    read(): Promise<string>;
+}
+//# sourceMappingURL=file-source.d.ts.map

package/dist/core/file-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-source.d.ts","sourceRoot":"","sources":["../../src/core/file-source.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAwBpF,kDAAkD;AAClD,qBAAa,UAAW,YAAW,cAAc;IAC/C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,IAAI,EAAE,MAAM;IAOxB,yDAAyD;IACzD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAEK,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAI9B"}

package/dist/core/file-source.js

@@ -0,0 +1,46 @@
+// FileSource — a MetaDataSource backed by a file on disk. Server-side only
+// (touches node:fs); lives under src/core/ so the browser-safe root never
+// imports it.
+import { basename, extname } from "node:path";
+/** Infer a source format from a file extension. `.yaml`/`.yml` → "yaml";
+ *  everything else (including `.json`) → "json", the canonical default. */
+function inferFormat(path) {
+    const ext = extname(path).toLowerCase();
+    return ext === ".yaml" || ext === ".yml" ? "yaml" : "json";
+}
+// File reader — Bun-first (Bun.file().text()) with a Node fallback
+// (node:fs/promises.readFile). Matches CLAUDE.md's Bun-first / Node-compatible policy.
+let _readText;
+async function getReadText() {
+    if (_readText !== undefined)
+        return _readText;
+    if (typeof Bun !== "undefined") {
+        _readText = (p) => Bun.file(p).text();
+    }
+    else {
+        const { readFile } = await import("node:fs/promises");
+        _readText = (p) => readFile(p, "utf-8");
+    }
+    return _readText;
+}
+/** A metadata source backed by a file on disk. */
+export class FileSource {
+    id;
+    format;
+    _path;
+    constructor(path) {
+        this._path = path;
+        // basename() for readable error messages; cross-platform (handles both / and \). Full path retained for read().
+        this.id = basename(path);
+        this.format = inferFormat(path);
+    }
+    /** The absolute/relative path this source reads from. */
+    get path() {
+        return this._path;
+    }
+    async read() {
+        const readText = await getReadText();
+        return readText(this._path);
+    }
+}
+//# sourceMappingURL=file-source.js.map

package/dist/core/file-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-source.js","sourceRoot":"","sources":["../../src/core/file-source.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,0EAA0E;AAC1E,cAAc;AAEd,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAG9C;2EAC2E;AAC3E,SAAS,WAAW,CAAC,IAAY;IAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;IACxC,OAAO,GAAG,KAAK,OAAO,IAAI,GAAG,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;AAC7D,CAAC;AAED,mEAAmE;AACnE,uFAAuF;AACvF,IAAI,SAA0D,CAAC;AAE/D,KAAK,UAAU,WAAW;IACxB,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC9C,IAAI,OAAO,GAAG,KAAK,WAAW,EAAE,CAAC;QAC/B,SAAS,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACxC,CAAC;SAAM,CAAC;QACN,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACtD,SAAS,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,kDAAkD;AAClD,MAAM,OAAO,UAAU;IACZ,EAAE,CAAS;IACX,MAAM,CAAiB;IACf,KAAK,CAAS;IAE/B,YAAY,IAAY;QACtB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,gHAAgH;QAChH,IAAI,CAAC,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,yDAAyD;IACzD,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,QAAQ,GAAG,MAAM,WAAW,EAAE,CAAC;QACrC,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;CACF"}

package/dist/core/identity/identity-constants.d.ts

@@ -0,0 +1,19 @@
+export declare const IDENTITY_SUBTYPE_PRIMARY = "primary";
+export declare const IDENTITY_SUBTYPE_SECONDARY = "secondary";
+export declare const IDENTITY_SUBTYPE_REFERENCE = "reference";
+export declare const IDENTITY_SUBTYPES: readonly ["primary", "secondary", "reference"];
+export type IdentitySubType = (typeof IDENTITY_SUBTYPES)[number];
+export declare const IDENTITY_ATTR_FIELDS = "fields";
+export declare const IDENTITY_ATTR_GENERATION = "generation";
+/** On secondary identities: true → uniqueIndex; false/absent → index. Defaults to true for back-compat. */
+export declare const IDENTITY_ATTR_UNIQUE = "unique";
+/** Identity-reference attr: target entity (bare or dotted `Entity.field` / `Entity.fA,fB`). */
+export declare const IDENTITY_REFERENCE_ATTR_REFERENCES = "references";
+/** Identity-reference attr: physical-enforcement flag. Default true → hard FK constraint; false → logical-only reference. */
+export declare const IDENTITY_REFERENCE_ATTR_ENFORCE = "enforce";
+export declare const GENERATION_INCREMENT = "increment";
+export declare const GENERATION_UUID = "uuid";
+export declare const GENERATION_ASSIGNED = "assigned";
+export declare const GENERATION_VALUES: readonly ["increment", "uuid", "assigned"];
+export type GenerationValue = (typeof GENERATION_VALUES)[number];
+//# sourceMappingURL=identity-constants.d.ts.map

package/dist/core/identity/identity-constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-constants.d.ts","sourceRoot":"","sources":["../../../src/core/identity/identity-constants.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,wBAAwB,YAAY,CAAC;AAClD,eAAO,MAAM,0BAA0B,cAAc,CAAC;AACtD,eAAO,MAAM,0BAA0B,cAAc,CAAC;AAEtD,eAAO,MAAM,iBAAiB,gDAIpB,CAAC;AACX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAMjE,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAC7C,eAAO,MAAM,wBAAwB,eAAe,CAAC;AACrD,2GAA2G;AAC3G,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAC7C,+FAA+F;AAC/F,eAAO,MAAM,kCAAkC,eAAe,CAAC;AAC/D,6HAA6H;AAC7H,eAAO,MAAM,+BAA+B,YAAY,CAAC;AAMzD,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAChD,eAAO,MAAM,eAAe,SAAS,CAAC;AACtC,eAAO,MAAM,mBAAmB,aAAa,CAAC;AAE9C,eAAO,MAAM,iBAAiB,4CAIpB,CAAC;AACX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/core/identity/identity-constants.js

@@ -0,0 +1,35 @@
+// Identity concern constants — subtypes, attr keys, and generation strategy values.
+// ---------------------------------------------------------------------------
+// Identity subtypes (3: primary, secondary, reference — NO base; Java doesn't register one)
+// ---------------------------------------------------------------------------
+export const IDENTITY_SUBTYPE_PRIMARY = "primary";
+export const IDENTITY_SUBTYPE_SECONDARY = "secondary";
+export const IDENTITY_SUBTYPE_REFERENCE = "reference";
+export const IDENTITY_SUBTYPES = [
+    IDENTITY_SUBTYPE_PRIMARY,
+    IDENTITY_SUBTYPE_SECONDARY,
+    IDENTITY_SUBTYPE_REFERENCE,
+];
+// ---------------------------------------------------------------------------
+// Identity attrs
+// ---------------------------------------------------------------------------
+export const IDENTITY_ATTR_FIELDS = "fields";
+export const IDENTITY_ATTR_GENERATION = "generation";
+/** On secondary identities: true → uniqueIndex; false/absent → index. Defaults to true for back-compat. */
+export const IDENTITY_ATTR_UNIQUE = "unique";
+/** Identity-reference attr: target entity (bare or dotted `Entity.field` / `Entity.fA,fB`). */
+export const IDENTITY_REFERENCE_ATTR_REFERENCES = "references";
+/** Identity-reference attr: physical-enforcement flag. Default true → hard FK constraint; false → logical-only reference. */
+export const IDENTITY_REFERENCE_ATTR_ENFORCE = "enforce";
+// ---------------------------------------------------------------------------
+// Identity generation strategies (values for IDENTITY_ATTR_GENERATION)
+// ---------------------------------------------------------------------------
+export const GENERATION_INCREMENT = "increment";
+export const GENERATION_UUID = "uuid";
+export const GENERATION_ASSIGNED = "assigned";
+export const GENERATION_VALUES = [
+    GENERATION_INCREMENT,
+    GENERATION_UUID,
+    GENERATION_ASSIGNED,
+];
+//# sourceMappingURL=identity-constants.js.map

package/dist/core/identity/identity-constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-constants.js","sourceRoot":"","sources":["../../../src/core/identity/identity-constants.ts"],"names":[],"mappings":"AAAA,oFAAoF;AAEpF,8EAA8E;AAC9E,4FAA4F;AAC5F,8EAA8E;AAE9E,MAAM,CAAC,MAAM,wBAAwB,GAAG,SAAS,CAAC;AAClD,MAAM,CAAC,MAAM,0BAA0B,GAAG,WAAW,CAAC;AACtD,MAAM,CAAC,MAAM,0BAA0B,GAAG,WAAW,CAAC;AAEtD,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,wBAAwB;IACxB,0BAA0B;IAC1B,0BAA0B;CAClB,CAAC;AAGX,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAC7C,MAAM,CAAC,MAAM,wBAAwB,GAAG,YAAY,CAAC;AACrD,2GAA2G;AAC3G,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAC7C,+FAA+F;AAC/F,MAAM,CAAC,MAAM,kCAAkC,GAAG,YAAY,CAAC;AAC/D,6HAA6H;AAC7H,MAAM,CAAC,MAAM,+BAA+B,GAAG,SAAS,CAAC;AAEzD,8EAA8E;AAC9E,uEAAuE;AACvE,8EAA8E;AAE9E,MAAM,CAAC,MAAM,oBAAoB,GAAG,WAAW,CAAC;AAChD,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC;AACtC,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC;AAE9C,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,oBAAoB;IACpB,eAAe;IACf,mBAAmB;CACX,CAAC"}

package/dist/core/identity/identity-schema.d.ts

@@ -0,0 +1,6 @@
+import type { AttrSchema } from "../../registry.js";
+/** Attrs on identity.primary / identity.secondary — @fields is required. */
+export declare const identityFieldsAttr: AttrSchema;
+/** Attrs per identity subtype. primary adds @generation; secondary adds @unique. */
+export declare const IDENTITY_ATTRS_MAP: Map<string, AttrSchema[]>;
+//# sourceMappingURL=identity-schema.d.ts.map

package/dist/core/identity/identity-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-schema.d.ts","sourceRoot":"","sources":["../../../src/core/identity/identity-schema.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAkBpD,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,EAAE,UAMhC,CAAC;AA8CF,oFAAoF;AACpF,eAAO,MAAM,kBAAkB,2BAI7B,CAAC"}

package/dist/core/identity/identity-schema.js

@@ -0,0 +1,55 @@
+// Identity attribute schemas — per-subtype attr inventories for identity types.
+// Consumed by registerCoreTypes().
+import { ATTR_SUBTYPE_STRING, ATTR_SUBTYPE_BOOLEAN, ATTR_SUBTYPE_STRINGARRAY, } from "../attr/attr-constants.js";
+import { IDENTITY_SUBTYPE_PRIMARY, IDENTITY_SUBTYPE_SECONDARY, IDENTITY_SUBTYPE_REFERENCE, IDENTITY_ATTR_FIELDS, IDENTITY_ATTR_GENERATION, IDENTITY_ATTR_UNIQUE, IDENTITY_REFERENCE_ATTR_REFERENCES, IDENTITY_REFERENCE_ATTR_ENFORCE, GENERATION_VALUES, } from "./identity-constants.js";
+/** Attrs on identity.primary / identity.secondary — @fields is required. */
+export const identityFieldsAttr = {
+    name: IDENTITY_ATTR_FIELDS,
+    valueType: ATTR_SUBTYPE_STRINGARRAY,
+    required: true,
+    description: "The field name(s) composing this identity. Single-element for a simple PK/index, multiple for a composite.",
+};
+const primaryIdentityAttrs = [
+    { ...identityFieldsAttr },
+    {
+        name: IDENTITY_ATTR_GENERATION,
+        valueType: ATTR_SUBTYPE_STRING,
+        required: false,
+        allowedValues: [...GENERATION_VALUES],
+        description: "Primary-key value generation strategy: 'increment' (auto-increment), 'uuid', or 'assigned' (caller-supplied).",
+    },
+];
+const secondaryIdentityAttrs = [
+    { ...identityFieldsAttr },
+    {
+        name: IDENTITY_ATTR_UNIQUE,
+        valueType: ATTR_SUBTYPE_BOOLEAN,
+        required: false,
+        description: "When true (default), the secondary identity is a UNIQUE index; false makes it a plain (non-unique) index.",
+    },
+];
+const referenceIdentityAttrs = [
+    { ...identityFieldsAttr },
+    {
+        name: IDENTITY_REFERENCE_ATTR_REFERENCES,
+        valueType: ATTR_SUBTYPE_STRING,
+        required: true,
+        description: "Target of the reference. Bare entity name (e.g. 'Program') resolves to that entity's primary identity. " +
+            "Dotted forms ('Program.id' or 'Program.fieldA,fieldB') target an explicit field set on the entity.",
+    },
+    {
+        name: IDENTITY_REFERENCE_ATTR_ENFORCE,
+        valueType: ATTR_SUBTYPE_BOOLEAN,
+        required: false,
+        description: "When true (default), the backend physically enforces the reference (SQL FK constraint, " +
+            "document validation rule, graph edge guarantee). Set false to declare a logical reference " +
+            "for navigation/typing/codegen only — the value may dangle at the backend level.",
+    },
+];
+/** Attrs per identity subtype. primary adds @generation; secondary adds @unique. */
+export const IDENTITY_ATTRS_MAP = new Map([
+    [IDENTITY_SUBTYPE_PRIMARY, [...primaryIdentityAttrs]],
+    [IDENTITY_SUBTYPE_SECONDARY, [...secondaryIdentityAttrs]],
+    [IDENTITY_SUBTYPE_REFERENCE, [...referenceIdentityAttrs]],
+]);
+//# sourceMappingURL=identity-schema.js.map

package/dist/core/identity/identity-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-schema.js","sourceRoot":"","sources":["../../../src/core/identity/identity-schema.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,mCAAmC;AAGnC,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,0BAA0B,EAC1B,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,EACpB,kCAAkC,EAClC,+BAA+B,EAC/B,iBAAiB,GAClB,MAAM,yBAAyB,CAAC;AAEjC,4EAA4E;AAC5E,MAAM,CAAC,MAAM,kBAAkB,GAAe;IAC5C,IAAI,EAAE,oBAAoB;IAC1B,SAAS,EAAE,wBAAwB;IACnC,QAAQ,EAAE,IAAI;IACd,WAAW,EACT,4GAA4G;CAC/G,CAAC;AAEF,MAAM,oBAAoB,GAAiB;IACzC,EAAE,GAAG,kBAAkB,EAAE;IACzB;QACE,IAAI,EAAE,wBAAwB;QAC9B,SAAS,EAAE,mBAAmB;QAC9B,QAAQ,EAAE,KAAK;QACf,aAAa,EAAE,CAAC,GAAG,iBAAiB,CAAC;QACrC,WAAW,EACT,+GAA+G;KAClH;CACF,CAAC;AAEF,MAAM,sBAAsB,GAAiB;IAC3C,EAAE,GAAG,kBAAkB,EAAE;IACzB;QACE,IAAI,EAAE,oBAAoB;QAC1B,SAAS,EAAE,oBAAoB;QAC/B,QAAQ,EAAE,KAAK;QACf,WAAW,EACT,2GAA2G;KAC9G;CACF,CAAC;AAEF,MAAM,sBAAsB,GAAiB;IAC3C,EAAE,GAAG,kBAAkB,EAAE;IACzB;QACE,IAAI,EAAE,kCAAkC;QACxC,SAAS,EAAE,mBAAmB;QAC9B,QAAQ,EAAE,IAAI;QACd,WAAW,EACT,yGAAyG;YACzG,oGAAoG;KACvG;IACD;QACE,IAAI,EAAE,+BAA+B;QACrC,SAAS,EAAE,oBAAoB;QAC/B,QAAQ,EAAE,KAAK;QACf,WAAW,EACT,yFAAyF;YACzF,4FAA4F;YAC5F,iFAAiF;KACpF;CACF,CAAC;AAEF,oFAAoF;AACpF,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAuB;IAC9D,CAAC,wBAAwB,EAAE,CAAC,GAAG,oBAAoB,CAAC,CAAC;IACrD,CAAC,0BAA0B,EAAE,CAAC,GAAG,sBAAsB,CAAC,CAAC;IACzD,CAAC,0BAA0B,EAAE,CAAC,GAAG,sBAAsB,CAAC,CAAC;CAC1D,CAAC,CAAC"}

package/dist/core/identity/meta-identity.d.ts

@@ -0,0 +1,71 @@
+import { MetaData } from "../../shared/meta-data.js";
+import type { MetaRoot } from "../../shared/meta-root.js";
+/** Strongly-typed identity generation strategies. */
+export type IdentityGeneration = "increment" | "uuid" | "assigned";
+export declare class MetaIdentity extends MetaData {
+    get fields(): string[];
+    /**
+     * Whether the identity enforces uniqueness.
+     * Defaults to true; explicit `@unique: false` makes it a non-unique index.
+     */
+    get unique(): boolean;
+    isPrimary(): boolean;
+    isSecondary(): boolean;
+    isReference(): boolean;
+    isComposite(): boolean;
+}
+/**
+ * Primary identity (the entity's PK). Always unique by definition.
+ * Carries `@generation` (increment / uuid / assigned).
+ */
+export declare class MetaPrimaryIdentity extends MetaIdentity {
+    get generation(): IdentityGeneration | undefined;
+}
+/**
+ * Secondary identity — a unique or non-unique index on one or more fields.
+ * `@generation` does not apply here.
+ */
+export declare class MetaSecondaryIdentity extends MetaIdentity {
+}
+/**
+ * Reference identity — a field (or compound field set) on this entity whose
+ * value(s) identify an instance of another entity.
+ *
+ * Maps to: SQL foreign key, document linked reference, graph edge target,
+ * OO pointer/reference. Backend-agnostic at the metamodel level.
+ *
+ * Carries `@references` — either a bare entity name (defaults to that
+ * entity's primary identity) or a dotted `Entity.field` or
+ * `Entity.fieldA,fieldB` form for explicit field/compound targets.
+ */
+export declare class MetaReferenceIdentity extends MetaIdentity {
+    /** Raw `@references` attr value, unparsed. */
+    get referencesRaw(): string | undefined;
+    /** Target entity name (the bit before the dot, or the whole bare value). */
+    get targetEntity(): string | undefined;
+    /**
+     * Whether the reference is physically enforced by the backend.
+     * Default true (hard FK constraint emitted). Explicit `@enforce: false`
+     * marks the reference as logical-only — drizzle-schema skips `.references()`
+     * and migrate-ts's expected schema omits the FK descriptor. relations()
+     * block and projection JOIN inference are unaffected.
+     */
+    get enforce(): boolean;
+    /**
+     * Target field names. Empty array means "use the target's primary identity"
+     * (the bare-entity form). For dotted forms, returns the field(s) after the
+     * dot (comma-split, trimmed).
+     */
+    get targetFields(): string[];
+    /**
+     * Resolve the target field on the referenced entity that this reference
+     * points at. Priority: explicit dotted-form `@references: "Entity.field"`
+     * override → target entity's primary identity field → "id" fallback.
+     *
+     * Returns undefined only if the target entity cannot be found in `root`.
+     * Centralizes the FK-target resolution rule used by projection view DDL,
+     * Drizzle schema emit, and migration schema comparison.
+     */
+    resolvedTargetPkField(root: MetaRoot): string | undefined;
+}
+//# sourceMappingURL=meta-identity.d.ts.map

package/dist/core/identity/meta-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-identity.d.ts","sourceRoot":"","sources":["../../../src/core/identity/meta-identity.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAWrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1D,qDAAqD;AACrD,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,MAAM,GAAG,UAAU,CAAC;AAEnE,qBAAa,YAAa,SAAQ,QAAQ;IACxC,IAAI,MAAM,IAAI,MAAM,EAAE,CAGrB;IAED;;;OAGG;IACH,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,SAAS,IAAI,OAAO;IAIpB,WAAW,IAAI,OAAO;IAItB,WAAW,IAAI,OAAO;IAItB,WAAW,IAAI,OAAO;CAGvB;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IACnD,IAAI,UAAU,IAAI,kBAAkB,GAAG,SAAS,CAG/C;CACF;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;CAAG;AAE1D;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;IACrD,8CAA8C;IAC9C,IAAI,aAAa,IAAI,MAAM,GAAG,SAAS,CAGtC;IAED,4EAA4E;IAC5E,IAAI,YAAY,IAAI,MAAM,GAAG,SAAS,CAKrC;IAED;;;;;;OAMG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;OAIG;IACH,IAAI,YAAY,IAAI,MAAM,EAAE,CAU3B;IAED;;;;;;;;OAQG;IACH,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS;CAe1D"}