@objectstack/rest 14.8.0 → 15.1.0

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { IHttpServer, RouteHandler, Plugin } from '@objectstack/core';
 import * as System from '@objectstack/spec/system';
 import * as Shared from '@objectstack/spec/shared';
 import { z } from 'zod';
-import { ObjectStackProtocol, RestServerConfig } from '@objectstack/spec/api';
+import { DataProtocol, MetadataProtocol, RestServerConfig } from '@objectstack/spec/api';
 
 type RouteHandlerMetadata = System.RouteHandlerMetadata;
 type HttpMethod = z.infer<typeof Shared.HttpMethod>;
@@ -155,6 +155,14 @@ declare class RouteGroupBuilder {
     private resolvePath;
 }
 
+/**
+ * The protocol slice the REST layer actually consumes (ADR-0076 D9 / #2462
+ * A1.5): wire-normalized data CRUD plus the metadata control plane — not the
+ * full `ObjectStackProtocol` union. Server-only extensions (drafts, history,
+ * diagnostics, clone, …) are feature-detected via runtime casts and so don't
+ * widen this contract.
+ */
+type RestProtocol = DataProtocol & MetadataProtocol;
 /**
  * Structural subset of `KernelManager` that RestServer needs in order to
  * resolve a per-project protocol at request time. Typed locally to avoid
@@ -266,7 +274,7 @@ declare class RestServer {
      * the durable source of truth a restarted/other node reads.
      */
     private readonly cancelledImportJobs;
-    constructor(server: IHttpServer, protocol: ObjectStackProtocol, config?: RestServerConfig, kernelManager?: RestKernelManager, envRegistry?: RestEnvRegistry, defaultEnvironmentIdProvider?: () => string | undefined, authServiceProvider?: (environmentId?: string) => Promise<any | undefined>, objectQLProvider?: (environmentId?: string) => Promise<any | undefined>, emailServiceProvider?: (environmentId?: string) => Promise<any | undefined>, sharingServiceProvider?: (environmentId?: string) => Promise<any | undefined>, reportsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, approvalsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, sharingRulesServiceProvider?: (environmentId?: string) => Promise<any | undefined>, i18nServiceProvider?: (environmentId?: string) => Promise<any | undefined>, analyticsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, settingsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, serviceExistsProvider?: (name: string) => boolean, securityServiceProvider?: (environmentId?: string) => Promise<any | undefined>);
+    constructor(server: IHttpServer, protocol: RestProtocol, config?: RestServerConfig, kernelManager?: RestKernelManager, envRegistry?: RestEnvRegistry, defaultEnvironmentIdProvider?: () => string | undefined, authServiceProvider?: (environmentId?: string) => Promise<any | undefined>, objectQLProvider?: (environmentId?: string) => Promise<any | undefined>, emailServiceProvider?: (environmentId?: string) => Promise<any | undefined>, sharingServiceProvider?: (environmentId?: string) => Promise<any | undefined>, reportsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, approvalsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, sharingRulesServiceProvider?: (environmentId?: string) => Promise<any | undefined>, i18nServiceProvider?: (environmentId?: string) => Promise<any | undefined>, analyticsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, settingsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, serviceExistsProvider?: (name: string) => boolean, securityServiceProvider?: (environmentId?: string) => Promise<any | undefined>);
     /**
      * Resolve the protocol for a given request. When `environmentId` is present
      * and a KernelManager is wired, fetch the per-project kernel's
@@ -755,7 +763,7 @@ interface RestApiPluginConfig {
  *
  * Responsibilities:
  * 1. Consumes 'http.server' (or configured service)
- * 2. Consumes 'protocol' (ObjectStackProtocol)
+ * 2. Consumes 'protocol' (the `RestProtocol` slice — DataProtocol + MetadataProtocol, ADR-0076 D9)
  * 3. Instantiates RestServer to auto-generate routes
  */
 declare function createRestApiPlugin(config?: RestApiPluginConfig): Plugin;
