@vibeorm/schema 4.1.0 → 4.3.0

package/dist/ir.d.ts

@@ -6,8 +6,10 @@
  * extensions) consumes ONLY this — nothing else ever parses schema text.
  */
 import type { ExclusionIR } from "./exclusion.ts";
+import type { GeneratedColumnIR } from "./generated-columns.ts";
 import type { MigrationObjectIR, QualifiedSqlName } from "./migration-objects.ts";
-import type { PredicateIR } from "./predicate.ts";
+import type { PredicateExpression, PredicateIR } from "./predicate.ts";
+import type { RowRuleIR } from "./row-rules.ts";
 /** Datasource providers a schema may declare. */
 export type Provider = "postgresql" | "pglite" | "sqlite" | "mysql";
 /**
@@ -43,6 +45,8 @@ export declare function isEnumType(fieldType: FieldType): fieldType is {
  */
 export declare function fieldTypeIdentity(params: {
     type: FieldType;
+    nativeType?: string;
+    isUnsupported?: boolean;
 }): string;
 /** Default value declarations, normalized across schema sources. */
 export type DefaultValueIR = {
@@ -75,6 +79,11 @@ export type JsonSchemaRefIR = {
     readonly name: string;
     readonly from: string;
 };
+/** A consumer-owned runtime scalar validator export; executable values never enter SchemaIR. */
+export type ValidatorRefIR = {
+    readonly name: string;
+    readonly from: string;
+};
 /** A scalar/enum column on a model. */
 export type FieldIR = {
     readonly name: string;
@@ -87,6 +96,8 @@ export type FieldIR = {
     readonly isUnique: boolean;
     readonly isUpdatedAt: boolean;
     readonly default?: DefaultValueIR;
+    /** Stored database expression, distinct from a DEFAULT and never client-writable. */
+    readonly generated?: GeneratedColumnIR;
     /** Dialect-native type override (@db.*), verbatim (e.g. "VarChar(191)"). */
     readonly nativeType?: string;
     /** Migration-only namespace evidence, bound to the exact unsupported declaration it resolved. */
@@ -108,6 +119,8 @@ export type FieldIR = {
     readonly documentation?: string;
     /** Runtime JSON schema reference, resolved relative to each emitted entry. */
     readonly jsonSchema?: JsonSchemaRefIR;
+    /** Write-only non-JSON scalar validator, resolved relative to each emitted entry. */
+    readonly validator?: ValidatorRefIR;
     /**
      * Explicit column collation (`@collation("...")`) — String fields. Rendered
      * as `COLLATE` on mysql and silently INERT on postgres/sqlite (the `@db.*`
@@ -156,6 +169,19 @@ export type IndexFieldIR = {
     /** Qualified PostgreSQL class; omitted preserves ordinary index semantics. */
     readonly operatorClass?: QualifiedSqlName;
 };
+/** Complete ordered keys for an expression-bearing index; never client selectors. */
+export type IndexKeyTermIR = {
+    readonly kind: "field";
+    readonly field: IndexFieldIR;
+} | {
+    readonly kind: "expression";
+    readonly expression: PredicateExpression;
+    readonly sort?: "asc" | "desc";
+} | {
+    readonly kind: "raw";
+    readonly sql: string;
+    readonly sort?: "asc" | "desc";
+};
 export type IndexIR = {
     readonly name?: string;
     /** Physical unique constraint owning this index, when catalog-backed. */
@@ -170,6 +196,8 @@ export type IndexIR = {
     readonly clientName?: string;
     readonly kind: IndexKind;
     readonly fields: readonly IndexFieldIR[];
+    /** Complete ordered key list, with at least one expression/raw term; fields must be empty. */
+    readonly expressions?: readonly IndexKeyTermIR[];
     /** Partial index predicate (raw SQL), postgres/sqlite only (capability-gated). */
     readonly where?: string;
     /**
@@ -244,6 +272,8 @@ export type ModelIR = {
     /** Named CHECK constraints (@@check), including authored expression changes. */
     readonly exclusions?: readonly ExclusionIR[];
     readonly checks?: readonly CheckIR[];
+    /** Declared database row invariants, separate from CHECKs and user migration SQL. */
+    readonly rowRules?: readonly RowRuleIR[];
     /**
      * Row-scoping policy (`@@policy([field], context: "key")`): the runtime
      * fails closed on policied models until a context is bound ($withPolicy).

package/dist/local-date.d.ts

@@ -0,0 +1,21 @@
+import type { FieldType } from "./ir.ts";
+/** Recognize the supported string-backed calendar-day representation, including invalid lists. */
+export declare function isLocalDateField(params: {
+    readonly field: {
+        readonly type: FieldType;
+        readonly nativeType?: string;
+        readonly isUnsupported?: boolean;
+    };
+}): boolean;
+/** Validate canonical Gregorian calendar days in years 0001–9999 without parsing an instant. */
+export declare function isCanonicalLocalDate(params: {
+    readonly value: unknown;
+}): params is {
+    readonly value: string;
+};
+/** Mint the physical name of SQLite's owned local-date CHECK; admission validates its length and collisions. */
+export declare function localDateCheckName(params: {
+    readonly table: string;
+    readonly column: string;
+}): string;
+//# sourceMappingURL=local-date.d.ts.map

package/dist/physical-names.d.ts

@@ -15,7 +15,7 @@
  * names are refused when over the limit (validate.ts) — the author chose them
  * and can shorten them, whereas PostgreSQL would silently truncate.
  */
-import type { Dialect } from "./ir.ts";
+import type { Dialect, IndexIR, ModelIR } from "./ir.ts";
 /** How a dialect measures an identifier and where it stops honouring it. */
 export type IdentifierLimit = {
     /** Longest identifier the server keeps intact. */
@@ -67,6 +67,13 @@ export declare function defaultIndexName(params: {
     unique: boolean;
     dialect: Dialect;
 }): string;
+/** Default mapped functional-key name; only its prefix may be shortened. */
+export declare function defaultExpressionIndexName(params: {
+    readonly table: string;
+    readonly model: Pick<ModelIR, "name" | "fields">;
+    readonly index: IndexIR;
+    readonly dialect: Dialect;
+}): string;
 /**
  * Default foreign-key constraint name: `Table_col1_col2_fkey`, shortened to the
  * dialect's limit. `columns` are the PHYSICAL FK column names on the owning

package/dist/predicate.d.ts

@@ -22,11 +22,17 @@
  * A raw SQL string stays the documented escape hatch for anything this cannot
  * express; raw text is carried verbatim and never parsed back into a predicate.
  */
-import type { Dialect } from "./ir.ts";
+import type { Dialect, FieldType, ModelIR } from "./ir.ts";
 /** Comparison operators a schema predicate may use. Deliberately closed. */
 export type PredicateComparisonOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte";
 /** All comparison operators, for matrix-style iteration in tests and tooling. */
 export declare const PREDICATE_COMPARISON_OPS: readonly PredicateComparisonOp[];
+/** Numeric expression families; arithmetic never implicitly promotes a family. */
+export type PredicateNumericType = "Int" | "BigInt" | "Float" | "Decimal";
+/** Schema expression sites; node admission is separate from host availability. */
+export type PredicateUsage = "check" | "indexPredicate" | "exclusionPredicate" | "indexExpression";
+/** Sites whose root must be a Boolean predicate. */
+export type PredicateBooleanUsage = Exclude<PredicateUsage, "indexExpression">;
 /**
  * A reference to one of the model's own fields, by LOGICAL name. The mapped
  * physical column is resolved when the predicate is rendered.
@@ -43,7 +49,7 @@ export type PredicateValue = {
     readonly kind: "value";
     readonly value: string | number | boolean;
 };
-/** Scalar expressions. Computed expressions are qualified for PostgreSQL CHECKs only. */
+/** Scalar expressions; each node has independent per-usage admission. */
 export type PredicateExpression = PredicateFieldRef | {
     readonly kind: "jsonText";
     readonly field: PredicateFieldRef;
@@ -51,8 +57,15 @@ export type PredicateExpression = PredicateFieldRef | {
 } | {
     readonly kind: "length";
     readonly expression: PredicateExpression;
+} | {
+    readonly kind: "add" | "sub" | "mul";
+    readonly left: PredicateExpression;
+    readonly right: PredicateOperand;
+} | {
+    readonly kind: "lower" | "upper";
+    readonly expression: PredicateExpression;
 };
-/** Either side of a comparison: an expression, or a literal. */
+/** An expression or a literal; comparison and arithmetic left sides are expressions. */
 export type PredicateOperand = PredicateExpression | PredicateValue;
 /**
  * A boolean expression over one model's fields.
@@ -89,6 +102,35 @@ export type PredicateIR = {
     readonly kind: "isTrue";
     readonly operand: PredicateIR;
 };
+/** Every scalar, Boolean and literal node in the closed predicate vocabulary. */
+export type PredicateNodeKind = PredicateExpression["kind"] | PredicateIR["kind"] | PredicateValue["kind"];
+/** Allowed usages for every node; dialect objects freeze the table and its rows. */
+export type PredicateCapabilityTable = Readonly<Record<PredicateNodeKind, readonly PredicateUsage[]>>;
+/** Pre-order scalar expressions and distinct node kinds in first-seen order. */
+export type PredicateInspection = {
+    readonly expressions: readonly PredicateExpression[];
+    readonly nodeKinds: readonly PredicateNodeKind[];
+};
+/** Produced value type, independent of a source column's storage metadata. */
+export type PredicateResultType = {
+    readonly type: FieldType;
+    readonly refinement?: "localDate" | "nativeUuid";
+};
+/** Exactly one Boolean predicate or scalar expression is admitted at a time. */
+export type PredicateCapabilityInput = {
+    readonly predicate: PredicateIR;
+    readonly expression?: never;
+} | {
+    readonly expression: PredicateExpression;
+    readonly predicate?: never;
+};
+/** The first denied node, operand native type or arithmetic family, suitable for issue reporting. */
+export type PredicateCapabilityIssue = {
+    readonly feature: string;
+    readonly node: PredicateNodeKind;
+    /** Names the field and its native type when an operand's storage type is the reason. */
+    readonly hint?: string;
+};
 /** Narrow a predicate operand to a field reference. */
 export declare function isPredicateFieldRef(operand: PredicateOperand): operand is PredicateFieldRef;
 /**
@@ -100,18 +142,25 @@ export declare function isPredicateFieldRef(operand: PredicateOperand): operand
 export declare function predicateFieldNames(params: {
     predicate: PredicateIR;
 }): readonly string[];
-/** Walk every nested scalar expression and record whether CHECK-only nodes occur. */
+/** Inspect every nested node, refusing malformed untrusted IR with a typed error. */
 export declare function inspectPredicate(params: {
     predicate: PredicateIR;
-}): {
-    readonly expressions: readonly PredicateExpression[];
-    readonly checkOnly: boolean;
-};
-/** Refuse CHECK-only expressions in index/exclusion predicates and unqualified dialects. */
-export declare function assertPredicateCapabilities(params: {
-    predicate: PredicateIR;
-    dialect: Dialect;
-    usage: "check" | "indexPredicate" | "exclusionPredicate";
+}): PredicateInspection;
+/** Inspect scalar children independently of a Boolean predicate or SQL renderer. */
+export declare function inspectPredicateExpression(params: {
+    readonly expression: PredicateExpression;
+}): PredicateInspection;
+/** Report node/usage denial, and operand native-type and arithmetic-family denial when model facts are supplied. */
+export declare function predicateCapabilityIssue(params: PredicateCapabilityInput & {
+    readonly dialect: Dialect;
+    readonly usage: PredicateUsage;
+    readonly model?: Pick<ModelIR, "name" | "fields">;
+}): PredicateCapabilityIssue | undefined;
+/** Refuse denied nodes, operand native types or numeric families before schema SQL is emitted. */
+export declare function assertPredicateCapabilities(params: PredicateCapabilityInput & {
+    readonly dialect: Dialect;
+    readonly usage: PredicateUsage;
+    readonly model?: Pick<ModelIR, "name" | "fields">;
 }): void;
 /**
  * A stable, DIALECT-FREE key for a predicate.
@@ -124,6 +173,9 @@ export declare function assertPredicateCapabilities(params: {
  * It is NOT a semantic equivalence test: `a AND b` and `b AND a` get different
  * keys, deliberately. Guessing SQL equivalence is what constitution rule 4
  * forbids and what EPIC 1's live normalization exists for.
+ *
+ * Pre-arithmetic trees retain their exact legacy bytes; format selection never
+ * depends on capability admission.
  */
 export declare function predicateKey(params: {
     predicate: PredicateIR;

package/dist/referential-actions.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Effective foreign-key referential actions — Prisma's defaults, resolved ONCE.
+ *
+ * Migrate renders these into DDL and compares them; schema validation reads
+ * them to refuse a MySQL CHECK on a column an action writes. One rule, so the
+ * two can never disagree about what a relation does.
+ */
+import type { CascadeAction, FieldIR, RelationIR } from "./ir.ts";
+/**
+ * Effective onDelete — Prisma's default: a required foreign key (every column
+ * non-nullable) restricts, an optional one sets NULL.
+ */
+export declare function resolveOnDelete(params: {
+    explicit: CascadeAction | undefined;
+    required: boolean;
+}): CascadeAction;
+/** Effective onUpdate — Prisma's default is Cascade. */
+export declare function resolveOnUpdate(params: {
+    explicit: CascadeAction | undefined;
+}): CascadeAction;
+/**
+ * A relation's effective actions. Its foreign key is required when every
+ * foreign-key column is non-nullable — the fact the database sees, and the one
+ * Prisma's defaults key off. A column `field` cannot resolve counts as
+ * required; schema validation reports the unknown column separately.
+ */
+export declare function resolveReferentialActions(params: {
+    relation: Pick<RelationIR, "fields" | "onDelete" | "onUpdate">;
+    /** The relation model's field by LOGICAL name. */
+    field: (name: string) => FieldIR | undefined;
+}): {
+    readonly onDelete: CascadeAction;
+    readonly onUpdate: CascadeAction;
+};
+//# sourceMappingURL=referential-actions.d.ts.map

package/dist/row-rules.d.ts

@@ -0,0 +1,198 @@
+import type { Dialect, FieldIR, ModelIR, SchemaIR } from "./ir.ts";
+import type { MigrationObjectIR, SqlObjectIdentity } from "./migration-objects.ts";
+/** A fixed group is protected from insertion, or after OLD's nullable gate is set. */
+export type RowRuleWhenIR = {
+    readonly fromCreation: true;
+} | {
+    readonly onceSet: string;
+};
+/** Structured row invariant; names are resolved physical stems and fields are logical names. */
+export type RowRuleIR = {
+    readonly kind: "appendOnly";
+    readonly name: string;
+} | {
+    readonly kind: "fixed";
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly when: RowRuleWhenIR;
+} | {
+    readonly kind: "rowFixed";
+    readonly name: string;
+    readonly except: readonly string[];
+} | {
+    readonly kind: "frozen";
+    readonly name: string;
+    readonly from: {
+        readonly create: true;
+    } | {
+        readonly field: string;
+    };
+    readonly mutable: readonly string[];
+};
+/** Authoring data before the shared normalizer resolves the optional physical stem. */
+export type RowRuleSpec = {
+    readonly kind: "appendOnly";
+    readonly name?: string;
+} | {
+    readonly kind: "fixed";
+    readonly name?: string;
+    readonly columns: readonly string[];
+    readonly when: RowRuleWhenIR;
+} | {
+    readonly kind: "rowFixed";
+    readonly name?: string;
+    readonly except: readonly string[];
+} | {
+    readonly kind: "frozen";
+    readonly name?: string;
+    readonly from: {
+        readonly create: true;
+    } | {
+        readonly field: string;
+    };
+    readonly mutable: readonly string[];
+};
+/** Shared admission keys; later dialects can enable each rule independently. */
+export type RowRuleCapability = "rowRuleAppendOnly" | "rowRuleFixed" | "rowRuleRowFixed" | "rowRuleFrozen";
+/** A structural or semantic error, usable by the schema's aggregate validator. */
+export type RowRuleValidationIssue = {
+    readonly rule: string;
+    readonly message: string;
+    readonly model?: string;
+    readonly field?: string;
+};
+/** One physical object owned by a declaration, tagged with the part it plays. */
+export type RowRuleObject = {
+    readonly role: "function" | "trigger";
+    readonly identity: SqlObjectIdentity;
+};
+/**
+ * Every physical object one declaration owns, in creation order. PostgreSQL emits
+ * one function then one trigger; a later dialect may emit several triggers and no
+ * function, so consumers select by role instead of assuming a fixed pair.
+ */
+export type RowRuleIdentities = readonly RowRuleObject[];
+/** The row events owned by portable rule triggers. */
+export type RowRuleEvent = "update" | "delete";
+/** Reserved SQLite error payload; it is not evidence of object ownership. */
+export declare const SQLITE_ROW_RULE_ERROR_PREFIX: "VIBEORM_ROW_RULE:";
+/** Conservative UTF-8 bound on MySQL SIGNAL's completed MESSAGE_TEXT value. */
+export declare const MYSQL_ROW_RULE_MESSAGE_MAX_BYTES: 128;
+/** Count the decoded diagnostic value, never the SQL literal or its escaping. */
+export declare function mysqlRowRuleMessageByteLength(params: {
+    readonly triggerName: string;
+}): number;
+/** Decode only a nonempty reserved payload at the beginning of the message. */
+export declare function sqliteRowRuleConstraint(params: {
+    readonly message: string;
+}): string | undefined;
+/** Inspect canonical JSON shape, including nested unknown-key refusal, before catalog access. */
+export declare function rowRuleShapeIssue(params: {
+    value: unknown;
+}): string | undefined;
+/** Select the shared dialect capability for one declared rule. */
+export declare function rowRuleCapability(params: {
+    kind: RowRuleIR["kind"];
+}): RowRuleCapability;
+/** Refuse an unsupported rule with its exact feature key and authoring context. */
+export declare function assertRowRuleCapability(params: {
+    dialect: Dialect;
+    model: string;
+    rule: RowRuleIR | RowRuleSpec;
+}): void;
+/** Default stem from physical table/column names, without truncation or hashing. */
+export declare function defaultRowRuleName(params: {
+    model: Pick<ModelIR, "name" | "dbName" | "fields">;
+    rule: RowRuleSpec;
+}): string;
+/** Finished pair names; the stem never includes either suffix. */
+export declare function rowRuleObjectNames(params: {
+    rule: Pick<RowRuleIR, "name">;
+}): {
+    readonly functionName: string;
+    readonly triggerName: string;
+};
+/** Finished SQLite/MySQL event name, independent of the PostgreSQL pair helper. */
+export declare function rowRuleTriggerName(params: {
+    readonly rule: Pick<RowRuleIR, "name">;
+    readonly event: RowRuleEvent;
+}): string;
+/** OLD-value activation field, absent for creation-fixed and append-only rules. */
+export declare function rowRuleGateField(params: {
+    rule: RowRuleIR | RowRuleSpec;
+}): string | undefined;
+type RowRuleOwnedObject = Pick<MigrationObjectIR, "id" | "identity">;
+/** Internal, invocation-local preparation shared by schema validation passes. */
+export type RowRuleValidationContext = {
+    readonly objects: () => readonly RowRuleOwnedObject[];
+    readonly generatedFields: (params: {
+        model: ModelIR;
+    }) => ReadonlySet<string>;
+    readonly validate: (params: {
+        model: ModelIR;
+    }) => readonly RowRuleValidationIssue[];
+    readonly assertEquality: (params: {
+        model: ModelIR;
+        rule: RowRuleIR;
+    }) => void;
+};
+/** Prepare registered ownership lazily; no row rules means no migration-object reads. */
+export declare function createRowRuleValidationContext(params: {
+    schema: SchemaIR;
+    dialect?: Dialect;
+}): RowRuleValidationContext;
+/** Authored generated-column ownership identities mapped to logical keys. */
+export declare function rowRuleGeneratedFields(params: {
+    schema: SchemaIR;
+    model: ModelIR;
+}): readonly string[];
+/** Effective protected fields: explicit fixed order then gate; complements follow model order. */
+export declare function rowRuleProtectedFields(params: {
+    schema: SchemaIR;
+    model: ModelIR;
+    rule: RowRuleIR;
+}): readonly FieldIR[];
+/** Exact physical objects in creation order; only PostgreSQL owns a function. */
+export declare function rowRuleIdentities(params: {
+    schema: SchemaIR;
+    model: ModelIR;
+    rule: RowRuleIR;
+    dialect?: Dialect;
+    namespace?: string;
+}): RowRuleIdentities;
+/** Collect only exact declared core identities; a name prefix never implies ownership. */
+export declare function schemaRowRuleIdentities(params: {
+    schema: SchemaIR;
+    dialect?: Dialect;
+    namespace?: string;
+}): readonly SqlObjectIdentity[];
+/** Validate canonical declarations on a complete model, without throwing for structural failures. */
+export declare function validateRowRules(params: {
+    schema: SchemaIR;
+    model: ModelIR;
+}): readonly RowRuleValidationIssue[];
+/** Normalize source declarations, copy retained arrays and stabilize exception sets in model order. */
+export declare function normalizeRowRules(params: {
+    model: ModelIR;
+    rules: unknown;
+    dialect: Dialect;
+    schema?: SchemaIR;
+}): readonly RowRuleIR[];
+/** Refuse protected/gate types whose database equality is not part of the admitted contract. */
+export declare function assertRowRuleEquality(params: {
+    schema: SchemaIR;
+    model: ModelIR;
+    rule: RowRuleIR;
+    dialect?: Dialect;
+}): void;
+/** MySQL FK actions bypass child triggers; refuse declarations whose protection they evade. */
+export declare function assertRowRuleReferentialActions(params: {
+    readonly schema: SchemaIR;
+    readonly dialect?: Dialect;
+}): void;
+/** Lossless VibeORM .prisma attribute spelling, including resolved stems and tagged gates. */
+export declare function rowRulePrismaAttribute(params: {
+    rule: RowRuleIR;
+}): string;
+export {};
+//# sourceMappingURL=row-rules.d.ts.map

package/dist/validator-ref.d.ts

@@ -0,0 +1,22 @@
+import type { ValidatorRefIR } from "./ir.ts";
+/** A validator reference contains only serializable named-export and import-specifier data. */
+export declare function validatorRefIssue(params: {
+    readonly value: unknown;
+}): string | undefined;
+/** Validate, copy and freeze a reference without retaining its mutable authoring object. */
+export declare function assertValidatorRef(params: {
+    readonly value: unknown;
+}): ValidatorRefIR;
+/** Whether documentation contains a validator annotation requiring normalization. */
+export declare function hasValidatorAnnotation(params: {
+    readonly documentation: string | undefined;
+}): boolean;
+/** Move the validator annotation into dedicated metadata while preserving other documentation. */
+export declare function normalizeValidatorRef(params: {
+    readonly documentation?: string | undefined;
+    readonly reference?: unknown;
+}): {
+    readonly documentation?: string;
+    readonly validator?: ValidatorRefIR;
+};
+//# sourceMappingURL=validator-ref.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeorm/schema",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "Canonical schema IR, validation, dialect/capability types, and error codes for VibeORM v2",
   "keywords": [
     "orm",