@sequenceholdings/orm 0.1.3 → 2.1.0

package/dist/authoring.d.cts

@@ -48,6 +48,12 @@ declare class ColumnBuilder {
      * (`'gen_random_uuid()'` / `'now()'`), which serialize as `defaultFn`.
      */
     default(value: ColumnDefaultLiteral): this;
+    /**
+     * Stamp this column with Postgres `now()` on every UPDATE. Only valid on
+     * timestamptz/date; the compiler drops it from SetInput so callers cannot
+     * supply a value.
+     */
+    onUpdate(value: 'now()'): this;
     description(text: string): this;
     /** Migration rename hint: the previous Postgres column name. */
     renamedFrom(previousColumnName: string): this;
@@ -324,6 +330,15 @@ interface IndexInput {
     unique?: boolean;
     name?: string;
 }
+/** Database integrity constraint; independent of GraphQL relationship traversal. */
+interface ForeignKeyInput {
+    name: string;
+    columns: readonly string[];
+    target: TableRef;
+    references: readonly string[];
+    /** Omit for immediate, non-deferrable PostgreSQL enforcement. */
+    deferrable?: 'initially-immediate' | 'initially-deferred';
+}
 interface TableConfig {
     description?: string;
     /** Table-level migration rename hint (new in v2). */
@@ -331,6 +346,7 @@ interface TableConfig {
     /** Composite primary key: property names (or column names). Mutually exclusive with column-level `.primaryKey()`. */
     primaryKey?: readonly string[];
     indexes?: readonly IndexInput[];
+    foreignKeys?: readonly ForeignKeyInput[];
     links?: Record<string, SeqLink>;
     policies?: TablePoliciesInput;
     /**
@@ -491,9 +507,10 @@ declare const NAMESPACE_CONFIG_FILE = "sequence.config.ts";
 declare const SCHEMA_DIR = "schema";
 interface LoadNamespaceOptions {
     /**
-     * Test/dev hook: absolute path that bare `'@sequenceholdings/orm'` imports
-     * in consumer files resolve to (jiti alias). Leave unset in production —
-     * the consumer's own installed package resolves naturally.
+     * Test/dev hook: absolute path that package-root and `/authoring` imports
+     * in consumer files resolve to (jiti aliases). `/drizzle` still resolves to
+     * the SDK-pinned query utilities. Leave unset in production — the consumer's
+     * own installed package resolves naturally.
      */
     ormModulePath?: string;
 }
@@ -536,4 +553,4 @@ declare function beginAuthoringContext(): AuthoringContext;
 declare function endAuthoringContext(context: AuthoringContext): void;
 declare function activeAuthoringContext(): AuthoringContext | undefined;
 
-export { type AuthoringContext, type AuthoringRegistration, COLUMN_BRAND, COLUMN_DEFAULT_FNS, ColumnBuilder, type ColumnDefaultFn, type ColumnDefaultLiteral, type ColumnTypeSpec, type CowMutationInput, type DrizzleRelation, ENUM_BRAND, type EnumRef, type IndexInput, LINK_BRAND, type LinkKind, type LoadNamespaceOptions, type LoadedNamespaceV2, NAMESPACE_CONFIG_BRAND, NAMESPACE_CONFIG_FILE, type NamespaceCapabilitiesInput, type NamespaceConfigInput, ORM_TO_PIPELINE_TYPE, type OrmContractColumnMap, type OrmContractPipelineColumn, type OrmSyncedTableContract, type OrmToPipelineType, type OverlayTableRef, type OverlayWinsUnionInput, type OverrideRowMutationInput, type PolicyInput, type PolicyVariantInput, type PolicyWithVariantsInput, type RelationRef, type RevertOverlayMutationInput, SCHEMA_DIR, SYNCED_CONTRACT_HASH_DOMAIN, type SeqLink, type SeqNamespaceConfig, type SeqTable, type SeqView, type SerializeNamespaceInput, type SyncedTableConfig, type SyncedTablePoliciesInput, TABLE_BRAND, type TableConfig, type TablePoliciesInput, type TableRef, type ToManyOptions, type ToOneOptions, type ToPlatformUserOptions, type TypedSyncedTableConfig, VIEW_BRAND, type ViewConfig, type ViewPoliciesInput, type ViewQueryContext, type ViewSelectQuery, activeAuthoringContext, beginAuthoringContext, computeCanonicalHash, computeSyncedContractHash, defineEnum, defineNamespace, defineSyncedTable, defineTable, defineView, deriveColumnName, endAuthoringContext, extractOrmSyncedTableContract, isColumnBuilder, isEnumRef, isSeqLink, isSeqNamespaceConfig, isSeqTable, isSeqView, loadNamespaceFromDir, overlayWinsUnion, overrideRowMutation, revertOverlayMutation, serializeNamespace, syncedContractSurface, t, toMany, toOne, toPlatformUser };
+export { type AuthoringContext, type AuthoringRegistration, COLUMN_BRAND, COLUMN_DEFAULT_FNS, ColumnBuilder, type ColumnDefaultFn, type ColumnDefaultLiteral, type ColumnTypeSpec, type CowMutationInput, type DrizzleRelation, ENUM_BRAND, type EnumRef, type ForeignKeyInput, type IndexInput, LINK_BRAND, type LinkKind, type LoadNamespaceOptions, type LoadedNamespaceV2, NAMESPACE_CONFIG_BRAND, NAMESPACE_CONFIG_FILE, type NamespaceCapabilitiesInput, type NamespaceConfigInput, ORM_TO_PIPELINE_TYPE, type OrmContractColumnMap, type OrmContractPipelineColumn, type OrmSyncedTableContract, type OrmToPipelineType, type OverlayTableRef, type OverlayWinsUnionInput, type OverrideRowMutationInput, type PolicyInput, type PolicyVariantInput, type PolicyWithVariantsInput, type RelationRef, type RevertOverlayMutationInput, SCHEMA_DIR, SYNCED_CONTRACT_HASH_DOMAIN, type SeqLink, type SeqNamespaceConfig, type SeqTable, type SeqView, type SerializeNamespaceInput, type SyncedTableConfig, type SyncedTablePoliciesInput, TABLE_BRAND, type TableConfig, type TablePoliciesInput, type TableRef, type ToManyOptions, type ToOneOptions, type ToPlatformUserOptions, type TypedSyncedTableConfig, VIEW_BRAND, type ViewConfig, type ViewPoliciesInput, type ViewQueryContext, type ViewSelectQuery, activeAuthoringContext, beginAuthoringContext, computeCanonicalHash, computeSyncedContractHash, defineEnum, defineNamespace, defineSyncedTable, defineTable, defineView, deriveColumnName, endAuthoringContext, extractOrmSyncedTableContract, isColumnBuilder, isEnumRef, isSeqLink, isSeqNamespaceConfig, isSeqTable, isSeqView, loadNamespaceFromDir, overlayWinsUnion, overrideRowMutation, revertOverlayMutation, serializeNamespace, syncedContractSurface, t, toMany, toOne, toPlatformUser };

package/dist/authoring.d.ts

@@ -48,6 +48,12 @@ declare class ColumnBuilder {
      * (`'gen_random_uuid()'` / `'now()'`), which serialize as `defaultFn`.
      */
     default(value: ColumnDefaultLiteral): this;
+    /**
+     * Stamp this column with Postgres `now()` on every UPDATE. Only valid on
+     * timestamptz/date; the compiler drops it from SetInput so callers cannot
+     * supply a value.
+     */
+    onUpdate(value: 'now()'): this;
     description(text: string): this;
     /** Migration rename hint: the previous Postgres column name. */
     renamedFrom(previousColumnName: string): this;
@@ -324,6 +330,15 @@ interface IndexInput {
     unique?: boolean;
     name?: string;
 }
+/** Database integrity constraint; independent of GraphQL relationship traversal. */
+interface ForeignKeyInput {
+    name: string;
+    columns: readonly string[];
+    target: TableRef;
+    references: readonly string[];
+    /** Omit for immediate, non-deferrable PostgreSQL enforcement. */
+    deferrable?: 'initially-immediate' | 'initially-deferred';
+}
 interface TableConfig {
     description?: string;
     /** Table-level migration rename hint (new in v2). */
@@ -331,6 +346,7 @@ interface TableConfig {
     /** Composite primary key: property names (or column names). Mutually exclusive with column-level `.primaryKey()`. */
     primaryKey?: readonly string[];
     indexes?: readonly IndexInput[];
+    foreignKeys?: readonly ForeignKeyInput[];
     links?: Record<string, SeqLink>;
     policies?: TablePoliciesInput;
     /**
@@ -491,9 +507,10 @@ declare const NAMESPACE_CONFIG_FILE = "sequence.config.ts";
 declare const SCHEMA_DIR = "schema";
 interface LoadNamespaceOptions {
     /**
-     * Test/dev hook: absolute path that bare `'@sequenceholdings/orm'` imports
-     * in consumer files resolve to (jiti alias). Leave unset in production —
-     * the consumer's own installed package resolves naturally.
+     * Test/dev hook: absolute path that package-root and `/authoring` imports
+     * in consumer files resolve to (jiti aliases). `/drizzle` still resolves to
+     * the SDK-pinned query utilities. Leave unset in production — the consumer's
+     * own installed package resolves naturally.
      */
     ormModulePath?: string;
 }
@@ -536,4 +553,4 @@ declare function beginAuthoringContext(): AuthoringContext;
 declare function endAuthoringContext(context: AuthoringContext): void;
 declare function activeAuthoringContext(): AuthoringContext | undefined;
 
-export { type AuthoringContext, type AuthoringRegistration, COLUMN_BRAND, COLUMN_DEFAULT_FNS, ColumnBuilder, type ColumnDefaultFn, type ColumnDefaultLiteral, type ColumnTypeSpec, type CowMutationInput, type DrizzleRelation, ENUM_BRAND, type EnumRef, type IndexInput, LINK_BRAND, type LinkKind, type LoadNamespaceOptions, type LoadedNamespaceV2, NAMESPACE_CONFIG_BRAND, NAMESPACE_CONFIG_FILE, type NamespaceCapabilitiesInput, type NamespaceConfigInput, ORM_TO_PIPELINE_TYPE, type OrmContractColumnMap, type OrmContractPipelineColumn, type OrmSyncedTableContract, type OrmToPipelineType, type OverlayTableRef, type OverlayWinsUnionInput, type OverrideRowMutationInput, type PolicyInput, type PolicyVariantInput, type PolicyWithVariantsInput, type RelationRef, type RevertOverlayMutationInput, SCHEMA_DIR, SYNCED_CONTRACT_HASH_DOMAIN, type SeqLink, type SeqNamespaceConfig, type SeqTable, type SeqView, type SerializeNamespaceInput, type SyncedTableConfig, type SyncedTablePoliciesInput, TABLE_BRAND, type TableConfig, type TablePoliciesInput, type TableRef, type ToManyOptions, type ToOneOptions, type ToPlatformUserOptions, type TypedSyncedTableConfig, VIEW_BRAND, type ViewConfig, type ViewPoliciesInput, type ViewQueryContext, type ViewSelectQuery, activeAuthoringContext, beginAuthoringContext, computeCanonicalHash, computeSyncedContractHash, defineEnum, defineNamespace, defineSyncedTable, defineTable, defineView, deriveColumnName, endAuthoringContext, extractOrmSyncedTableContract, isColumnBuilder, isEnumRef, isSeqLink, isSeqNamespaceConfig, isSeqTable, isSeqView, loadNamespaceFromDir, overlayWinsUnion, overrideRowMutation, revertOverlayMutation, serializeNamespace, syncedContractSurface, t, toMany, toOne, toPlatformUser };
+export { type AuthoringContext, type AuthoringRegistration, COLUMN_BRAND, COLUMN_DEFAULT_FNS, ColumnBuilder, type ColumnDefaultFn, type ColumnDefaultLiteral, type ColumnTypeSpec, type CowMutationInput, type DrizzleRelation, ENUM_BRAND, type EnumRef, type ForeignKeyInput, type IndexInput, LINK_BRAND, type LinkKind, type LoadNamespaceOptions, type LoadedNamespaceV2, NAMESPACE_CONFIG_BRAND, NAMESPACE_CONFIG_FILE, type NamespaceCapabilitiesInput, type NamespaceConfigInput, ORM_TO_PIPELINE_TYPE, type OrmContractColumnMap, type OrmContractPipelineColumn, type OrmSyncedTableContract, type OrmToPipelineType, type OverlayTableRef, type OverlayWinsUnionInput, type OverrideRowMutationInput, type PolicyInput, type PolicyVariantInput, type PolicyWithVariantsInput, type RelationRef, type RevertOverlayMutationInput, SCHEMA_DIR, SYNCED_CONTRACT_HASH_DOMAIN, type SeqLink, type SeqNamespaceConfig, type SeqTable, type SeqView, type SerializeNamespaceInput, type SyncedTableConfig, type SyncedTablePoliciesInput, TABLE_BRAND, type TableConfig, type TablePoliciesInput, type TableRef, type ToManyOptions, type ToOneOptions, type ToPlatformUserOptions, type TypedSyncedTableConfig, VIEW_BRAND, type ViewConfig, type ViewPoliciesInput, type ViewQueryContext, type ViewSelectQuery, activeAuthoringContext, beginAuthoringContext, computeCanonicalHash, computeSyncedContractHash, defineEnum, defineNamespace, defineSyncedTable, defineTable, defineView, deriveColumnName, endAuthoringContext, extractOrmSyncedTableContract, isColumnBuilder, isEnumRef, isSeqLink, isSeqNamespaceConfig, isSeqTable, isSeqView, loadNamespaceFromDir, overlayWinsUnion, overrideRowMutation, revertOverlayMutation, serializeNamespace, syncedContractSurface, t, toMany, toOne, toPlatformUser };

package/dist/authoring.js

@@ -30,6 +30,7 @@ var ColumnBuilder = class {
       hasDefault: false,
       defaultValue: void 0,
       defaultFn: void 0,
+      onUpdateFn: void 0,
       description: void 0,
       renamedFrom: void 0,
       cast: void 0,
@@ -65,6 +66,15 @@ var ColumnBuilder = class {
     this.state.defaultFn = void 0;
     return this;
   }
+  /**
+   * Stamp this column with Postgres `now()` on every UPDATE. Only valid on
+   * timestamptz/date; the compiler drops it from SetInput so callers cannot
+   * supply a value.
+   */
+  onUpdate(value) {
+    this.state.onUpdateFn = value;
+    return this;
+  }
   description(text2) {
     this.state.description = text2;
     return this;
@@ -108,6 +118,7 @@ var ColumnBuilder = class {
     };
     if (this.state.hasDefault) column.default = this.state.defaultValue ?? null;
     if (this.state.defaultFn !== void 0) column.defaultFn = this.state.defaultFn;
+    if (this.state.onUpdateFn !== void 0) column.onUpdateFn = this.state.onUpdateFn;
     if (this.state.description !== void 0) column.description = this.state.description;
     if (this.state.renamedFrom !== void 0) column.renamedFrom = this.state.renamedFrom;
     if (this.state.cast !== void 0) column.cast = this.state.cast;
@@ -135,6 +146,7 @@ var t = {
 // src/constants.ts
 var NAMESPACE_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;
 var IDENTIFIER_PATTERN = /^[a-z][a-z0-9_]*$/;
+var COLUMN_IDENTIFIER_PATTERN = /^_?[a-z][a-z0-9_]*$/;
 var MAX_IDENTIFIER_LENGTH = 63;
 var SYNCED_SOURCE_PATTERN = /^gold\.[a-z][a-z0-9_]*$/;
 var HASH_DOMAIN = "sequence-orm-definitions\0";
@@ -237,10 +249,10 @@ function isSeqLink(value) {
 function isSeqTable(value) {
   return typeof value === "object" && value !== null && value.kind === TABLE_BRAND;
 }
-function assertIdentifier({ value, what, file }) {
-  if (!IDENTIFIER_PATTERN.test(value) || value.length > MAX_IDENTIFIER_LENGTH) {
+function assertIdentifier({ value, what, file, pattern = IDENTIFIER_PATTERN }) {
+  if (!pattern.test(value) || value.length > MAX_IDENTIFIER_LENGTH) {
     throw new OrmDefinitionError(
-      `${what} "${value}" must match ${IDENTIFIER_PATTERN} and be at most ${MAX_IDENTIFIER_LENGTH} characters`,
+      `${what} "${value}" must match ${pattern} and be at most ${MAX_IDENTIFIER_LENGTH} characters`,
       file
     );
   }
@@ -261,7 +273,7 @@ function defineTable(name, columns, config = {}) {
       );
     }
     const columnName = builder.columnNameFor(propertyName);
-    assertIdentifier({ value: columnName, what: `table "${name}": column "${propertyName}" column name`, file });
+    assertIdentifier({ value: columnName, what: `table "${name}": column "${propertyName}" column name`, file, pattern: COLUMN_IDENTIFIER_PATTERN });
     const existing = seenColumnNames.get(columnName);
     if (existing !== void 0) {
       throw new OrmDefinitionError(
@@ -301,7 +313,8 @@ function defineSyncedTable(name, columnsOrConfig, maybeConfig) {
     assertIdentifier({
       value: columnName,
       what: `synced table "${name}": column "${propertyName}" column name`,
-      file
+      file,
+      pattern: COLUMN_IDENTIFIER_PATTERN
     });
     const existing = seenColumnNames.get(columnName);
     if (existing !== void 0) {
@@ -390,7 +403,7 @@ function defineView(name, columns, config) {
       );
     }
     const columnName = builder.columnNameFor(propertyName);
-    if (!IDENTIFIER_PATTERN.test(columnName) || columnName.length > MAX_IDENTIFIER_LENGTH) {
+    if (!COLUMN_IDENTIFIER_PATTERN.test(columnName) || columnName.length > MAX_IDENTIFIER_LENGTH) {
       throw new OrmDefinitionError(`view "${name}": column "${propertyName}" has invalid column name "${columnName}"`, file);
     }
     const existing = seenColumnNames.get(columnName);
@@ -839,6 +852,7 @@ function scalarColumnType(table, property, helper) {
 var CANONICAL_FORMAT = 2;
 var IDENTIFIER_RE = /^[a-z][a-z0-9_]*$/;
 var identifier = z.string().min(1).max(63).regex(IDENTIFIER_RE);
+var columnIdentifier = z.string().min(1).max(63).regex(COLUMN_IDENTIFIER_PATTERN);
 var COLUMN_TYPES = [
   "uuid",
   "text",
@@ -859,18 +873,33 @@ var canonicalEnumSchema = z.object({
 var canonicalColumnSchema = z.object({
   /** Property name in TS (camelCase); columnName is the Postgres name. */
   name: z.string().min(1).max(63),
-  columnName: identifier,
+  columnName: columnIdentifier,
   type: z.union([columnTypeSchema, z.object({ enum: identifier })]),
   nullable: z.boolean().default(true),
   unique: z.boolean().default(false),
   /** Literal default, or one of the allowlisted SQL functions. */
   default: z.union([z.string(), z.number(), z.boolean(), z.null()]).optional(),
   defaultFn: z.enum(["gen_random_uuid()", "now()"]).optional(),
+  /**
+   * Stamp this column from the database clock on UPDATE (`now()`). The
+   * column stays insertable (defaults fill gaps) but is omitted from
+   * SetInput / settable so callers cannot backdate it.
+   */
+  onUpdateFn: z.enum(["now()"]).optional(),
   description: z.string().max(500).optional(),
   /** Migration hints — same semantics as v1. */
-  renamedFrom: identifier.optional(),
+  renamedFrom: columnIdentifier.optional(),
   cast: z.string().max(200).optional(),
   deprecated: z.boolean().default(false)
+}).superRefine((column, ctx) => {
+  if (column.onUpdateFn === void 0) return;
+  if (typeof column.type !== "string" || column.type !== "timestamptz" && column.type !== "date") {
+    ctx.addIssue({
+      code: "custom",
+      path: ["onUpdateFn"],
+      message: `onUpdateFn '${column.onUpdateFn}' is only valid on timestamptz/date columns`
+    });
+  }
 });
 var canonicalLinkSchema = z.object({
   name: z.string().min(1).max(63),
@@ -878,15 +907,15 @@ var canonicalLinkSchema = z.object({
   /** Target table name (namespace-local). Absent for toPlatformUser. */
   target: identifier.optional(),
   /** FK column on the owning side (toOne/toPlatformUser: on this table; toMany: on the target). */
-  on: identifier,
+  on: columnIdentifier,
   /** Referenced column on the target (default: target's PK / platform user `sub`). */
-  references: identifier.optional(),
+  references: columnIdentifier.optional(),
   /** enforce: true emits a real FK constraint (same-namespace toOne only). */
   enforce: z.boolean().default(false),
   description: z.string().max(500).optional()
 });
 var canonicalIndexSchema = z.object({
-  columns: z.array(identifier).min(1),
+  columns: z.array(columnIdentifier).min(1),
   unique: z.boolean().default(false),
   name: identifier.optional()
 });
@@ -977,6 +1006,13 @@ var canonicalCowMutationSchema = z.object({
     }
   }
 });
+var canonicalForeignKeySchema = z.object({
+  name: identifier,
+  columns: z.array(columnIdentifier).min(1).max(8),
+  target: identifier,
+  references: z.array(columnIdentifier).min(1).max(8),
+  deferrable: z.enum(["initially-immediate", "initially-deferred"]).optional()
+}).strict();
 var canonicalTableSchema = z.object({
   table: identifier,
   description: z.string().max(2e3).optional(),
@@ -985,7 +1021,7 @@ var canonicalTableSchema = z.object({
   /** Synced/reflected read-only tables (`source: gold.*`) — v1 semantics. */
   source: z.string().regex(/^gold\.[a-z][a-z0-9_]*$/).optional(),
   columns: z.array(canonicalColumnSchema).default([]),
-  primaryKey: z.array(identifier).min(1).max(8).optional(),
+  primaryKey: z.array(columnIdentifier).min(1).max(8).optional(),
   links: z.array(canonicalLinkSchema).default([]),
   indexes: z.array(canonicalIndexSchema).default([]),
   policies: canonicalPoliciesSchema.default({}),
@@ -996,14 +1032,16 @@ var canonicalTableSchema = z.object({
    */
   actions: z.array(canonicalActionSchema).default([]),
   /** Optional (not defaulted) so pre-CoW canonical documents keep byte-identical hashes. */
-  cowMutations: z.array(canonicalCowMutationSchema).optional()
+  cowMutations: z.array(canonicalCowMutationSchema).optional(),
+  /** Omitted by old definitions, preserving their existing content hashes. */
+  foreignKeys: z.array(canonicalForeignKeySchema).max(100).optional()
 });
 var canonicalViewSchema = z.object({
   view: identifier,
   description: z.string().max(2e3).optional(),
   columns: z.array(canonicalColumnSchema).min(1),
   /** Logical identity for GraphQL only; PostgreSQL views have no PK constraint. */
-  primaryKey: z.array(identifier).min(1).max(8).optional(),
+  primaryKey: z.array(columnIdentifier).min(1).max(8).optional(),
   links: z.array(canonicalLinkSchema).default([]),
   policies: z.object({ read: policyExpressionSchema }).strict(),
   query: z.string().min(1).max(1e5).refine(isSingleViewQuerySql, {
@@ -1016,6 +1054,9 @@ var canonicalViewSchema = z.object({
     if (column.default !== void 0 || column.defaultFn !== void 0) {
       ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare a default` });
     }
+    if (column.onUpdateFn !== void 0) {
+      ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare onUpdateFn` });
+    }
     if (column.unique) {
       ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare unique` });
     }
@@ -1049,6 +1090,45 @@ var canonicalDefinitionSchema = z.object({
       ctx.addIssue({ code: "custom", path: ["tables", index, "table"], message: `duplicate relation '${table.table}'` });
     }
     seen.add(table.table);
+    if (table.source !== void 0) {
+      for (const [columnIndex, column] of table.columns.entries()) {
+        if (column.onUpdateFn !== void 0) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["tables", index, "columns", columnIndex],
+            message: `synced table '${table.table}' column '${column.name}' cannot declare onUpdateFn`
+          });
+        }
+      }
+    }
+  }
+  const fkTables = new Map(definition.tables.map((table) => [table.table, table]));
+  for (const [tableIndex, table] of definition.tables.entries()) {
+    const names = /* @__PURE__ */ new Set([
+      ...table.primaryKey?.length ? [`${table.table}_pkey`] : [],
+      ...table.columns.filter((column) => column.unique && !(table.primaryKey?.length === 1 && table.primaryKey[0] === column.columnName)).map((column) => `${table.table}_${column.columnName}_unique`),
+      ...table.links.filter((link) => link.enforce).map((link) => `fk_${table.table}_${link.name}`)
+    ]);
+    for (const [index, fk] of (table.foreignKeys ?? []).entries()) {
+      const fail = (message) => ctx.addIssue({ code: "custom", path: ["tables", tableIndex, "foreignKeys", index], message });
+      if (names.has(fk.name)) fail(`duplicate foreign key '${fk.name}'`);
+      names.add(fk.name);
+      const target = fkTables.get(fk.target);
+      if (table.source || !target || target.source) {
+        fail("foreign keys must connect owned tables in the same namespace");
+        continue;
+      }
+      if (fk.columns.length !== fk.references.length) fail("foreign key columns and references must have the same number of columns");
+      if (new Set(fk.columns).size !== fk.columns.length || new Set(fk.references).size !== fk.references.length) fail("foreign key columns must not repeat");
+      for (const [position, name] of fk.columns.entries()) {
+        const sourceColumn = table.columns.find((column) => column.columnName === name);
+        const targetColumn = target.columns.find((column) => column.columnName === fk.references[position]);
+        if (!sourceColumn || !targetColumn) fail("foreign key references an unknown column");
+        else if (JSON.stringify(sourceColumn.type) !== JSON.stringify(targetColumn.type)) fail("foreign key column types must match");
+      }
+      const uniqueKeys = [target.primaryKey ?? [], ...target.indexes.filter((index2) => index2.unique).map((index2) => index2.columns), ...target.columns.filter((column) => column.unique).map((column) => [column.columnName])];
+      if (!uniqueKeys.some((key) => key.length === fk.references.length && key.every((column) => fk.references.includes(column)))) fail("foreign key target columns must form a unique key");
+    }
   }
   const tableByName = new Map(definition.tables.map((table) => [table.table, table]));
   for (const [tableIndex, table] of definition.tables.entries()) {
@@ -1171,12 +1251,13 @@ function normalizeCanonical(definition) {
     ...definition,
     enums: sortByName(definition.enums),
     tables: [...definition.tables].sort((a, b) => a.table.localeCompare(b.table)).map((t2) => {
-      const { cowMutations, ...rest } = t2;
+      const { cowMutations, foreignKeys, ...rest } = t2;
       return {
         ...rest,
         links: sortByName(t2.links),
         indexes: [...t2.indexes].sort((a, b) => (a.name ?? a.columns.join("_")).localeCompare(b.name ?? b.columns.join("_"))),
         actions: sortByName(t2.actions),
+        ...foreignKeys?.length ? { foreignKeys: sortByName(foreignKeys) } : {},
         // Omitted entirely when absent/empty so pre-CoW documents hash unchanged.
         ...cowMutations !== void 0 && cowMutations.length > 0 ? { cowMutations: sortByName(cowMutations) } : {}
       };
@@ -1372,6 +1453,22 @@ function buildCanonicalTable({ table, relationsByName, enumsByName }) {
   } else if (columnLevelPk.length > 0) {
     candidate.primaryKey = columnLevelPk;
   }
+  if (table.config.foreignKeys?.length) {
+    if (table.source) throw new OrmDefinitionError(`synced table "${table.tableName}" cannot enforce foreign keys`, table.file);
+    candidate.foreignKeys = table.config.foreignKeys.map((fk) => {
+      const target = resolveRelationRef({ ref: fk.target, fail: (message) => {
+        throw new OrmDefinitionError(message, table.file);
+      } });
+      if (!isSeqTable(target) || !relationsByName.has(target.tableName)) throw new OrmDefinitionError("foreign key target must be a table in this namespace", table.file);
+      return {
+        name: fk.name,
+        columns: fk.columns.map((ref) => resolveColumnRef({ relation: table, ref, role: `foreign key "${fk.name}" column` })),
+        target: target.tableName,
+        references: fk.references.map((ref) => resolveColumnRef({ relation: target, ref, role: `foreign key "${fk.name}" reference` })),
+        ...fk.deferrable ? { deferrable: fk.deferrable } : {}
+      };
+    });
+  }
   for (const index of table.config.indexes ?? []) {
     const entry = {
       columns: index.columns.map((ref) => resolveColumnRef({ relation: table, ref, role: "index" }))
@@ -1424,6 +1521,12 @@ function buildCanonicalView({
     if (column.default !== void 0 || column.defaultFn !== void 0) {
       throw new OrmDefinitionError(`view "${view.viewName}": column "${propertyName}" cannot declare a default`, view.file);
     }
+    if (column.onUpdateFn !== void 0) {
+      throw new OrmDefinitionError(
+        `view "${view.viewName}": column "${propertyName}" cannot declare onUpdateFn`,
+        view.file
+      );
+    }
     if (column.unique) {
       throw new OrmDefinitionError(`view "${view.viewName}": column "${propertyName}" cannot declare unique`, view.file);
     }
@@ -1682,7 +1785,16 @@ async function loadNamespaceFromDir(dir, options = {}) {
   const jiti = createJiti(import.meta.url, {
     interopDefault: true,
     fsCache: false,
-    ...options.ormModulePath !== void 0 ? { alias: { "@sequenceholdings/orm": options.ormModulePath } } : {}
+    ...options.ormModulePath !== void 0 ? {
+      alias: {
+        // The public /drizzle barrel re-exports this pinned dependency.
+        // Explicitly map it before the root alias: otherwise jiti appends
+        // "/drizzle" to the overridden module's filename.
+        "@sequenceholdings/orm/drizzle": createRequire(import.meta.url).resolve("drizzle-orm"),
+        "@sequenceholdings/orm": options.ormModulePath,
+        "@sequenceholdings/orm/authoring": options.ormModulePath
+      }
+    } : {}
   });
   const context = beginAuthoringContext();
   try {