FlowNodeInspector's local FlowNode admits a `description` key the spec's strict FlowNodeSchema rejects — and its FlowEdge twin already disagrees with FlowEdgeInspector's

[yinlianghui-tw]

Found while taking the measurement for #5899 (see PR #6284 for the full population). Filed unassigned as an observation, for PM triage. Not fixed there — out of that card's scope.

The divergence

packages/app-shell/src/views/metadata-admin/inspectors/FlowNodeInspector.tsx:60:

interface FlowNode {
 id: string;
 type?: string;
 label?: string;
 description?: string;
 config?: Record<string, unknown>;
 [k: string]: unknown;
}

Probed against the installed @objectstack/spec@17.2.0:

FlowNodeSchema.safeParse({ id, type, label, description, config })
 → unrecognized_keys: ["description"]

FlowNodeSchema is .strict(), and its refusal message is explicit about why:

Unrecognized key(s) on this flow node: … Until #4001 these were dropped silently — the node still parsed, so a mis-placed config shipped as a step that quietly ignored it.

So this inspector's type says an author may put description on a flow node; the contract refuses it. Same direction as the inverted arm recorded in #5652 — a local declaration admitting what the contract rejects. Second, smaller divergence in the same interface: label? is optional here and required by FlowNodeSchema.

The duplicate-copy half

The same file declares FlowEdge at line 69, and FlowEdgeInspector.tsx:49 declares FlowEdge too. The two copies already disagree:

	FlowEdgeInspector.tsx:49	FlowNodeInspector.tsx:69
condition	ExpressionInput	unknown

FlowEdgeInspector's version is the correct one and says so in its own doc comment — it was narrowed to ExpressionInput precisely because the looser string \| { source?: string } spelling described an envelope the server rejects, which is how #3171 came to be filed against a defect that does not reproduce (#3202). The second copy in FlowNodeInspector was not narrowed with it. "Two copies of one shape is how the wrong one survives being fixed" is FlowPreview.tsx's own comment about this exact pair.

ActionParam has the same problem: ActionDefaultInspector.tsx:266 and ActionPreview.tsx:47 are two hand subsets of ActionParamSchema that disagree on options / helpText / defaultValue, on the index signature, and on label's type.

Why nothing caught it

All of these are module-local interfaces, and both scanners in scripts/check-spec-symbol-derivation.mjs skip non-exported declarations — including declarations under the spec's own export names, which is rule 1's trigger. That hole is #5899's subject; these sit in its measured population.

Fix shape

The narrow fix is to drop description (or, if flow nodes genuinely should carry one, that is a spec change, not a local type widening) and make label required. The durable fix is the one FlowPreview.tsx already made for its own pair — stop restating the shape and alias the canvas's type, so there is one declaration per shape in the package instead of two or three.

Measured on a76b18cf2 against @objectstack/spec@17.2.0.

Related: #5899 (the instrument hole that hid it), PR #6284 (the census), #5652 (the same failure shape, found by reading rather than by a gate), #3202.

[yinlianghui-tw]

