@@ -0,0 +1,11 @@
+---
+'@objectstack/service-storage': patch
+---
+
+A file field's declared `accept` / `maxSize` refusal now answers `400 ERR_FILE_CONSTRAINT` with a sentence naming the field and the constraint, instead of `500 INTERNAL_ERROR` with the sentence withheld.
+
+Clause-②: no
+
+- **`FileConstraintError` declares `status = 400`**, as `FileFieldBulkWriteError` in the same module already did. The data API's declared-status passthrough now answers the refusal on create and on update, e.g. `400 {"error":"File exceeds the maximum size declared for 'doc' (5005 bytes > 10 bytes)","code":"ERR_FILE_CONSTRAINT","object":"…"}`. Before, the error declared a registered `code` but no status, so it fell through to the sanitised `500 INTERNAL_ERROR`, and the field and the reason reached only the server log.
+- **It carries `field` and `constraint` (`'accept' | 'maxSize'`) as members**, for in-process callers. The constructor is now `new FileConstraintError(field, constraint, message)`. The new `FileConstraint` type is exported beside it. On the HTTP wire the message names both, and its wording is unchanged.
+- The accept set is unchanged: the same files are refused, and a refused write still persists no row and claims no file. `ERR_FILE_CONSTRAINT` was already in the error-code ledger.
@@ -362,7 +362,7 @@ Self-referential hierarchy (e.g., categories, org chart).
 
 ## Media Types
 
-Media fields store a reference to an uploaded file. They take the universal field properties (`multiple` is honored for `file` and `image`); there is no per-field file-attachment config object in the field schema — file constraints and storage are configured at the storage-provider layer, not on the field.
+Media fields store a reference to an uploaded file. They take the universal field properties (`multiple` is honored for `file` and `image`). Two more field properties apply to the media family (`file`, `image`, `avatar`, `video` and `audio`) and constrain the referenced file: `accept`, the permitted upload types as MIME types or extensions (e.g. `["image/*", ".pdf"]`), offered to the file picker and enforced on write; and `maxSize`, the maximum permitted file size in bytes, enforced on write against the stored file size, not just checked in the browser. A create or update whose referenced file violates either is refused with `400 ERR_FILE_CONSTRAINT`, and the error message names the field and the constraint. Storage itself is configured at the storage-provider layer, not on the field.
 
 ### `image`
 Image file with optional validation.
 