@@ -787,6 +795,8 @@ interface ExportFieldMeta {
     reference?: string;
     /** Field on the referenced record to show as its label. */
     displayField?: string;
+    /** Field holds multiple values (an array), e.g. a `multiple: true` lookup. */
+    multiple?: boolean;
     /** Field is required — a value (or default) must exist on insert. */
     required?: boolean;
     /** Engine-owned column the client never supplies (never required of import). */
@@ -1027,6 +1037,12 @@ declare function runImport(opts: RunImportOptions): Promise<ImportRunSummary>;
  *   - select / radio                                → an option *value*
  *   - multiselect / checkboxes / tags               → an array of option values
  *   - lookup / master_detail / user / reference     → a record id (resolved async)
+ *   - file / image                                  → a file id / url (as-is)
+ *
+ * Any of the last four whose field is flagged `multiple: true` (per the spec,
+ * `multiple` applies to select / lookup / file / image; `radio`/`user` share
+ * their branch) instead store an **array** — the cell is split on the export
+ * separator and each token coerced individually. See `isMultiValueField`.
  *
  * Contract: when a field carries no usable metadata the value passes through
  * untouched, so an import stays byte-identical to the pre-coercion behaviour.
@@ -1085,4 +1101,4 @@ declare function coerceRow(rawRow: Record<string, unknown>, metaMap: Map<string,
     errors: FieldCoerceError[];
 }>;
 
-export { type CoerceContext, type ExportFieldMeta, type ImportAction, type ImportProgress, type ImportProtocolLike, type ImportRowResult, type ImportRunSummary, type ImportUndoLog, type PrepareImportResult, type PreparedImport, type RefResolver, type RestApiPluginConfig, RestServer, type RouteEntry, RouteGroupBuilder, RouteManager, type RunImportOptions, buildFieldMetaMap, coerceRow, createRestApiPlugin, isMetaEnvelope, parseCsvToRows, parseXlsxToRows, prepareImportRequest, runImport };
+export { type CoerceContext, type ExportFieldMeta, type ImportAction, type ImportProgress, type ImportProtocolLike, type ImportRowResult, type ImportRunSummary, type ImportUndoLog, type PrepareImportResult, type PreparedImport, type RefResolver, type RestApiPluginConfig, type RestProtocol, RestServer, type RouteEntry, RouteGroupBuilder, RouteManager, type RunImportOptions, buildFieldMetaMap, coerceRow, createRestApiPlugin, isMetaEnvelope, parseCsvToRows, parseXlsxToRows, prepareImportRequest, runImport };

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { IHttpServer, RouteHandler, Plugin } from '@objectstack/core';
 import * as System from '@objectstack/spec/system';
 import * as Shared from '@objectstack/spec/shared';
 import { z } from 'zod';
-import { ObjectStackProtocol, RestServerConfig } from '@objectstack/spec/api';
+import { DataProtocol, MetadataProtocol, RestServerConfig } from '@objectstack/spec/api';
 
 type RouteHandlerMetadata = System.RouteHandlerMetadata;
 type HttpMethod = z.infer<typeof Shared.HttpMethod>;
@@ -155,6 +155,14 @@ declare class RouteGroupBuilder {
     private resolvePath;
 }
 
+/**
+ * The protocol slice the REST layer actually consumes (ADR-0076 D9 / #2462
+ * A1.5): wire-normalized data CRUD plus the metadata control plane — not the
+ * full `ObjectStackProtocol` union. Server-only extensions (drafts, history,
+ * diagnostics, clone, …) are feature-detected via runtime casts and so don't
+ * widen this contract.
+ */
+type RestProtocol = DataProtocol & MetadataProtocol;
 /**
  * Structural subset of `KernelManager` that RestServer needs in order to
  * resolve a per-project protocol at request time. Typed locally to avoid
@@ -266,7 +274,7 @@ declare class RestServer {
      * the durable source of truth a restarted/other node reads.
      */
     private readonly cancelledImportJobs;
-    constructor(server: IHttpServer, protocol: ObjectStackProtocol, config?: RestServerConfig, kernelManager?: RestKernelManager, envRegistry?: RestEnvRegistry, defaultEnvironmentIdProvider?: () => string | undefined, authServiceProvider?: (environmentId?: string) => Promise<any | undefined>, objectQLProvider?: (environmentId?: string) => Promise<any | undefined>, emailServiceProvider?: (environmentId?: string) => Promise<any | undefined>, sharingServiceProvider?: (environmentId?: string) => Promise<any | undefined>, reportsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, approvalsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, sharingRulesServiceProvider?: (environmentId?: string) => Promise<any | undefined>, i18nServiceProvider?: (environmentId?: string) => Promise<any | undefined>, analyticsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, settingsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, serviceExistsProvider?: (name: string) => boolean, securityServiceProvider?: (environmentId?: string) => Promise<any | undefined>);
+    constructor(server: IHttpServer, protocol: RestProtocol, config?: RestServerConfig, kernelManager?: RestKernelManager, envRegistry?: RestEnvRegistry, defaultEnvironmentIdProvider?: () => string | undefined, authServiceProvider?: (environmentId?: string) => Promise<any | undefined>, objectQLProvider?: (environmentId?: string) => Promise<any | undefined>, emailServiceProvider?: (environmentId?: string) => Promise<any | undefined>, sharingServiceProvider?: (environmentId?: string) => Promise<any | undefined>, reportsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, approvalsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, sharingRulesServiceProvider?: (environmentId?: string) => Promise<any | undefined>, i18nServiceProvider?: (environmentId?: string) => Promise<any | undefined>, analyticsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, settingsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, serviceExistsProvider?: (name: string) => boolean, securityServiceProvider?: (environmentId?: string) => Promise<any | undefined>);
     /**
      * Resolve the protocol for a given request. When `environmentId` is present
      * and a KernelManager is wired, fetch the per-project kernel's
@@ -755,7 +763,7 @@ interface RestApiPluginConfig {
  *
  * Responsibilities:
  * 1. Consumes 'http.server' (or configured service)
- * 2. Consumes 'protocol' (ObjectStackProtocol)
+ * 2. Consumes 'protocol' (the `RestProtocol` slice — DataProtocol + MetadataProtocol, ADR-0076 D9)
  * 3. Instantiates RestServer to auto-generate routes
  */
 declare function createRestApiPlugin(config?: RestApiPluginConfig): Plugin;
@@ -787,6 +795,8 @@ interface ExportFieldMeta {
     reference?: string;
     /** Field on the referenced record to show as its label. */
     displayField?: string;
+    /** Field holds multiple values (an array), e.g. a `multiple: true` lookup. */
+    multiple?: boolean;
     /** Field is required — a value (or default) must exist on insert. */
     required?: boolean;
     /** Engine-owned column the client never supplies (never required of import). */
@@ -1027,6 +1037,12 @@ declare function runImport(opts: RunImportOptions): Promise<ImportRunSummary>;
  *   - select / radio                                → an option *value*
  *   - multiselect / checkboxes / tags               → an array of option values
  *   - lookup / master_detail / user / reference     → a record id (resolved async)
+ *   - file / image                                  → a file id / url (as-is)
+ *
+ * Any of the last four whose field is flagged `multiple: true` (per the spec,
+ * `multiple` applies to select / lookup / file / image; `radio`/`user` share
+ * their branch) instead store an **array** — the cell is split on the export
+ * separator and each token coerced individually. See `isMultiValueField`.
  *
  * Contract: when a field carries no usable metadata the value passes through
  * untouched, so an import stays byte-identical to the pre-coercion behaviour.
@@ -1085,4 +1101,4 @@ declare function coerceRow(rawRow: Record<string, unknown>, metaMap: Map<string,
     errors: FieldCoerceError[];
 }>;
 
-export { type CoerceContext, type ExportFieldMeta, type ImportAction, type ImportProgress, type ImportProtocolLike, type ImportRowResult, type ImportRunSummary, type ImportUndoLog, type PrepareImportResult, type PreparedImport, type RefResolver, type RestApiPluginConfig, RestServer, type RouteEntry, RouteGroupBuilder, RouteManager, type RunImportOptions, buildFieldMetaMap, coerceRow, createRestApiPlugin, isMetaEnvelope, parseCsvToRows, parseXlsxToRows, prepareImportRequest, runImport };
+export { type CoerceContext, type ExportFieldMeta, type ImportAction, type ImportProgress, type ImportProtocolLike, type ImportRowResult, type ImportRunSummary, type ImportUndoLog, type PrepareImportResult, type PreparedImport, type RefResolver, type RestApiPluginConfig, type RestProtocol, RestServer, type RouteEntry, RouteGroupBuilder, RouteManager, type RunImportOptions, buildFieldMetaMap, coerceRow, createRestApiPlugin, isMetaEnvelope, parseCsvToRows, parseXlsxToRows, prepareImportRequest, runImport };

package/dist/index.js

@@ -1,5 +1,12 @@
 // src/rest-server.ts
-import { resolveAuthzContext, resolveLocalizationContext, isAuthGateAllowlisted } from "@objectstack/core";
+import {
+  resolveAuthzContext,
+  resolveLocalizationContext,
+  isAuthGateAllowlisted,
+  shouldDenyAnonymous,
+  ANONYMOUS_DENY_BODY,
+  ANONYMOUS_DENY_STATUS
+} from "@objectstack/core";
 import { isMcpServerEnabled } from "@objectstack/types";
 
 // src/route-manager.ts
@@ -212,6 +219,9 @@ var RouteGroupBuilder = class {
   }
 };
 
+// src/rest-server.ts
+import { PUBLIC_FORM_SERVER_MANAGED_FIELDS } from "@objectstack/spec/security";
+
 // src/export-format.ts
 function exportContentDisposition(objectName, label, ext, now = /* @__PURE__ */ new Date()) {
   const pad = (n) => String(n).padStart(2, "0");
@@ -261,6 +271,7 @@ function buildFieldMetaMap(schema) {
       options: Array.isArray(f.options) ? f.options : void 0,
       reference: typeof f.reference === "string" ? f.reference : void 0,
       displayField: typeof f.displayField === "string" ? f.displayField : void 0,
+      multiple: f.multiple === true,
       required: f.required === true,
       system: f.system === true,
       readonly: f.readonly === true,
@@ -382,6 +393,14 @@ var OPTION_TYPES2 = /* @__PURE__ */ new Set(["select", "radio"]);
 var MULTI_OPTION_TYPES2 = /* @__PURE__ */ new Set(["multiselect", "checkboxes", "tags"]);
 var NUMBER_TYPES = /* @__PURE__ */ new Set(["number", "currency", "percent", "rating", "slider"]);
 var BOOL_TYPES = /* @__PURE__ */ new Set(["boolean", "toggle"]);
+var FILE_TYPES = /* @__PURE__ */ new Set(["file", "image"]);
+var MULTI_CAPABLE_TYPES = /* @__PURE__ */ new Set(["select", "radio", "lookup", "user", "file", "image"]);
+function isMultiValueField(meta) {
+  const t = meta?.type;
+  if (!t) return false;
+  if (MULTI_OPTION_TYPES2.has(t)) return true;
+  return MULTI_CAPABLE_TYPES.has(t) && meta?.multiple === true;
+}
 function normalizeRefMatch(result) {
   if (result == null) return {};
   if (typeof result === "string") return result ? { id: result } : {};
@@ -499,7 +518,23 @@ async function coerceFieldValue(raw, meta, ctx) {
     if (d === void 0) return { error: { field, code: "invalid_date", message: `${field}: "${String(raw)}" is not a valid ${t}` } };
     return { value: d };
   }
-  if (OPTION_TYPES2.has(t)) {
+  if (OPTION_TYPES2.has(t) || MULTI_OPTION_TYPES2.has(t)) {
+    if (isMultiValueField(meta)) {
+      const parts = splitMulti(raw);
+      const out = [];
+      for (const part of parts) {
+        const v2 = matchOption(part, meta?.options);
+        if (v2 === void 0) {
+          if (ctx.createMissingOptions) {
+            out.push(part);
+            continue;
+          }
+          return { error: { field, code: "invalid_option", message: `${field}: "${part}" is not a known option` } };
+        }
+        out.push(v2);
+      }
+      return { value: out };
+    }
     const v = matchOption(raw, meta?.options);
     if (v === void 0) {
       if (ctx.createMissingOptions) return { value: String(raw).trim() };
@@ -507,23 +542,23 @@ async function coerceFieldValue(raw, meta, ctx) {
     }
     return { value: v };
   }
-  if (MULTI_OPTION_TYPES2.has(t)) {
-    const parts = splitMulti(raw);
-    const out = [];
-    for (const part of parts) {
-      const v = matchOption(part, meta?.options);
-      if (v === void 0) {
-        if (ctx.createMissingOptions) {
-          out.push(part);
-          continue;
-        }
-        return { error: { field, code: "invalid_option", message: `${field}: "${part}" is not a known option` } };
+  if (REFERENCE_TYPES2.has(t)) {
+    if (isMultiValueField(meta)) {
+      const tokens = splitMulti(raw);
+      if (!ctx.resolveRef || !meta.reference) return { value: tokens };
+      const out = [];
+      for (const token of tokens) {
+        const m = normalizeRefMatch(await ctx.resolveRef(meta.reference, token, meta));
+        if (m.ambiguous) {
+          return { error: { field, code: "reference_ambiguous", message: `${field}: "${token}" matches more than one ${meta.reference} \u2014 use a unique value or the record id` } };
+        }
+        if (m.id === void 0) {
+          return { error: { field, code: "reference_not_found", message: `${field}: no ${meta.reference} matches "${token}"` } };
+        }
+        out.push(m.id);
       }
-      out.push(v);
+      return { value: out };
     }
-    return { value: out };
-  }
-  if (REFERENCE_TYPES2.has(t)) {
     const display = String(raw).trim();
     if (!ctx.resolveRef || !meta?.reference) return { value: display };
     const match = normalizeRefMatch(await ctx.resolveRef(meta.reference, display, meta));
@@ -535,6 +570,9 @@ async function coerceFieldValue(raw, meta, ctx) {
     }
     return { value: match.id };
   }
+  if (FILE_TYPES.has(t) && isMultiValueField(meta)) {
+    return { value: splitMulti(raw) };
+  }
   return { value: trim && typeof raw === "string" ? raw.trim() : raw };
 }
 var REQUIRED_CHECK_SKIP = /* @__PURE__ */ new Set([
@@ -585,6 +623,10 @@ function toFailedResult(rowNo, err) {
   return { row: rowNo, ok: false, action: "failed", error: message, code };
 }
 var MAX_CREATE_BATCH_SIZE = 200;
+var yieldToEventLoop = () => new Promise((resolve) => {
+  if (typeof setImmediate === "function") setImmediate(resolve);
+  else setTimeout(resolve, 0);
+});
 function runImport(opts) {
   const {
     p,
@@ -803,8 +845,9 @@ function runImport(opts) {
         await flushPendingCreates();
         if (onProgress) await onProgress(snapshot(processed));
       }
-      if (shouldCancel && processed < rows.length && processed % progressEvery === 0) {
-        if (await shouldCancel()) {
+      if (processed < rows.length && processed % progressEvery === 0) {
+        await yieldToEventLoop();
+        if (shouldCancel && await shouldCancel()) {
           cancelled = true;
           break;
         }
@@ -1068,7 +1111,7 @@ async function prepareImportRequest(body, opts) {
   const dryRun = body?.dryRun === true;
   let writeMode = body?.writeMode === "update" || body?.writeMode === "upsert" ? body.writeMode : "insert";
   let matchFields = Array.isArray(body?.matchFields) ? body.matchFields.filter((f) => typeof f === "string" && f.length > 0) : [];
-  const runAutomations = body?.runAutomations === true;
+  const runAutomations = body?.runAutomations !== false;
   const trimWhitespace = body?.trimWhitespace !== false;
   const nullValues = Array.isArray(body?.nullValues) ? body.nullValues.filter((v) => typeof v === "string") : void 0;
   const createMissingOptions = body?.createMissingOptions === true;
@@ -1228,6 +1271,16 @@ function mapDataError(error, object) {
       }
     };
   }
+  if (error?.code === "ATTACHMENT_PARENT_ACCESS" || error?.code === "ATTACHMENT_DELETE_DENIED") {
+    return {
+      status: 403,
+      body: {
+        error: error?.message ?? "Attachment access denied",
+        code: error.code,
+        ...error?.object || object ? { object: error?.object ?? object } : {}
+      }
+    };
+  }
   if (error?.code === "PERMISSION_DENIED" || error?.name === "PermissionDeniedError" || typeof error?.message === "string" && error.message.startsWith("[Security] Access denied")) {
     return {
       status: 403,
@@ -1247,6 +1300,17 @@ function mapDataError(error, object) {
       }
     };
   }
+  if (typeof error?.status === "number" && error.status >= 400 && error.status < 500) {
+    const msg = typeof error?.message === "string" && error.message.length > 0 && error.message.length < 500 ? error.message : "Request failed";
+    return {
+      status: error.status,
+      body: {
+        error: msg,
+        ...typeof error?.code === "string" && error.code ? { code: error.code } : {},
+        ...object ? { object } : {}
+      }
+    };
+  }
   const raw = String(error?.message ?? error ?? "");
   const lower = raw.toLowerCase();
   const sandboxWrapper = /^(?:hook|action) '[^']*' threw:\s*(.+)$/s.exec(raw);
@@ -1696,14 +1760,16 @@ var RestServer = class _RestServer {
       res.status(403).json({ error: { code: gate.code, message: gate.message } });
       return true;
     }
-    if (!this.config.api.requireAuth) return false;
-    if (context?.userId) return false;
-    if (req?.method === "OPTIONS") return false;
-    res.status(401).json({
-      error: "unauthenticated",
-      message: "Authentication is required to access this endpoint."
-    });
-    return true;
+    if (shouldDenyAnonymous({
+      requireAuth: this.config.api.requireAuth,
+      userId: context?.userId,
+      isSystem: context?.isSystem,
+      method: req?.method
+    })) {
+      res.status(ANONYMOUS_DENY_STATUS).json(ANONYMOUS_DENY_BODY);
+      return true;
+    }
+    return false;
   }
   /**
    * Enforce object-level API exposure (ObjectSchema `enable.apiEnabled` /
@@ -1921,6 +1987,10 @@ var RestServer = class _RestServer {
         permissions: authz.permissions,
         systemPermissions: authz.systemPermissions,
         ...authz.tabPermissions ? { tabPermissions: authz.tabPermissions } : {},
+        // [ADR-0095 D2 / #2947] Carry the derived posture rung so the
+        // enforcement side reads the SAME value the resolver computed,
+        // instead of dropping it here (the boundary this issue closes).
+        ...authz.posture ? { posture: authz.posture } : {},
         isSystem: false,
         org_user_ids: authz.org_user_ids,
         ...authGate ? { authGate } : {},
@@ -3450,7 +3520,7 @@ var RestServer = class _RestServer {
             res.json(result);
           } catch (error) {
             const mapped = mapDataError(error, req.params?.object);
-            if (mapped.status === 404 || mapped.status === 503 || mapped.status === 502) {
+            if (isExpectedDataStatus(mapped.status) || mapped.body?.code === "UNSUPPORTED_QUERY_PARAM") {
               res.status(mapped.status).json(mapped.body);
             } else {
               logError("[REST] Unhandled error:", error);
@@ -3742,6 +3812,16 @@ var RestServer = class _RestServer {
         tags: ["data", "import"]
       }
     });
+    const loadImportJob = async (p, jobId, environmentId, context) => {
+      const r = await p.findData({
+        object: IMPORT_JOB_OBJECT,
+        query: { $filter: { id: jobId }, $top: 1 },
+        ...environmentId ? { environmentId } : {},
+        ...context ? { context } : {}
+      });
+      const rows = Array.isArray(r?.records) ? r.records : Array.isArray(r?.data) ? r.data : Array.isArray(r?.rows) ? r.rows : Array.isArray(r) ? r : [];
+      return rows[0];
+    };
     this.routeManager.register({
       method: "POST",
       path: `${dataPath}/:object/import/jobs`,
@@ -3807,6 +3887,11 @@ var RestServer = class _RestServer {
           };
           const captureUndo = !prepared.dryRun && prepared.rows.length <= IMPORT_JOB_UNDO_MAX_ROWS;
           void (async () => {
+            if (this.cancelledImportJobs.has(jobId)) {
+              this.cancelledImportJobs.delete(jobId);
+              await patch({ status: "cancelled", completed_at: (/* @__PURE__ */ new Date()).toISOString() });
+              return;
+            }
             await patch({ status: "running", started_at: (/* @__PURE__ */ new Date()).toISOString() });
             try {
               const summary = await runImport({
@@ -3824,10 +3909,27 @@ var RestServer = class _RestServer {
                   skipped_count: pr.skipped,
                   error_count: pr.errors
                 }),
-                shouldCancel: () => this.cancelledImportJobs.has(jobId)
+                shouldCancel: async () => {
+                  if (this.cancelledImportJobs.has(jobId)) return true;
+                  try {
+                    const row = await loadImportJob(p, jobId, environmentId, context);
+                    return String(row?.status ?? "") === "cancelled";
+                  } catch {
+                    return false;
+                  }
+                }
               });
+              let finalStatus = summary.cancelled ? "cancelled" : "succeeded";
+              if (finalStatus === "succeeded" && this.cancelledImportJobs.has(jobId)) finalStatus = "cancelled";
+              if (finalStatus === "succeeded") {
+                try {
+                  const row = await loadImportJob(p, jobId, environmentId, context);
+                  if (String(row?.status ?? "") === "cancelled") finalStatus = "cancelled";
+                } catch {
+                }
+              }
               await patch({
-                status: summary.cancelled ? "cancelled" : "succeeded",
+                status: finalStatus,
                 processed_rows: summary.processed,
                 created_count: summary.created,
                 updated_count: summary.updated,
@@ -3857,16 +3959,6 @@ var RestServer = class _RestServer {
         tags: ["data", "import"]
       }
     });
-    const loadImportJob = async (p, jobId, environmentId, context) => {
-      const r = await p.findData({
-        object: IMPORT_JOB_OBJECT,
-        query: { $filter: { id: jobId }, $top: 1 },
-        ...environmentId ? { environmentId } : {},
-        ...context ? { context } : {}
-      });
-      const rows = Array.isArray(r?.records) ? r.records : Array.isArray(r?.data) ? r.data : Array.isArray(r?.rows) ? r.rows : Array.isArray(r) ? r : [];
-      return rows[0];
-    };
     this.routeManager.register({
       method: "POST",
       path: `${dataPath}/import/jobs/:jobId/cancel`,
@@ -4450,6 +4542,7 @@ var RestServer = class _RestServer {
                 }
                 const fields = {};
                 for (const [name, def] of Object.entries(obj.fields)) {
+                  if (PUBLIC_FORM_SERVER_MANAGED_FIELDS.has(name)) continue;
                   if (allowed.size === 0 || allowed.has(name)) {
                     fields[name] = def;
                   }
@@ -4474,6 +4567,7 @@ var RestServer = class _RestServer {
           const safeForm = (() => {
             if (!match.form || !Array.isArray(match.form.sections)) return match.form;
             const allow = (name, cfg) => {
+              if (PUBLIC_FORM_SERVER_MANAGED_FIELDS.has(name)) return false;
               const def = objectSchema?.fields?.[name];
               const t = def?.type;
               if (t !== "lookup" && t !== "master_detail" && t !== "user") return true;
@@ -4539,12 +4633,10 @@ var RestServer = class _RestServer {
           }
           const rawBody = req.body && typeof req.body === "object" ? req.body : {};
           const filteredData = {};
-          if (allowedFields.size > 0) {
-            for (const [k, v] of Object.entries(rawBody)) {
-              if (allowedFields.has(k)) filteredData[k] = v;
-            }
-          } else {
-            Object.assign(filteredData, rawBody);
+          for (const [k, v] of Object.entries(rawBody)) {
+            if (PUBLIC_FORM_SERVER_MANAGED_FIELDS.has(k)) continue;
+            if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
+            if (allowedFields.size === 0 || allowedFields.has(k)) filteredData[k] = v;
           }
           const context = {
             publicFormGrant: { object: match.object },
@@ -4593,15 +4685,17 @@ var RestServer = class _RestServer {
             return;
           }
           let fieldCfg = null;
-          for (const sec of match.form?.sections ?? []) {
-            for (const f of sec?.fields ?? []) {
-              const name = typeof f === "string" ? f : f?.field;
-              if (name === fieldName) {
-                fieldCfg = typeof f === "string" ? {} : f;
-                break;
+          if (!PUBLIC_FORM_SERVER_MANAGED_FIELDS.has(fieldName)) {
+            for (const sec of match.form?.sections ?? []) {
+              for (const f of sec?.fields ?? []) {
+                const name = typeof f === "string" ? f : f?.field;
+                if (name === fieldName) {
+                  fieldCfg = typeof f === "string" ? {} : f;
+                  break;
+                }
               }
+              if (fieldCfg) break;
             }
-            if (fieldCfg) break;
           }
           const picker = fieldCfg?.publicPicker;
           if (!picker) {
@@ -4859,12 +4953,15 @@ var RestServer = class _RestServer {
         const parsed = ExplainRequestSchema.safeParse({
           object: src.object,
           operation: src.operation ?? "read",
-          ...src.userId != null && src.userId !== "" ? { userId: src.userId } : {}
+          ...src.userId != null && src.userId !== "" ? { userId: src.userId } : {},
+          // [C2 / ADR-0095] Optional record id — explains ONE concrete
+          // row at record granularity; omitted stays object-level.
+          ...src.recordId != null && src.recordId !== "" ? { recordId: src.recordId } : {}
         });
         if (!parsed.success) {
           return res.status(400).json({
             code: "VALIDATION_FAILED",
-            message: "Invalid explain request \u2014 expected { object: string, operation: read|create|update|delete|transfer|restore|purge, userId?: string }.",
+            message: "Invalid explain request \u2014 expected { object: string, operation: read|create|update|delete|transfer|restore|purge, userId?: string, recordId?: string }.",
             detail: String(parsed.error?.message ?? "").slice(0, 1e3)
           });
         }