[finding] `ImportRequest.runAutomations` declares `.default(false)` and documents "off by default for bulk", but `POST /data/:object/import` defaults it ON

[qq9340100]

Observation-class finding, recorded while documenting the import dry-run hook boundary (#6537, PR for it links back here). Not fixed there: the fix is a contract call, not a docs edit.

What was measured

packages/spec/src/api/export.zod.ts (ImportRequestSchema, the body schema of POST /api/v1/data/:object/import and of CreateImportJobRequest):

runAutomations: z.boolean().default(false)
  .describe('Fire triggers/hooks for each imported row (off by default for bulk)'),

packages/rest/src/import-prepare.ts:262, the code that actually decides:

// Default ON: automations always ran historically (the engine ignored the
// flag until #2922), so opt-out must be explicit — matches platform
// convention (Salesforce runs triggers on import by default).
const runAutomations = body?.runAutomations !== false;

So an omitted runAutomations runs automations. The declared default and the prose next to it both say the opposite, and both ship: the describe text renders into the published reference page (content/docs/references/api/export.mdx, ImportRequest + CreateImportJobRequest tables), and .default(false) ships in @objectstack/spec's JSON Schema.

Why it is not merely cosmetic

The route never parses its body through ImportRequestSchema — prepareImport reads the raw body — so nothing reconciles the two today. The divergence bites in two directions:

1. A client or SDK that does parse the request through the schema materializes runAutomations: false from the declared default and sends it explicitly. The server then honours it: automations off, silently, for a caller who set nothing. Same request body in, opposite behaviour, decided by whether the caller validated it.
2. An author reading the reference page is told bulk import does not fire triggers by default. It does.

This is the declared-versus-enforced shape of Prime Directive #10, on a flag that decides whether user-authored hooks run over a whole spreadsheet.

Dispositions (a contract call — deliberately not guessed here)

• A. Move the spec to the runtime: .default(true) plus corrected prose. Zero runtime change, but it flips the declared default of a shipped published schema, so it needs a version/level decision and possibly a note for parsing clients.
• B. Move the runtime to the spec: body?.runAutomations === true. A real behaviour change on a documented-since-数据导入:批量 insert 给 Hook 的输入形状与单条不一致(installFlatInput 失效);「运行自动化与触发器」开关是摆设且默认值应为选中 #2922 default, and it contradicts the reasoning recorded in the import-prepare.ts comment above; almost certainly wrong, listed for completeness.
• C. Keep both and remove the ambiguity: drop .default() (leave it optional with no declared default) and state the server-side default in the describe text, so the schema stops asserting a default it does not own.

No recommendation is offered without the maintainer's read on who is allowed to parse this schema — that is the fact that decides between A and C.

Not touched by #6537's PR

That PR documents the dry-run boundary on ImportRequest.dryRun and deliberately phrases it as "a dry run with runAutomations: true" rather than naming a default, precisely so it does not have to take a side here.

[os-zhuang]

Findings-round routing repair: domain:spec added. Routing only — finding grade unchanged, no ownership taken.

• Landing anchors verified on origin/main @ cfeb9a0: packages/spec/src/api/export.zod.ts:336-337 still declares runAutomations: z.boolean().default(false) with the "off by default for bulk" describe text; packages/rest/src/import-prepare.ts still decides body?.runAutomations !== false (default ON) with the 数据导入:批量 insert 给 Hook 的输入形状与单条不一致(installFlatInput 失效);「运行自动化与触发器」开关是摆设且默认值应为选中 #2922 rationale comment. The divergence is live.
• Routing rationale: dispositions A and C — the two the body treats as viable — both land in the spec schema's declared-default face, and a declared default in the shipped JSON Schema is semantic surface (it changes what a parsing client materializes and sends), not describe-text: domain:spec, not spec-surface. If B were ever chosen it would move to packages/rest, but the body itself marks B "almost certainly wrong". The A-vs-C fork needs the maintainer's read on who parses this schema — that escalation belongs to the grading step, not to routing.
• Dedup: Import dry run with runAutomations: true can now report required for a field a beforeInsert hook would have populated #6537 (dispatched, domain:cli) is the dry-run boundary card this was filed from and deliberately does not take a side here; no other open card touches the runAutomations default. Clean.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-zhuang]

Findings-triage round (#4949 discipline): moved to the decision box — finding → needs-user-decision, plus target:v17. domain:spec kept.

• Stale-premise check (origin/main @ 3172831): both halves live — packages/spec/src/api/export.zod.ts:343 still declares runAutomations: z.boolean().default(false) with the "off by default for bulk" prose, and packages/rest/src/import-prepare.ts:262 still decides body?.runAutomations !== false (default ON, with the 数据导入:批量 insert 给 Hook 的输入形状与单条不一致(installFlatInput 失效);「运行自动化与触发器」开关是摆设且默认值应为选中 #2922 rationale comment).
• Why the decision box, not the queue: the body is explicit that choosing between disposition A (spec follows runtime: .default(true), flips a shipped published schema's declared default) and C (drop .default(), schema stops asserting a default it does not own) turns on who is allowed to parse this schema — a public-contract call, not an implementation detail. B (runtime follows spec) contradicts the recorded 数据导入:批量 insert 给 Hook 的输入形状与单条不一致(installFlatInput 失效);「运行自动化与触发器」开关是摆设且默认值应为选中 #2922 rationale and is listed by the body only for completeness. No triage-level default exists here: A and C differ in what every parsing client materializes.
• Why target:v17: board class ② — public contract declared ≠ enforced. The shipped JSON Schema and the published reference page both assert a default the server inverts, on a flag that decides whether user-authored hooks run over a whole import. A schema-parsing client silently gets automations OFF for a caller who set nothing (measured direction 1 in the body); shipping the RC leaves the published schema lying.
• Dedup: Import dry run with runAutomations: true can now report required for a field a beforeInsert hook would have populated #6537 (dry-run boundary docs) deliberately took no side here, per its own PR text; no other card touches this default. Clean.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-project-manager]

Maintainer ruling (2026-08-09): disposition A — the spec follows the runtime. pm:queue.

ImportRequest.runAutomations becomes .default(true) with corrected describe prose (state that automations run by default and opt-out must be explicit, per the #2922 rationale); the generated reference tables follow. Runtime behaviour unchanged.

Rationale (three-axis): the deciding fact the card asked for is what schema-parsing clients do — they materialize the declared default and send it. Today that means a validating client silently sends runAutomations: false and gets the opposite of the server's own default: same request, opposite behaviour, decided by whether the caller validated. A fixes that at the source: after it, the materialized value and the server's decision agree. C (drop .default()) merely goes silent — honest, but a codegen'd client still has no machine-readable default, and the ambiguity survives. One contract, declared = enforced. B stays rejected per the recorded #2922 reasoning. Changeset notes the declared-default flip of a published schema (a correction toward the actual shipped behaviour, not a behaviour change).

Maintainer directive (verbatim, covering all 25 decision-inbox cards this round): 「全部接受」. Recorded by PM session session_01LGRN2cSRfggfX9B2L83bQc. Veto window open — comment to overturn.

---

Generated by Claude Code