@@ -0,0 +1,184 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// A file field's declared `accept` / `maxSize` refusal, end to end through the
+// real stack: storage service's copy-on-claim before-hook
+// (`assertFileConstraints`, `FileConstraintError`) → ObjectQL triggerHooks →
+// REST `mapDataError` → HTTP body.
+//
+// ── What this pins ──────────────────────────────────────────────────────────
+//
+// The refusal is a verdict about the CALLER's own file — wrong type, too big —
+// so it answers `400 ERR_FILE_CONSTRAINT` with a sentence naming the field and
+// the constraint. Before `FileConstraintError` declared its `status`, the
+// declared-status passthrough never fired and the same refusal left through the
+// unclassified-fault terminal as `500 INTERNAL_ERROR` with the sentence
+// withheld: enforcement held, the wire contract did not.
+//
+// ── Why each assertion is load-bearing ──────────────────────────────────────
+//
+//   `code` AND `status` (ADR-0112). A bare status cannot tell this verdict
+//   apart from any other 400 the data door gives.
+//
+//   The READ-BACK, not the response. A write that answers 400 and lands anyway
+//   satisfies a response-only assertion perfectly, so every refusal re-reads
+//   the object's rows and the `sys_file` ownership columns under a system
+//   context.
+//
+//   The SMALL-PDF CONTROL, on the same field. Without it the refusal cases pass
+//   just as well when every file write is refused for an unrelated reason.
+//
+// The sentence is asserted by its NAMED SUBJECTS only — the field and the
+// constraint — never its full wording: the field and the constraint reach the
+// wire through the message alone (the declared-status passthrough forwards
+// `status`, the registered `code` and the bounded message, and no other member
+// of the thrown error).
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtempSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { bootStack, type VerifyStack } from '@objectstack/verify';
+import { defineStack } from '@objectstack/spec';
+import { ObjectSchema, Field, RAW_FILE_VALUES_CONTEXT_KEY } from '@objectstack/spec/data';
+import { StorageServicePlugin } from '@objectstack/service-storage';
+
+const SYS = { isSystem: true } as const;
+const OBJECT = 'ffc_doc';
+
+const FfcDoc = ObjectSchema.create({
+  name: OBJECT,
+  label: 'Constrained Document',
+  fields: {
+    name: Field.text({ label: 'Name' }),
+    doc: Field.file({ label: 'Document', accept: ['.pdf'], maxSize: 10 }),
+  },
+});
+
+const ffcStack = defineStack({
+  manifest: {
+    id: 'com.dogfood.file-field-constraint-refusal',
+    namespace: 'ffc',
+    version: '0.0.0',
+    type: 'app',
+    name: 'File Field Constraint Refusal Fixture',
+    description: 'A file field declaring accept and maxSize, written through the data API.',
+  },
+  objects: [FfcDoc],
+});
+
+/** The three `sys_file` rows the cases reference — one per verdict. */
+const FILES = {
+  wrongType: { id: 'ffc_file_txt', name: 'notes.txt', mime_type: 'text/plain', size: 6 },
+  oversize: { id: 'ffc_file_big', name: 'big.pdf', mime_type: 'application/pdf', size: 5005 },
+  smallPdf: { id: 'ffc_file_ok', name: 'small.pdf', mime_type: 'application/pdf', size: 6 },
+  smallPdf2: { id: 'ffc_file_ok2', name: 'small2.pdf', mime_type: 'application/pdf', size: 6 },
+} as const;
+
+describe('a file field\'s accept / maxSize refusal answers 400 ERR_FILE_CONSTRAINT', () => {
+  let stack: VerifyStack;
+  let token: string;
+  let ql: any;
+
+  beforeAll(async () => {
+    const rootDir = mkdtempSync(join(tmpdir(), 'ffc-pin-'));
+    stack = await bootStack(ffcStack, {
+      extraPlugins: [
+        new StorageServicePlugin({ adapter: 'local', local: { rootDir }, bindToSettings: false }),
+      ],
+    });
+    token = await stack.signIn();
+    ql = await stack.kernel.getServiceAsync('objectql');
+
+    for (const f of Object.values(FILES)) {
+      await ql.insert(
+        'sys_file',
+        { ...f, key: `user/${f.id}`, status: 'committed', scope: 'user' },
+        { context: SYS },
+      );
+    }
+  }, 60_000);
+
+  afterAll(async () => {
+    await stack?.stop();
+  });
+
+  const write = async (method: 'POST' | 'PATCH', path: string, data: Record<string, unknown>) => {
+    const res = await stack.apiAs(token, method, path, data);
+    return { status: res.status, body: (await res.json()) as any };
+  };
+
+  /** The rows named `name`, read above every access layer. */
+  const rowsNamed = async (name: string) =>
+    ql.find(OBJECT, { where: { name }, context: { ...SYS, [RAW_FILE_VALUES_CONTEXT_KEY]: true } });
+
+  /** The `sys_file` ownership columns, read above every access layer. */
+  const owner = async (id: string) => {
+    const row = await ql.findOne('sys_file', { where: { id }, context: SYS });
+    return { ref_object: row?.ref_object ?? null, ref_id: row?.ref_id ?? null, ref_field: row?.ref_field ?? null };
+  };
+  const UNOWNED = { ref_object: null, ref_id: null, ref_field: null };
+
+  let controlId: string;
+
+  it('a file outside the accept list answers 400 ERR_FILE_CONSTRAINT naming the field and the accept list, and writes no row', async () => {
+    const r = await write('POST', `/data/${OBJECT}`, { name: 'wrong type', doc: FILES.wrongType.id });
+
+    expect(r.status, JSON.stringify(r.body)).toBe(400);
+    expect(r.body.code).toBe('ERR_FILE_CONSTRAINT');
+    expect(r.body.error).toContain("'doc'");
+    expect(r.body.error).toContain('accept list');
+    expect(r.body.object).toBe(OBJECT);
+
+    expect(await rowsNamed('wrong type')).toHaveLength(0);
+    expect(await owner(FILES.wrongType.id)).toEqual(UNOWNED);
+  });
+
+  it('a file over maxSize answers 400 ERR_FILE_CONSTRAINT naming the field and the maximum size, and writes no row', async () => {
+    const r = await write('POST', `/data/${OBJECT}`, { name: 'oversize', doc: FILES.oversize.id });
+
+    expect(r.status, JSON.stringify(r.body)).toBe(400);
+    expect(r.body.code).toBe('ERR_FILE_CONSTRAINT');
+    expect(r.body.error).toContain("'doc'");
+    expect(r.body.error).toContain('maximum size');
+    expect(r.body.object).toBe(OBJECT);
+
+    expect(await rowsNamed('oversize')).toHaveLength(0);
+    expect(await owner(FILES.oversize.id)).toEqual(UNOWNED);
+  });
+
+  it('control: a 6-byte PDF satisfies both declarations, answers 201, and is claimed by the row', async () => {
+    const r = await write('POST', `/data/${OBJECT}`, { name: 'control', doc: FILES.smallPdf.id });
+
+    expect(r.status, JSON.stringify(r.body)).toBe(201);
+    controlId = r.body.record?.id ?? r.body.id;
+    expect(controlId).toBeTruthy();
+
+    const stored = await rowsNamed('control');
+    expect(stored).toHaveLength(1);
+    expect(stored[0].doc).toBe(FILES.smallPdf.id);
+    expect(await owner(FILES.smallPdf.id)).toEqual({ ref_object: OBJECT, ref_id: controlId, ref_field: 'doc' });
+  });
+
+  it('an UPDATE onto an oversize file is refused the same way and leaves the record and both files as they were', async () => {
+    const r = await write('PATCH', `/data/${OBJECT}/${controlId}`, { doc: FILES.oversize.id });
+
+    expect(r.status, JSON.stringify(r.body)).toBe(400);
+    expect(r.body.code).toBe('ERR_FILE_CONSTRAINT');
+    expect(r.body.error).toContain("'doc'");
+    expect(r.body.error).toContain('maximum size');
+
+    const stored = await rowsNamed('control');
+    expect(stored).toHaveLength(1);
+    expect(stored[0].doc).toBe(FILES.smallPdf.id);
+    expect(await owner(FILES.smallPdf.id)).toEqual({ ref_object: OBJECT, ref_id: controlId, ref_field: 'doc' });
+    expect(await owner(FILES.oversize.id)).toEqual(UNOWNED);
+  });
+
+  it('control: an UPDATE onto a permitted file still lands', async () => {
+    const r = await write('PATCH', `/data/${OBJECT}/${controlId}`, { doc: FILES.smallPdf2.id });
+
+    expect(r.status, JSON.stringify(r.body)).toBe(200);
+    const stored = await rowsNamed('control');
+    expect(stored[0].doc).toBe(FILES.smallPdf2.id);
+  });
+});
@@ -924,30 +924,75 @@ describe('File Reference Ownership (ADR-0104 D3 wave 2)', () => {
       },
     });
 
