@@ -0,0 +1,220 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#25491] An inline `FieldMappingEntry[]` mapping's per-cell rules
+ * (`transform`, `defaultValue`, `required`) are applied by the REAL
+ * `POST /data/:object/import` route before the cells are coerced: they used to
+ * be accepted and dropped, leaving only the rename. Driven through a real
+ * ObjectQL engine + protocol on sqlite `:memory:`, as
+ * `import-integration.test.ts` is.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { ObjectQL } from '@objectstack/objectql';
+import { SqlDriver } from '@objectstack/driver-sql';
+import { ObjectStackProtocolImplementation } from '@objectstack/metadata-protocol';
+import { SysMetadataAuditObject, SysMetadataCommitObject, SysMetadataHistoryObject, SysMetadataObject } from '@objectstack/metadata-core';
+import { RestServer } from './rest-server';
+import { installDefaultOrganization } from './default-organization.testkit.js';
+
+const SUPPLIER = {
+  name: 'supplier', label: 'Supplier', systemFields: false,
+  fields: {
+    id: { name: 'id', type: 'text' as const, primaryKey: true },
+    name: { name: 'name', type: 'text' as const, label: 'Name' },
+    country: { name: 'country', type: 'text' as const, label: 'Country' },
+    credit_code: { name: 'credit_code', type: 'text' as const, label: 'Credit code' },
+  },
+  validations: [{
+    type: 'format' as const, name: 'credit_code_format', field: 'credit_code',
+    regex: '^[0-9A-Z]{18}$', message: 'Credit code must be 18 digits or capital letters',
+  }],
+};
+
+const CONTACT = {
+  name: 'contact', label: 'Contact', systemFields: false,
+  fields: {
+    id: { name: 'id', type: 'text' as const, primaryKey: true },
+    supplier: { name: 'supplier', type: 'text' as const, label: 'Supplier' },
+    email: { name: 'email', type: 'email' as const, label: 'Email' },
+    name: { name: 'name', type: 'text' as const, label: 'Name' },
+  },
+};
+
+const liveEngines: ObjectQL[] = [];
+afterEach(async () => {
+  while (liveEngines.length) {
+    try { await liveEngines.pop()?.destroy(); } catch { /* noop */ }
+  }
+});
+
+function makeRes() {
+  const res: any = {
+    write: () => true, end: () => {},
+    header: () => res,
+    status: (code: number) => { res._status = code; return res; },
+    json: (body: any) => { res._json = body; return res; },
+  };
+  return res;
+}
+
+async function boot() {
+  const engine = new ObjectQL();
+  liveEngines.push(engine);
+  engine.registerDriver(new SqlDriver({
+    client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true,
+  }), true);
+  await engine.init();
+  engine.registry.registerObject(SUPPLIER as any);
+  engine.registry.registerObject(CONTACT as any);
+  await engine.syncSchemas();
+  await installDefaultOrganization(engine);
+  for (const o of [SysMetadataObject, SysMetadataHistoryObject, SysMetadataAuditObject, SysMetadataCommitObject]) {
+    if (!engine.registry.getObject(o.name)) engine.registry.registerObject(o as any);
+  }
+  const protocol = new ObjectStackProtocolImplementation(engine as any);
+  const noop = () => {};
+  const server = { get: noop, post: noop, put: noop, delete: noop, patch: noop, use: noop, listen: async () => {}, close: async () => {} };
+  const rest = new RestServer(server as any, protocol as any, { api: { requireAuth: false } } as any);
+  (rest as any).resolveExecCtx = async () => ({ userId: 'test-user' });
+  rest.registerRoutes();
+  const route = rest.getRoutes().find((r: any) => r.method === 'POST' && r.path === '/api/v1/data/:object/import');
+  expect(route).toBeDefined();
+  return { engine, route };
+}
+
+describe('import route — inline FieldMappingEntry rules (#25491)', () => {
+  let engine: any;
+  let route: any;
+  const call = async (object: string, body: any) => {
+    const res = makeRes();
+    await route.handler({ params: { object }, body } as any, res);
+    return res;
+  };
+
+  beforeEach(async () => {
+    ({ engine, route } = await boot());
+  });
+
+  it('uppercase: a lowercase credit code passes the ^[0-9A-Z]{18}$ rule and is stored upper-cased (the card\'s reproduction)', async () => {
+    const res = await call('supplier', {
+      format: 'csv',
+      csv: '公司全称,国家 / 地区,统一社会信用代码\n示例公司,中国,91000000ma0trial02\n',
+      mapping: [
+        { sourceField: '公司全称', targetField: 'name' },
+        { sourceField: '国家 / 地区', targetField: 'country' },
+        { sourceField: '统一社会信用代码', targetField: 'credit_code', transform: 'uppercase' },
+      ],
+      writeMode: 'upsert', matchFields: ['credit_code'],
+    });
+    expect(res._json).toMatchObject({ total: 1, ok: 1, errors: 0, created: 1 });
+    const stored = await engine.find('supplier', {});
+    expect(stored).toHaveLength(1);
+    expect(stored[0]).toMatchObject({ name: '示例公司', country: '中国', credit_code: '91000000MA0TRIAL02' });
+  });
+
+  it('lowercase: two spellings of one email merge into one contact under matchFields [supplier, email]', async () => {
+    const mapping = [
+      { sourceField: 'Supplier', targetField: 'supplier' },
+      { sourceField: 'Email', targetField: 'email', transform: 'lowercase' },
+      { sourceField: 'Name', targetField: 'name' },
+    ];
+    const first = await call('contact', {
+      format: 'csv', csv: 'Supplier,Email,Name\ns1,ZHOU@X.EXAMPLE.COM,Zhou\n',
+      mapping, writeMode: 'upsert', matchFields: ['supplier', 'email'],
+    });
+    expect(first._json).toMatchObject({ ok: 1, created: 1 });
+    const second = await call('contact', {
+      format: 'csv', csv: 'Supplier,Email,Name\ns1,zhou@x.example.com,Zhou Wei\n',
+      mapping, writeMode: 'upsert', matchFields: ['supplier', 'email'],
+    });
+    expect(second._json).toMatchObject({ ok: 1, created: 0, updated: 1 });
+    const stored = await engine.find('contact', {});
+    expect(stored).toHaveLength(1);
+    expect(stored[0]).toMatchObject({ supplier: 's1', email: 'zhou@x.example.com', name: 'Zhou Wei' });
+  });
+
+  it('trim: strips the cell even when the request turns trimWhitespace off', async () => {
+    const res = await call('supplier', {
+      format: 'json', trimWhitespace: false,
+      rows: [{ N: '  Acme  ', C: '  CN  ' }],
+      mapping: [
+        { sourceField: 'N', targetField: 'name', transform: 'trim' },
+        { sourceField: 'C', targetField: 'country' },
+      ],
+    });
+    expect(res._json).toMatchObject({ ok: 1, created: 1 });
+    const [stored] = await engine.find('supplier', {});
+    expect(stored).toMatchObject({ name: 'Acme', country: '  CN  ' });
+  });
+
+  it('defaultValue: fills a blank cell and a missing column, leaves a filled cell alone', async () => {
+    const res = await call('supplier', {
+      format: 'csv', csv: 'Name,Country\nA,\nB,JP\n',
+      mapping: [
+        { sourceField: 'Name', targetField: 'name' },
+        { sourceField: 'Country', targetField: 'country', defaultValue: 'CN' },
+        { sourceField: 'Code', targetField: 'credit_code', defaultValue: '000000000000000000' },
+      ],
+    });
+    expect(res._json).toMatchObject({ ok: 2, created: 2 });
+    const stored = await engine.find('supplier', { orderBy: [{ field: 'name', order: 'asc' }] });
+    expect(stored.map((r: any) => [r.name, r.country, r.credit_code])).toEqual([
+      ['A', 'CN', '000000000000000000'],
+      ['B', 'JP', '000000000000000000'],
+    ]);
+  });
+
+  it('required: a blank required cell refuses the request before any row, on the dry run and the commit alike', async () => {
+    const body = {
+      format: 'csv', csv: 'Name,Country\nA,CN\nB,\n',
+      mapping: [
+        { sourceField: 'Name', targetField: 'name' },
+        { sourceField: 'Country', targetField: 'country', required: true },
+      ],
+    };
+    const dry = await call('supplier', { ...body, dryRun: true });
+    const commit = await call('supplier', body);
+    for (const res of [dry, commit]) {
+      expect(res._status).toBe(400);
+      expect(res._json?.error?.code ?? res._json?.code).toBe('MISSING_REQUIRED_FIELD');
+      expect(JSON.stringify(res._json)).toContain('row 2');
+    }
+    expect(await engine.find('supplier', {})).toHaveLength(0);
+  });
+
+  it('required with a defaultValue is satisfied by the default', async () => {
+    const res = await call('supplier', {
+      format: 'csv', csv: 'Name,Country\nB,\n',
+      mapping: [
+        { sourceField: 'Name', targetField: 'name' },
+        { sourceField: 'Country', targetField: 'country', required: true, defaultValue: 'CN' },
+      ],
+    });
+    expect(res._json).toMatchObject({ ok: 1, created: 1 });
+  });
+
+  it('date_format is refused with 400 UNSUPPORTED_TRANSFORM naming it, and nothing is written', async () => {
+    const res = await call('supplier', {
+      format: 'csv', csv: 'Name\nA\n',
+      mapping: [{ sourceField: 'Name', targetField: 'name', transform: 'date_format' }],
+    });
+    expect(res._status).toBe(400);
+    expect(res._json?.error?.code ?? res._json?.code).toBe('UNSUPPORTED_TRANSFORM');
+    expect(JSON.stringify(res._json)).toContain('date_format');
+    expect(await engine.find('supplier', {})).toHaveLength(0);
+  });
+
+  it('control: a plain { sourceField, targetField } array mapping is the rename it always was', async () => {
+    const res = await call('supplier', {
+      format: 'csv', csv: 'Name,Country\n  Acme ,cn\n', trimWhitespace: false,
+      mapping: [
+        { sourceField: 'Name', targetField: 'name' },
+        { sourceField: 'Country', targetField: 'country', transform: 'none' },
+      ],
+    });
+    expect(res._json).toMatchObject({ ok: 1, created: 1 });
+    const [stored] = await engine.find('supplier', {});
+    expect(stored).toMatchObject({ name: '  Acme ', country: 'cn' });
+  });
+});
@@ -17,6 +17,7 @@ import {
     resolveNamedMapping, applyMappingToRows, refuseUnknownMappingTargets, type MappingArtifactLike,
 } from './import-mapping.js';
 import { asXlsxLoadInput, loadExcelJs } from './xlsx-module.js';
