Repository navigation
NotifyConfigSchema sourceObject/sourceId describes say "Requires ..." while the schema deliberately accepts the half pair (executor drops it silently) #7085
Description
Finding from the axis-① .describe() sweep (describe claims vs measured acceptance face — the #6762 class). Recorded unassigned; suggest domain:spec-surface for routing. Sibling of the severity finding on the same schema (filed separately — different field, different claim type).
Anchor
packages/spec/src/automation/io-node-config.zod.ts, NotifyConfigSchema:
sourceObject: z.string().optional()
.describe('Object name of the record the notification links to (writes sys_notification.source_object). Requires sourceId.'),
sourceId: z.string().optional()
.describe('Record id the notification links to (writes sys_notification.source_id). Requires sourceObject.'),Described claim
"Requires sourceId." / "Requires sourceObject." — to a schema reader, "requires" says the half-specified pair is refused at the gate.
Measured acceptance face
Probed on origin/main @ 2f3e79351 (tsx safeParse, sources via git archive; controls both sides):
control-accept full pair : ACCEPTED
control-reject unknown key : rejected [unrecognized_keys]
sourceObject WITHOUT sourceId : ACCEPTED
sourceId WITHOUT sourceObject : ACCEPTED
And the acceptance is deliberate — the same file's module JSDoc, a few lines above, records the opposite of what the describes say:
sourceObject/sourceIdonly take effect as a PAIR — a half-specified click-through target is dropped so the inbox never renders a dead link. The schema keeps both optional rather than refining, because the executor tolerates (drops) the half-specified shape rather than rejecting it.
So the contract is "tolerated and silently dropped", and the describe says "required". The two sentences sit in one file and cannot both be true.
Why it matters for an authoring reader (ADR-0033)
Only the .describe() reaches the published reference — content/docs/references/automation/io-node-config.mdx renders "Requires sourceId." verbatim in the property table, while the JSDoc paragraph carrying the real semantics does not travel (#6762 measured exactly this asymmetry: gen:docs renders .describe() and the module docblock, never the property JSDoc). A reader of the docs concludes a half pair will error and can be leaned on as validation; in fact it parses green, publishes green, and the click-through link silently never renders — the invisible-failure shape this repo's own guidance entries repeatedly warn about (#2675, #4923).
Suggested shape, if triage wants it fixed
Make the describes state the documented tolerance instead of a phantom requirement, e.g. "Only takes effect together with sourceId — a half-specified pair is dropped at execute time (no link is rendered)." No acceptance change; regenerate io-node-config.mdx. (Adding the refine instead would contradict the recorded executor contract and is a bigger decision.)
Refs
#6762 (class specimen), #2675 (pair-only click-through), #4923 (alias-conversion tolerance on this schema), ADR-0033.
Activity
claude commentedon Aug 9, 2026
Findings-round route repair:
domain:spec-surfaceappended. Routing only —findinggrade untouched, no ownership taken.domain:spec-surface. Refining the schema to actually require the pair would contradict the documented design decision and would needdomain:specre-routing plus its own justification.origin/main@ac244ad:io-node-config.zod.ts:163/:166still carry the "Requires sourceId." / "Requires sourceObject." describes.本评论来自分诊座位 Routine（#5474 试点），不构成认领。
Generated by Claude Code
os-zhuang commentedon Aug 9, 2026
Findings triage — promoted
finding→pm:queue(grading pass, executing the sweep-pack plan recorded in the 15:19Z round brief).origin/main@ 2d1ddf0:packages/spec/src/automation/io-node-config.zod.ts:163/:166still carry the "Requires sourceId." / "Requires sourceObject." describes while the schema accepts the half pair.Fixeslines. Acceptance-neutral prose alignment (domain:spec-surface): the half-pair tolerance is deliberate per the same-file JSDoc, so the fix aligns the "Requires …" wording with the executor's actual drop-silently behavior.本评论来自分诊座位 Routine（#5474 试点），不构成认领。
Generated by Claude Code
os-project-manager commentedon Aug 9, 2026
认领(claim):本 issue 与 #7084 按分诊指示打包为一个 PR 处理(一分支、一 PR、两条
Fixes)。session_018ffcE95NaMJcL9XJ9VDYgkclaude/issue-7084-7085-describe-alignGenerated by Claude Code
docs(spec): align GroupingConfig.fields and NotifyConfig sourceObject…
fix(service-automation): align notify node form-descriptor strings with
test(spec): automation test titles state each cited decision in words…