-    it('rejects a file larger than the declared maxSize', async () => {
+    /** The refusal a caller is owed: the ADR-0112 `code` plus the 4xx
+     * `status` the REST passthrough answers with, and the two named subjects
+     * as members. Without `status` the same throw leaves the data door as a
+     * sanitised `500 INTERNAL_ERROR` with the sentence withheld. */
+    const refusal = (constraint: 'accept' | 'maxSize') => ({
+      code: 'ERR_FILE_CONSTRAINT',
+      status: 400,
+      field: 'image',
+      constraint,
+    });
+
+    it('rejects a file larger than the declared maxSize (ERR_FILE_CONSTRAINT / 400, naming field and constraint)', async () => {
       const engine = fakeEngine({
         files: [file({ size: 5000 })],
         registry: constrained(),
       });
       install(engine);
 
-      await expect(driveInsert(engine, 'product', { image: 'file_a' }, 'p1')).rejects.toThrow(
-        FileConstraintError,
-      );
-      // The write failed, so nothing was claimed.
+      const err = await driveInsert(engine, 'product', { image: 'file_a' }, 'p1')
+        .then(() => null)
+        .catch((e) => e);
+
+      expect(err).toBeInstanceOf(FileConstraintError);
+      expect(err).toMatchObject(refusal('maxSize'));
+      expect(err.message).toContain("'image'");
+      // The write failed before the driver: no row, and nothing was claimed.
+      expect(engine.tables.product ?? []).toHaveLength(0);
       expect(engine.tables.sys_file[0].ref_id).toBeUndefined();
     });
 
-    it('rejects a file whose MIME type is outside the declared accept list', async () => {
+    it('rejects a file whose MIME type is outside the declared accept list (ERR_FILE_CONSTRAINT / 400, naming field and constraint)', async () => {
       const engine = fakeEngine({
         files: [file({ mime_type: 'application/pdf', name: 'a.pdf', size: 10 })],
         registry: constrained(),
       });
       install(engine);
 
-      await expect(driveInsert(engine, 'product', { image: 'file_a' }, 'p1')).rejects.toThrow(
-        /not permitted by the accept list/,
-      );
+      const err = await driveInsert(engine, 'product', { image: 'file_a' }, 'p1')
+        .then(() => null)
+        .catch((e) => e);
+
+      expect(err).toBeInstanceOf(FileConstraintError);
+      expect(err).toMatchObject(refusal('accept'));
+      expect(err.message).toMatch(/not permitted by the accept list/);
+      expect(err.message).toContain("'image'");
+      expect(engine.tables.product ?? []).toHaveLength(0);
+      expect(engine.tables.sys_file[0].ref_id).toBeUndefined();
+    });
+
+    it('refuses an UPDATE onto an oversize file with the same envelope, leaving the record and both files as they were', async () => {
+      const engine = fakeEngine({
+        files: [
+          file({ id: 'file_old', size: 10, ref_object: 'product', ref_id: 'p1', ref_field: 'image' }),
+          file({ id: 'file_big', size: 5000 }),
+        ],
+        records: { product: [{ id: 'p1', image: 'file_old' }] },
+        registry: constrained(),
+      });
+      install(engine);
+
+      const err = await driveUpdate(engine, 'product', 'p1', { image: 'file_big' })
+        .then(() => null)
+        .catch((e) => e);
+
+      expect(err).toBeInstanceOf(FileConstraintError);
+      expect(err).toMatchObject(refusal('maxSize'));
+      expect(engine.tables.product[0].image).toBe('file_old');
+      expect(engine.tables.sys_file.find((f) => f.id === 'file_old')).toMatchObject({ ref_id: 'p1' });
+      expect(engine.tables.sys_file.find((f) => f.id === 'file_big')!.ref_id).toBeUndefined();
     });
 
     it('accepts a file that satisfies both declarations', async () => {
 
@@ -221,15 +221,36 @@ export class FileReferenceCopyError extends Error {
   }
 }
 
+/** The media-field declaration a {@link FileConstraintError} names as violated. */
+export type FileConstraint = 'accept' | 'maxSize';
+
 /**
  * Raised when a referenced file violates its field's declared `accept` /
  * `maxSize`. Fails the write: a stored value that breaks its own field's
  * declaration is the "declared but not enforced" state ADR-0104 removes.
+ *
+ * ADR-0112 envelope, the same shape as {@link FileFieldBulkWriteError} below:
+ * a registered `code` plus a 4xx `status`, so the REST layer's declared-status
+ * passthrough answers `400 ERR_FILE_CONSTRAINT` with this message instead of
+ * the bare error falling through to the sanitised `500 INTERNAL_ERROR` with
+ * the sentence withheld. `400` because the verdict is about the file the
+ * CALLER chose — wrong type, too large — and the remedy is the caller's: pick
+ * a file the field's declaration permits.
+ *
+ * `field` and `constraint` carry the two named subjects as members for
+ * in-process callers. On the HTTP wire the passthrough forwards `status`, the
+ * registered `code` and the bounded message, so there the message is what
+ * names both — keep it naming the field and the constraint.
  */
 export class FileConstraintError extends Error {
   readonly code = 'ERR_FILE_CONSTRAINT';
-  constructor(message: string) {
+  readonly status = 400;
+  readonly field: string;
+  readonly constraint: FileConstraint;
+  constructor(field: string, constraint: FileConstraint, message: string) {
     super(message);
+    this.field = field;
+    this.constraint = constraint;
   }
 }
 
@@ -328,6 +349,8 @@ function assertFileConstraints(
   if (typeof maxSize === 'number' && maxSize > 0 && typeof file.size === 'number') {
     if (file.size > maxSize) {
       throw new FileConstraintError(
+        field,
+        'maxSize',
         `File exceeds the maximum size declared for '${field}' ` +
           `(${file.size} bytes > ${maxSize} bytes)`,
       );
@@ -351,6 +374,8 @@ function assertFileConstraints(
 
     if (!testable.some((e) => matchesAcceptEntry(e, mime, name))) {
       throw new FileConstraintError(
+        field,
+        'accept',
         `File type '${mime || name}' is not permitted by the accept list declared for ` +
           `'${field}' (${accept.join(', ')})`,
       );
 
@@ -65,7 +65,7 @@ export {
   FileReferenceCopyError,
   FileConstraintError,
 } from './file-reference-lifecycle.js';
-export type { FileReferenceEngine, FileReferenceLogger } from './file-reference-lifecycle.js';
+export type { FileConstraint, FileReferenceEngine, FileReferenceLogger } from './file-reference-lifecycle.js';
 export {
   verifyFileReferences,
   formatFileReferenceReport,