skills(objectstack-api): teach import applyOn, read FLOW_FAILED's innerRefusal, and the anonymous-form file refusal - #26392

Contract review

Reviewed at 2026-10-27T02:06Z · PR #26392 · card #26299 · independent contract review at the ceiling tier, read-only, adversarial to the dispatch order, the seat's claim and the dev's report alike.

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 3add67c79c287ff30ecc3e921c93959a9908624a
Local-runs: none
Scope: skills/objectstack-api/SKILL.md, skills/objectstack-api/evals/endpoints-auth-routes.json + scripts/check-skills-token-ratchet.mjs, packages/rest/src/import-prepare.ts, packages/core/src/utils/import-runner.ts, packages/spec/src/api/export.zod.ts, packages/spec/src/data/column-apply-on.zod.ts, packages/spec/src/api/automation-api.zod.ts, packages/spec/src/api/contract.zod.ts, packages/runtime/src/domains/automation.ts, packages/runtime/src/endpoint-executor.ts, packages/runtime/CHANGELOG.md, packages/lint/src/validate-public-form-file-fields.ts, packages/lint/src/authoring-rules.ts, packages/lint/src/runtime-gate.ts, packages/spec/src/data/field-value.zod.ts, packages/rest/src/form-routes.ts, packages/types/src/validation-failure.ts, .claude/agents/os-dev.md, .github/PULL_REQUEST_TEMPLATE.md, scripts/pm/clause2-line.mjs, .github/workflows/lint.yml

Landing state as read. A GOVERNED_APPROVERS account approved twice at 2026-10-27T01:52Z on this head and armed auto-merge (merge method merge); at 2026-10-27T02:03Z the PR was still open, merged: false, mergeable_state: blocked (waiting on checks). This record is owed on the head regardless and is rendered from git show 3add67c7:PATH against origin/main at abb90460, never from the shared checkout. The PR's recorded base abb90460 is not an ancestor of the head: the merge-base is 756220c4, and main moved from 756220c4 to abb90460 on none of the three files this PR touches (git diff --stat 756220c4 abb90460 -- scripts/check-skills-token-ratchet.mjs skills/objectstack-api/ is empty), so the three-file diff below is the whole PR and the dev's "read off main at 756220c" readings hold on the live tip.

Check-runs on 3add67c7 (read twice, last at 2026-10-27T02:03Z, not waited for): 51 runs, 34 success, 16 skipped (UI, docs, dogfood-regression and opt-in lanes the path filter turned off), 1 in_progress (TypeScript Type Check). Every gate this PR can move is green: Type Check · source gates (the lane that runs node scripts/check-skills-token-ratchet.mjs and its --self-test, check:ratchet-remedy-authority, check:skill-docs and check:skill-refs — read off lint.yml lines 5326, 5458, 5582, 5589–5590 under job typecheck-source-gates, not the "Lint · repo & tooling gates" lane the sibling brief assumed), Type Check · consumer gates (runs check:skill-examples, line 6463, job typecheck-consumers) — success at 2026-10-27T01:56Z and later, Lint · ESLint, Lint · repo & tooling gates, Lint · docs & code guards, Lint · PM dispatch-gates, Check Changeset, Governed Surface Queue Guard, Part-of PR must not also close its card, The card this PR closes must claim this branch, No other open PR may claim the same issue, Build Core and Test Core 1–8. Nothing red.

① Derived judgments

(a) Every new sentence is true of the spec and the implementation on origin/main. Three hunks, 27 added lines in SKILL.md, each read line by line:

1. Public-form file field (SKILL.md lines 104–111, inside "Public (anonymous) Form Endpoints", which the card's SKILL.md:75-100 names). RIGHT on every clause. FILE_REFERENCE_TYPES is image, file, avatar, video, audio (field-value.zod.ts:306-308). The rule id is the exported constant PUBLIC_FORM_FILE_FIELD = 'public-form-file-field'; its registry row is tier: 'gating', commands: ALL where AUTHORING_COMMANDS = ['validate', 'build', 'lint'] (authoring-rules.ts:167, 462, 1584-1593) — so "at os validate / os build / os lint" is exact. "And at the view's publish": surfaces: CLI_AND_RUNTIME with runtimeTypes: ['view'], and runtime-gate.ts:584-592 selects rules whose surfaces include runtime-publish for the written type — the registry comment states the view's publish is refused at the key and an object write is deliberately not covered; the skill's sentence claims only the view's publish, which is what holds. "A visitor has no upload door to mint a sys_file id" is the rule's own header wording. The submit-door sentence: form-routes.ts:650-663 pushes { field, code: 'invalid_value', message, label } for every file-typed field carrying a non-empty value and throws validationFailure(...), whose constructor (packages/types/src/validation-failure.ts:76-82) is what both dispatcher exits map to 400 VALIDATION_FAILED + details.fields[]; the file's own comments at 585 and 616 call this "the flat 400 VALIDATION_FAILED with fields[]", so "flat" is the code's term, not the dev's. The qualifier "a form published before that rule" is the only population that can still carry a file field after the rule, and the refusal fires on any such submission. The prescription "collect the file on a signed-in form instead" is ruling C's own route as the rule header records it.

2. Import applyOn (SKILL.md lines 269–275, directly after the derived-verbs table whose import row is the card's SKILL.md:253 neighbourhood). RIGHT. ImportMappingSchema is the union of the { Column: field } record and z.array(FieldMappingEntrySchema) (export.zod.ts:241-245); applyOn: ColumnApplyOnSchema.default('always') sits on the entry only (export.zod.ts:174; the enum is ['create', 'always'], column-apply-on.zod.ts). The door: prepareImportRequest reads applyOn only in the Array.isArray(body.mapping) branch, treats undefined as always, and returns { status: 400, code: 'INVALID_REQUEST' } for any value outside the pair (import-prepare.ts:610-627); both routes (data-action-routes.ts:369, :483) call it on the raw body with no prior Zod parse that could answer first, so "any other value is 400 INVALID_REQUEST" is exactly what the door answers. The record form silently ignores applyOn (it keeps only string values), so "only the entry form carries applyOn" is right. "A re-run upsert refreshes the always columns and leaves a value an admin set since": import-runner.ts:690-694 builds the update patch as if (!createOnly.has(k) || keySet.includes(k)) patch[k] = v. "A create-only column is still read for matching": true — findExisting reads data[f] for every key-set field regardless of applyOn — and the runner additionally still WRITES a create-only column on update when it belongs to the matched key set (the || keySet.includes(k) arm). The skill's sentence is true as written; it leaves that corner unsaid, which is a scope choice, not a falsehood (an author who marks a match key create-only gets the key written back unchanged).

3. FLOW_FAILED details (SKILL.md lines 372–380, inside "Error Envelopes & the Code Ledger"). RIGHT. FlowFailureDetailsSchema is exactly errorMessage? ("the flow author's own failure text"), summary? (FlowRunSummarySchema, "which node failed") and innerRefusal? (automation-api.zod.ts:585-602); FlowInnerRefusalSchema is { code: ErrorCode, message: string } with code "in its WIRE spelling (e.g. UNIQUE_VIOLATION)" (lines 334–344). The three example codes the skill lists are the ones the runtime CHANGELOG names for the node catch arms. The doors: the trigger route is POST /api/v1/automation/:name/trigger (automation-api.zod.ts:43; the skill's {name} spelling matches the file's own /data/{object}/import convention), and the dispatch table at automation.ts:2041-2048 / endpoint-executor.ts:476-480 answers "ran and failed" with 400 FLOW_FAILED at the trigger, resume, /actions and declared-endpoint doors (the "409 at the trigger door" line in endpoint-executor.ts:487 is the history the table replaced, not the current answer). The render order userMessage → details.innerRefusal → message is NOT the dev's invention: it is the CHANGELOG's own "For consumers" sentence on the entry that landed innerRefusal ("render a refused run the way a record form renders a refused save: the top-level userMessage when present, then details.innerRefusal, then message"), and userMessage is ApiErrorSchema.userMessage (contract.zod.ts:93). "Absent keys mean the run produced none — never invent an empty" is the schema's own "absent means absent, never an invented empty".

(b) Cuts. None. The diff removes nothing from the package (0 deletions in SKILL.md and the eval file; references/_index.md byte-identical, 3200 bytes). The card names no stale lines and the base package has 0 hits for applyOn, innerRefusal, FLOW_FAILED and file field (git grep -c on 756220c4), so no duplicate existed to cut; ruling A's "削重复 first" is satisfied vacuously and the PR body says so.

(c) Ratchet row. The script's measure is Math.ceil(Buffer.byteLength(text, 'utf8') / 4) with one exclusion, the indented release-stamp line of a SKILL.md (check-skills-token-ratchet.mjs:49, 77-113). Recomputed by hand over the head blobs (a byte count, not a run): endpoints-auth-routes.json is 4936 bytes on the head → ceil(4936/4) = 1234, and 4156 bytes on the base → 1039; the new row is 1234 — pinned AT the measurement, zero headroom, no smuggled room. The row's arithmetic checks: +780 bytes = 4936 − 4156; +192 = 1234 − 1042; the 3 absorbed tokens = 1042 − 1039. SKILL.md is 20532 bytes on the head; minus the 20-byte stamp line → 20512/4 = 5128, under the untouched ceiling 6314 (base 18782 − 20 → 4691), so no second row moves and none should. The raise rule (header lines 128–130) requires "a PR whose body quotes a maintainer ruling authorizing it"; the script itself reads no PR body, so the evidence is the body and the row comment, and both quote the tap 「A:先削重复,余额按实测提高」 verbatim with the card's title, the date and the per-file before/after. The row comment follows the shape of the 2026-08-31 precedent block (ruling quoted untranslated, paid-down-first statement, arithmetic) and sits inside the CEILINGS map, not between the precedent block and the SHRINK-ONLY doc comment that check-ratchet-remedy-authority anchors on (placement warning at lines 294–301); that gate ran green in Type Check · source gates. No eslint max-len rule exists anywhere in the repo's config (0 hits), and Lint · ESLint is green, so the long comment lines are not a lint risk. The "0 duplicate bytes" claim, judged on the eval file itself: fixtures 1–5 are five distinct prompts (declarative endpoint, anonymous endpoint budget, webhook gap, auth providers, apiMethods derivation) and no sentence recurs between them; the only phrase shared with anything is "the flat public + permissions pair" in fixture 4, which the SKILL.md also carries at line 322 — a different file, and the ratchet prices per file. The claim holds.

(d) Eval. One fixture, id 6, ids 1–6 unique and sequential, the file's existing shape (prompt / expected_output / files: [] / assertions). Every must_contain token (applyOn, 'create', sourceField, targetField) appears in expected_output; must_not_contain: ["writeMode: 'insert'"] is consistent with the expected writeMode: 'upsert' and with the import door's semantics. The expected output's mechanics match the runner (written on create, left out of the patch on a match, others default always). The card-specific acceptance asks one eval for the import and that is the one present; the shared Acceptance's "every new teaching gets an eval prompt" is met for the import teaching only — the FLOW_FAILED and public-form-file teachings carry no eval. The card's own text resolves that conflict in the dev's favour (the card-specific line "one eval for the import" is the narrower, later instruction, the dispatch order says "the card asks one eval, for the import", and the dev's report declares the scope), so this is a boundary note, not a failure. The package has no evals README or index counting prompts (three files in the tree), so nothing else needs updating.

(e) Wanted lines met, nothing beyond. All three Wanted items land in the named sections (verified above). Line 1 of SKILL.md (version frontmatter, PR #25640's line) is unchanged — the first five lines of base and head are identical. No file outside the claim + amendment surface: the three paths are skills/objectstack-api/SKILL.md, skills/objectstack-api/evals/endpoints-auth-routes.json and the one CEILINGS row in scripts/check-skills-token-ratchet.mjs. Line readings claimed in the body are exact: SKILL.md 417 → 444, eval 55 → 65, _index.md 46 → 46, package 463 → 490.

(f) PR body shape. Line 1 is the harness attribution HTML comment, line 2 the harness's _Requested by_ line, line 3 Fixes #26299, lines 4–5 Clause-②: no and Metadata-protocol: none, each line-initial and each occurring exactly once. os-dev.md on main (line 323) exempts the harness-written attribution comment on line 1 ("原样留、只报") and wants Fixes "紧随其后"; the harness wrote two lines, and Fixes follows that block on line 3. clause2-line.mjs's reader is CLAUSE2_KEY_LINE = /^[ \t]*...Clause-②...:(.*)$/ (line-initial, any line of the body), so the declaration lines are read wherever they sit; the template puts them under ## Verification, os-dev.md after Fixes, and this body satisfies both readers with one pair. The CI checks that parse the closing keyword (The card this PR closes must claim this branch, Part-of PR must not also close its card, No other open PR may claim the same issue) are green on the head, which is the proof the attribution comment did not hide Fixes from any parser. ## 维护者速读 carries the six labels in order; 需要你做的 names one action (approve / Merge when ready — right for Tier H); 先看 names three hunks with line numbers; 两分钟验证 is one command with the expected sight, and the sight it promises (SKILL.md 5128 / 6314, endpoints-auth-routes.json 1234 / 1234 (+0)) is the dev's paraphrase of the script's report lines, whose real wording the body's own details block quotes (... is 5128 tokens (ceiling 6314; headroom 1186) / ... is 1234 tokens (ceiling 1234; headroom 0)) — a reader grepping the output finds the numbers, so the verification works as written. English sections What changes / Tests / Acceptance notes / Verification are present with readings folded into details blocks; the extra ## Why and ## Human Minimum come from .github/PULL_REQUEST_TEMPLATE.md (landed on main at 756220c4, after dispatch); os-dev.md's 英文节序 line names an order and forbids no extra section, and the dev named the conflict rather than picking silently. The commit's trailer pair is model-free. The body reports no model name.

(g) Report. os-dev-report 6431775093 carries issue, status: done, branch: claude/project-thread-i1b4v5 (= the claim's branch), pr, session, premise_still_valid, summary, tests, gates, dogfood_battery: n/a (no !, no narrowing arm — right), mcp_calls: 0, api_writes: 3 with endpoints, line_budget, deviations (7), open_questions: [], out_of_scope_findings (2). files_changed / rules_retired are absent, and os-dev.md's JSON template on main (lines 362–384) does not list them, so nothing is missing. One note: the report's summary and first deviation name the served models by id; the dispatch order's ban reads "no model name anywhere in the commit or PR", and both the commit message and the PR body are clean — the card comment is outside the ban's letter, so this is a process note, not a defect.

② Semver level

skip-changeset is right: skills/objectstack-api/ carries no package.json (tree: SKILL.md, evals/endpoints-auth-routes.json, references/_index.md), scripts/** publishes no npm package, and Check Changeset is green on the head. Clause-②: no and Metadata-protocol: none are correct — the skill teaches keys the protocol already carries (FieldMappingEntry.applyOn, FlowFailureDetails, the lint rule), no accept set moves. Both declaration lines are line-initial and the value is the first thing after the colon.

③ Boundary flags

• Dev's out-of-scope note 1 — SeedColumn.applyOn (same ColumnApplyOnSchema, seed.zod.ts) is objectstack-data's surface and is untaught there: confirmed, git grep -c applyOn origin/main -- skills/objectstack-data/ is 0 hits. That belongs to the skills(objectstack-data): teach membership keys, ownerMayEdit, create-only seed columns, the position-to-set binding and the external role, and fix the reference: 'user' example #26297 (objectstack-data) card's dev or a follow-up card on that package; it is a 收班简报 note for the seat, not this PR's debt.
• Dev's out-of-scope note 2 — the premise read looked for the anonymous-form file refusal in packages/spec/src/api while it lives in packages/lint + packages/rest/src/form-routes.ts: confirmed by reading; a process note for the seat's premise-read recipe, nothing to file.
• Eval coverage — only the import teaching has an eval (card-specific acceptance), while the shared Acceptance's "every new teaching gets an eval" would want two more (FLOW_FAILED details, public-form file field). The card's own narrower line and the dispatch order settle this PR; the seat may want to carry "evals for API2/API3" as a note for a later ratchet-paying card. Not a defect of this head.
• PR-template vs os-dev.md — the template's declaration-lines-under-Verification layout and os-dev.md's after-Fixes layout are both satisfied by one pair here, and the template's ## Why / ## Human Minimum are extra sections os-dev.md does not forbid. The two documents should converge in os-dev.md, and the harness's two-line attribution block (comment + _Requested by_) should be named in os-dev.md line 323, which today reads as one line. 收班简报 note; nothing for this PR.
• Lane naming — the ratchet, check:ratchet-remedy-authority, check:skill-docs and check:skill-refs run in Type Check · source gates, and check:skill-examples in Type Check · consumer gates, not in the "Lint · …" lanes the reviewer briefs assumed. A note for the brief template, not for this PR.
• Base reconciliation — base abb90460 vs merge-base 756220c4: main moved on none of the three touched files, the ratchet row on main still reads 1042, so the merge carries exactly this diff.

Implemented-by: claude/project-thread-i1b4v5
Reviewed-by: session_01LqKsGyMNFwwnbF5FTAqyPn

VERDICT: PASS

维护者速读

改了什么:skills/objectstack-api 补三段教学,各落在卡点名的章节:公开表单段加「匿名表单不声明文件字段」(lint 规则 public-form-file-field、发布门、旧表单提交时的 400 VALIDATION_FAILED);派生操作表后加导入 mapping 条目的 applyOn: 'always' | 'create'(仅条目数组形态;其它值 400 INVALID_REQUEST);错误信封段加流程门 400 FLOW_FAILED 的 details(errorMessage / summary / innerRefusal)与渲染顺序。eval 加一题导入;该 eval 文件天花板按你的裁决 A 实测抬 1042 → 1234(五条夹具无一句重复可削,正文已说明)。什么都没删。
为什么改:审计 § objectstack-api 三行均「未教、无 eval」:写导入作业的 AI 作者每次重跑 upsert 都会覆盖管理员手改的列;客户端只能显示「flow failed」;公开表单作者会声明访客永远填不了的文件字段。
风险与回滚:只改发布技能文本与一条棘轮行,无运行时代码;每句都对着 main 的 spec/实现核过;回滚 = revert 本 PR。
先看:① SKILL.md 三个 hunk(行 104–111、269–275、372–380);② eval 第 6 题;③ 棘轮 endpoints-auth-routes.json 行。
两分钟验证:node scripts/check-skills-token-ratchet.mjs | grep objectstack-api 预期 SKILL.md 5128 / 6314、endpoints-auth-routes.json 1234 / 1234。
需要你做的:无——os-zhuang 已 approve + ready + 入队(01:52Z),合入即落地。
席位意见:同意落地。两处留作后续(不挡本 PR):导入里「仅建时写」的列若同时在匹配键集里,更新时仍会写入(runner || keySet.includes(k)),技能只说「仍参与匹配」;FLOW_FAILED 与公开表单两段还没有 eval(卡只要求导入那一条)。

席位核对

ACCEPT · domain:skills#2 · session_01LqKsGyMNFwwnbF5FTAqyPn · 2026-10-27T02:10Z — seat review of record for #26299 on head 3add67c7, against GitHub, not the report's own account. Published surface skills/** ⇒ Tier H: the record of this tier is the independent ## Contract review at comment 6431952702 (Served-tier: CONTRACT_REVIEW_TIER, head 3add67c7, VERDICT: PASS, Local-runs: none; drafted by a reviewer other than the implementer, the card thread's dev). This seat adds the landing read. Order of events, reported: the governed approver's hand ran ahead of this record (see 6).

1. Shape. Base main, mergeable_state: clean; body lines 1–2 the harness attribution block, line 3 Fixes #26299 (os-dev.md 323's exemption; the closing-keyword guards green), Clause-②: no, Metadata-protocol: none line-initial (kind none ⇒ no Skills-docs: line owed under the rule landed in b33dd25b); ## 维护者速读 six labels in order, then What changes / Tests / Acceptance notes / Verification with folds. Files: SKILL.md (+27), evals/endpoints-auth-routes.json (+10), scripts/check-skills-token-ratchet.mjs (+18/−1, one row) — the claim's surface (6430933607) as amended at 2026-10-27T01:26Z (+ the package's CEILINGS rows under ruling A); line 1 of SKILL.md untouched. Labels documentation, size/s, skip-changeset — right, no package.json under skills/objectstack-api. Branch claude/project-thread-i1b4v5, named by the claim. Model: the thread switched to the ceiling tier on the maintainer's own words before its first edit (reported in the os-dev-report).
2. Record, measured. All three teachings true of the spec/implementation on origin/main: applyOn (export.zod.ts:174, column-apply-on.zod.ts, import-prepare.ts:610–627 → 400 INVALID_REQUEST; runner import-runner.ts:690–694); FLOW_FAILED details (automation-api.zod.ts:585–602, inner refusal 334–344; the render order is the runtime CHANGELOG's own sentence; doors per automation.ts:2041–2048 / endpoint-executor.ts:476–480); public-form file field (lint rule public-form-file-field, publish gate; form-routes.ts:650–663 invalid_value → 400 VALIDATION_FAILED, 「flat」 the code's own word). Ratchet: ceil(4936/4) = 1234 = the row, headroom 0; SKILL.md 5128 of 6314 untouched; 0 duplicate bytes holds. Eval 6 well-formed, ids 1–6 sequential. Line counts 417→444, 55→65, 46→46, package 463→490. Base reconciled: merge-base 756220c4, main moved on none of the three files. The seat re-read the diff and reads the same.
3. Gates, pinned to head 3add67c7. 51 check-runs on the head: 34 success, 16 skipped, 1 in progress (TypeScript Type Check) at 2026-10-27T02:03Z; Type Check · source gates (ratchet, skill-docs, skill-refs) and Type Check · consumer gates (skill-examples) success. Lane map read off today's lint.yml: the token ratchet, check:skill-docs and check:skill-refs run in Type Check · source gates; check:skill-examples in Type Check · consumer gates.
4. Accepted deviations. (a) Surface widened to the CEILINGS rows — the seat's own amendment under ruling A. (b) The card's cited commits unreachable in the shallow clone; spec lines cited instead. (c) check:dual-build-cjs-loads NOT MEASURED locally (whole-tree build prerequisite), CI's run green. (d) Fixes on line 3 under the harness block.
5. Carrier. Nothing to file. 收班简报: SeedColumn.applyOn untaught in skills/objectstack-data (route to skills(objectstack-data): teach membership keys, ownerMayEdit, create-only seed columns, the position-to-set binding and the external role, and fix the reference: 'user' example #26297); API2/API3 have no eval; os-dev.md 323 names a one-line attribution exemption while the harness writes two lines; the os-dev-report named served models by id (the ban covers commit and PR; extend to reports?).
6. Landing. os-zhuang approved twice, readied and armed at 2026-10-27T01:52Z; the PR sits in the merge queue — ⛔ nothing for the seat to ready, arm or enqueue. On MERGED the seat closes the card with the landing record.

Generated by Claude Code