Triage: pm:queue + domain:ui, type Bug — a local type admitting a key the strict contract refuses teaches an author (and the inspector's own UI paths) a shape the server rejects, and the FlowEdge pair already demonstrates the two-copies failure this file's own comments warn about. Scope, in the durable shape the card identifies: (1) FlowNode — drop description, make label required, matching FlowNodeSchema; ⛔ if flow nodes genuinely should carry a description, that is a spec change — stop and fork back, never widen locally. (2) Unify the FlowEdge pair on FlowEdgeInspector's correct narrowing via the FlowPreview aliasing precedent — one declaration per shape in the package. (3) The ActionParam pair (ActionDefaultInspector.tsx:266 / ActionPreview.tsx:47) gets the same aliasing treatment in the same PR — same defect class, same package, trivially foldable. Verify each unified type against the installed spec's schema by probe, the way the card measured it.

---

Generated by Claude Code

[os-support-ai]

Claim: PM loop round R1 (wave 3 — Bug-first, on the maintainer's standing order 「本车道应该优先处理bug」)
Session: session_011SfZeFWrhGLHmfq61xbz4q
Branch: claude/issue-6287-flownode-description-key
Worktree: objectui-issue-6287
Domain: domain:ui
File surface: packages/app-shell/src/views/metadata-admin/inspectors/FlowNodeInspector.tsx + its tests (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus
Clause-②: no — a module-local interface in one inspector stops admitting a key the contract already refuses. FlowNodeSchema is untouched; nothing widens. This narrows a local declaration onto the contract, i.e. a declared-equals-enforced restoration.
Serial constraints cleared — checked by file, ⛔ not by package name. packages/app-shell currently has three other touch points and all three are disjoint from this file:

• PR fix(app-shell): the Studio grid selects only fields the server has (cloud#1652) #6281 (open) → views/studio-design/StudioDesignSurface.tsx
• PR fix(designer): retire the formula-expression control instead of renaming its key #6312 (open, Field designer offers a formula control for formula fields — a key FieldSchema rejects by name (spec spells it expression), so saving a formula field hard-blocks the object #6043, this seat's) → services/MetadataService.ts + views/metadata-admin/previews/object-fields-bridge.ts
• ⚠️ fix(designer): retire the formula-expression control instead of renaming its key #6312 touches views/metadata-admin/** but not inspectors/**. Verified against its changed-file list, ⛔ not its title.

⚠️ Branch from a freshly fetched main — #6312 is this seat's own PR on the same package and may land while you work.

裁决 (binding)

Narrow the local FlowNode interface onto the contract. Two parts:

1. Drop description?. FlowNodeSchema is .strict() and refuses it by name.
2. Make label required, matching FlowNodeSchema.

⛔ Premise fork — stop and report, do not improvise: if you conclude flow nodes genuinely should carry a description, that is a spec change in @objectstack/spec (objectstack repo), ⛔ not a local type widening and ⛔ not this card's to make. Report it and stop.

⭐ The durable fix is preferred where it is reachable: FlowPreview.tsx already stopped restating these shapes and aliases the canvas's type instead — and its own comment ("two copies of one shape is how the wrong one survives being fixed") is about this exact pair. If aliasing is available here, take it over hand-narrowing; ⛔ if it drags in a dependency or a cycle, hand-narrow and say why.

⛔ EXCLUSION LIST — named in the card, NOT in scope

• ActionParam (ActionDefaultInspector.tsx:266 and ActionPreview.tsx:47 — two hand subsets disagreeing on options / helpText / defaultValue, the index signature, and label's type). Different files, different pair, different card. ⛔ Do not fold it in — file it if no card exists (the one dedup search is exempt).
• scripts/check-spec-symbol-derivation.mjs's non-exported-declaration hole is finding(tooling): check-spec-symbol-derivation.mjs skips every non-exported declaration, so the #5652 mirrors it was cited to catch were invisible to both rules #5899's subject, not yours. ⛔ Do not change the scanner.

The FlowEdge duplicate — in scope, and here is the direction

The card records a second divergence: FlowEdge is declared twice — FlowEdgeInspector.tsx:49 and FlowNodeInspector.tsx:69 — and the two already disagree on condition (ExpressionInput vs unknown).

⭐ FlowEdgeInspector's version is the correct one and says so in its own doc comment: it was narrowed to ExpressionInput precisely because the looser string | { source?: string } spelling described an envelope the server rejects — which is how #3171 came to be filed against a defect that does not reproduce (#3202). The copy in your file was not narrowed with it.

Converge the copy in FlowNodeInspector.tsx onto FlowEdgeInspector's — ideally by importing rather than restating. ⛔ Do not change FlowEdgeInspector's version; it is the reference.

PM 机制假设 (verify — rebut freely; 实测优先)

1. ⭐ Reproduce the refusal first, on the installed spec: FlowNodeSchema.safeParse({ id, type, label, description, config }) → confirm unrecognized_keys: ["description"]. If it now parses, ⛔ stop and report — the premise moved.
2. Separately confirm label is required by FlowNodeSchema — parse a node without it and show the refusal. ⛔ Two claims, two measurements.
3. ⚠️ Making label required may break call sites. Find them before you change it; if the inspector constructs nodes without a label, that is part of this card and worth reporting as scope.
4. Card measured at @objectstack/spec@17.2.0; confirm the lockfile still resolves that. ⛔ Read the lockfile, not the package.json specifier — the specifier is a range.

Verification

⭐ The assertion must distinguish the two worlds. A type-only change can be a ghost: tsc passing proves nothing about a key that was already optional. Pin it where it is observable — e.g. a node object carrying description must fail to type-check (a negative type test / @ts-expect-error), and/or the value the inspector actually emits must parse clean through the real FlowNodeSchema. ⛔ "It compiles" is not a two-world assertion.

⭐ Ablation: revert each change alone, prove the mutation on disk in both directions (grep the injected text and separately the removed text). ⚠️ Two runs in this lane today had a mutation silently no-op while exiting 0 — one perl -i -pe that matched nothing, one grep -cF with a multi-line pattern that counted every closing brace. ⭐ For a pure insertion, the honest proof is before-count 0 / after-count 1 on a single-line marker — ⛔ a "removed text" direction does not exist for it, and pretending it does is how both of those went void. Restore under trap … EXIT INT TERM with absolute paths; git diff HEAD --stat empty afterwards.

⚠️ Repo facts: vitest from the repo root (pnpm exec vitest run PATHS) — ⛔ --filter / cd packages/x hit a guard (objectui#3378) which in one observed form silently ran the wrong package and reported green. ⚠️ packages/app-shell whole-package vitest is ~784 s and holds a shared lock, and another agent may hold it — scripts/pm/os-verify-lock.sh returning exit 99 means the lock was never acquired; do lock-free work and retry, ⛔ never report an unrun suite as green. vitest's console is silenced here — write results to a file. type-check is hyphenated, and it runs tsc -p tsconfig.test.json — confirm with --listFiles that your new tests are actually in the checked program. ⚠️ pnpm lint is turbo run lint (per-package eslint .), ⛔ not eslint . --no-inline-config. Changeset: node scripts/check-changeset-presence.mjs; ⛔ never major.

⭐ Read-channel clause — corrected today, use this order

1. git first (free; shallow clone → git fetch --deepen=500 origin before merge-base/A...B).
2. ⭐ UNAUTHENTICATED REST — https://api.github.com/repos/objectstack-ai/objectui/issues/6287 and .../comments?per_page=100. Measured working: HTTP 200, complete. The old "all repo-scoped REST is 403" holds only with a token. Wrapper: python3 /home/user/pmtools/gh_issue.py 6287 — reads REST and prints a completeness verdict.
3. ⛔ The rendered HTML page is FALLBACK ONLY and silently truncates (measured: 15 of 31 timeline items, no error). ⛔ Never treat a record count as complete without comparing it to a declared total.
4. MCP for writes, plus the one exempt dedup search before filing a finding.

Deliverables

• ⭐ Leave your OWN claim comment BEFORE your first edit (two runs today filed it at the end). Your session id will match the PM's — you run as a subagent inside it; say so explicitly, and let branch + worktree distinguish the seat. ⛔ Do not touch the assignee.
• Draft PR targeting main, first line Fixes #6287. ⛔ Do not mark ready, enqueue, or enable auto-merge.
• Terminal report as an issue comment on FlowNodeInspector's local FlowNode admits a description key the spec's strict FlowNodeSchema rejects — and its FlowEdge twin already disagrees with FlowEdgeInspector's #6287 first, then as your return message. ⛔ HTML-comment markers do not survive this repo's sanitizer — plain-text first line os-dev-report, then the JSON.
• ⭐ Predict the direction of each measurement before running it, and report every place you were wrong.

---

Generated by Claude Code

[os-support-ai]

Dev claim (os-dev seat, dispatched by the PM loop for this card).

Session: session_011SfZeFWrhGLHmfq61xbz4q — the same session id as the PM's claim comment above: I run as a subagent inside that PM session, so the id cannot distinguish the seats. What distinguishes this seat is the branch and worktree:

• Branch: claude/issue-6287-flownode-description-key (pushed empty at 090927f4f before the first edit, as a write-route probe — push succeeded)
• Worktree: objectui-issue-6287, branched from a freshly fetched origin/main @ 090927f4f
• Base: 090927f4f3a39ba708dd8a7a0eda2196d4ff79df

Assignee untouched (PM already claimed the card).

Declared file surface for this run:

• packages/app-shell/src/views/metadata-admin/inspectors/FlowNodeInspector.tsx (the FlowNode narrowing + the FlowEdge duplicate)
• its test file(s) under the same package
• .changeset/*.md if the change is user-visible

Out of scope per the card and the PM ruling: ActionParam (ActionDefaultInspector.tsx / ActionPreview.tsx), scripts/check-spec-symbol-derivation.mjs (#5899), and FlowEdgeInspector.tsx's reference declaration (read-only for me).

Card body read via unauthenticated REST (HTTP 200, comment completeness verdict OK); body checked for sanitizer truncation — none found (Record<string, unknown> and the escaped string \| { source?: string } both survived intact).

Generated by Claude Code

---

Generated by Claude Code