+import { isBlank } from '@objectstack/core';
 
 /**
  * Minimal RFC-4180-style CSV parser used by the bulk-import endpoint
@@ -194,6 +195,112 @@ export async function parseXlsxToRows(
     return out;
 }
 
+/**
+ * [#25491] The per-cell rules of one inline `FieldMappingEntry`
+ * (`ImportRequestSchema.mapping` in its array form), keyed by the entry's
+ * target: the column has already been renamed to it when the rules run.
+ */
+interface InlineEntryRule {
+    sourceField: string;
+    targetField: string;
+    transform: InlineTransform;
+    hasDefault: boolean;
+    defaultValue?: unknown;
+    required: boolean;
+}
+
+/**
+ * The transforms an inline mapping entry may declare that this path applies,
+ * each to a string cell (any other value passes through). `none` and `lookup`
+ * copy the cell: a `lookup` cell is resolved to a record id by the import's
+ * reference resolution downstream, as the named mapping's `lookup` is.
+ */
+const INLINE_TRANSFORMS = {
+    none: (s: string) => s,
+    lookup: (s: string) => s,
+    trim: (s: string) => s.trim(),
+    uppercase: (s: string) => s.toUpperCase(),
+    lowercase: (s: string) => s.toLowerCase(),
+} as const;
+type InlineTransform = keyof typeof INLINE_TRANSFORMS;
+
+type ImportRefusal = { ok: false; status: number; code: string; error: string };
+
+/**
+ * Read one inline entry's rules, refusing a transform this path does not
+ * apply instead of running the import without it. `date_format` is declared
+ * by the spec, but an entry carries no format for it to apply. Returns no
+ * rule for a plain rename (no transform, no default, not required), which
+ * leaves the row exactly as the rename built it.
+ */
+function readInlineEntryRule(
+    e: { sourceField: string; targetField: string; transform?: unknown; defaultValue?: unknown; required?: unknown },
+): { ok: true; rule?: InlineEntryRule } | ImportRefusal {
+    const transform = e.transform === undefined ? 'none' : e.transform;
+    if (typeof transform !== 'string' || !Object.prototype.hasOwnProperty.call(INLINE_TRANSFORMS, transform)) {
+        const named = typeof transform === 'string' ? `"${transform}"` : String(transform);
+        const why = transform === 'date_format'
+            ? 'a mapping entry carries no date format for it to apply; a cell mapped to a date or datetime field is already parsed as a date, so drop the transform'
+            : `the transforms a mapping entry may declare are ${Object.keys(INLINE_TRANSFORMS).join(', ')}`;
+        return {
+            ok: false, status: 400, code: 'UNSUPPORTED_TRANSFORM',
+            error: `Mapping entry "${e.sourceField}" to "${e.targetField}" declares transform ${named}, which the import path does not apply, `
+                + `so the import is refused rather than run with that transform skipped: ${why}.`,
+        };
+    }
+    const hasDefault = e.defaultValue !== undefined;
+    const required = e.required === true;
+    if (transform === 'none' && !hasDefault && !required) return { ok: true };
+    return {
+        ok: true,
+        rule: {
+            sourceField: e.sourceField, targetField: e.targetField,
+            transform: transform as InlineTransform, hasDefault, defaultValue: e.defaultValue, required,
+        },
+    };
+}
+
+/**
+ * Apply each inline entry's rules to every row, in place, before the cells
+ * are coerced: the transform to a string cell, then `defaultValue` to a cell
+ * that is blank (what cell coercion calls blank: absent, empty, whitespace or
+ * one of the request's `nullValues`), then `required` to what is left. A
+ * required cell still blank refuses the whole request before any row is
+ * written, on the dry run and the commit alike, naming the column and the
+ * rows (numbered as the row report numbers them).
+ */
+function applyInlineEntryRules(
+    rows: Array<Record<string, any>>,
+    rules: InlineEntryRule[],
+    nullValues: string[] | undefined,
+): ImportRefusal | undefined {
+    const misses = new Map<InlineEntryRule, number[]>();
+    rows.forEach((row, i) => {
+        for (const rule of rules) {
+            let value = row[rule.targetField];
+            if (typeof value === 'string') value = INLINE_TRANSFORMS[rule.transform](value);
+            if (rule.hasDefault && isBlank(value, nullValues)) value = rule.defaultValue;
+            if (value !== undefined) row[rule.targetField] = value;
+            if (rule.required && isBlank(value, nullValues)) {
+                const at = misses.get(rule) ?? [];
+                at.push(i + 1);
+                misses.set(rule, at);
+            }
+        }
+    });
+    if (misses.size === 0) return undefined;
+    const listed = [...misses].map(([rule, at]) => {
+        const shown = at.length > 10 ? `${at.slice(0, 10).join(', ')} and ${at.length - 10} more` : at.join(', ');
+        return `"${rule.sourceField}" to "${rule.targetField}" (row${at.length === 1 ? '' : 's'} ${shown})`;
+    });
+    return {
+        ok: false, status: 400, code: 'MISSING_REQUIRED_FIELD',
+        error: `The mapping marks ${listed.length === 1 ? 'a column' : 'columns'} required that some rows leave blank: ${listed.join('; ')}. `
+            + 'The import is refused before any row, on the dry run and the commit alike. '
+            + 'Fill those cells, give the entry a defaultValue, or drop required from it.',
+    };
+}
+
 /** Everything the import runner needs, parsed & validated from a request body. */
 export interface PreparedImport {
     rows: Array<Record<string, any>>;
@@ -453,12 +560,18 @@ export async function prepareImportRequest(
     }
 
     // Normalize `mapping` to a `{ sourceColumn: targetField }` record. Accepts
-    // either that compact form or a FieldMappingEntry[].
+    // either that compact form or a FieldMappingEntry[]. An entry's own
+    // per-cell rules (`transform` / `defaultValue` / `required`) are kept
+    // beside the rename and applied once the rows are built (#25491).
     const mapping: Record<string, string> = {};
+    const entryRules: InlineEntryRule[] = [];
     if (Array.isArray(body?.mapping)) {
         for (const e of body.mapping) {
             if (e && typeof e.sourceField === 'string' && typeof e.targetField === 'string') {
                 mapping[e.sourceField] = e.targetField;
+                const read = readInlineEntryRule(e);
+                if (!read.ok) return read;
+                if (read.rule) entryRules.push(read.rule);
             }
         }
     } else if (body?.mapping && typeof body.mapping === 'object') {
@@ -499,6 +612,11 @@ export async function prepareImportRequest(
         return { ok: false, status: 413, code: 'PAYLOAD_TOO_LARGE', error: `Import limit is ${maxRows} rows per request (got ${rows.length}).` };
     }
 
+    if (entryRules.length > 0) {
+        const refused = applyInlineEntryRules(rows, entryRules, nullValues);
+        if (refused) return refused;
+    }
+
     // Resolve the object's field metadata so cells coerce to storage values
     // (booleans, numbers, dates→ISO, select label→code) and lookup names resolve
     // to record ids. Best-effort: a failed lookup leaves `metaMap` empty and